Metadata-Version: 2.4
Name: simpac-logger
Version: 0.1.2
Summary: Colored console + daily file logger for Python, zero dependencies
Author: SIMPAC AI LAB
Project-URL: Repository, https://github.com/simpac-ai-lab/simpac-logger
Project-URL: Issues, https://github.com/simpac-ai-lab/simpac-logger/issues
Project-URL: Changelog, https://github.com/simpac-ai-lab/simpac-logger/blob/main/CHANGELOG.md
Keywords: logging,logger,color,ansi,daily,file
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Logging
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# simpac-logger

[![CI](https://github.com/simpac-ai-lab/simpac-logger/actions/workflows/ci.yml/badge.svg)](https://github.com/simpac-ai-lab/simpac-logger/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/simpac-logger)](https://pypi.org/project/simpac-logger/)
![Python](https://img.shields.io/badge/python-3.8%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

A Python logger you set up in one line: **colored console output by level** plus a
**daily log file under `logs/`**. Standard library only, no dependencies.

```python
from simpac_logger import get_logger

log = get_logger(__name__)

log.debug("detailed information")   # blue
log.info("general information")
log.success("task completed")        # green
log.warning("something to watch")    # orange
log.error("something failed")        # red
log.critical("fatal error")          # bold red
```

Console:

```
15:04:12 | DEBUG    | myapp | detailed information
15:04:12 | INFO     | myapp | general information
15:04:12 | SUCCESS  | myapp | task completed
15:04:12 | WARNING  | myapp | something to watch
15:04:12 | ERROR    | myapp | something failed
15:04:12 | CRITICAL | myapp | fatal error
```

`logs/2026-09-07.log` (no color codes):

```
2026-09-07 15:04:12.031 | DEBUG    | myapp | detailed information
2026-09-07 15:04:12.031 | INFO     | myapp | general information
2026-09-07 15:04:12.032 | SUCCESS  | myapp | task completed
...
```

## Installation

```bash
pip install simpac-logger
```

In `requirements.txt`:

```
simpac-logger>=0.1.2
```

To install straight from GitHub instead, for example to try an unreleased commit:

```bash
pip install git+https://github.com/simpac-ai-lab/simpac-logger.git@main
```

## Usage

### `get_logger()` arguments

| Argument | Default | Description |
|---|---|---|
| `name` | `"simpac"` | Logger name, usually `__name__`. Calling again with the same name does not add handlers; it only updates the levels |
| `level` | `"DEBUG"` | Minimum level for console output, as a string or an int |
| `log_dir` | `"logs"` | Directory for log files, created if missing. Can also be set with the `SIMPAC_LOG_DIR` environment variable |
| `to_file` | `True` | `False` disables the file handler |
| `file_level` | `"DEBUG"` | Minimum level written to the file |
| `color` | `None` | `None` auto-detects; `True`/`False` forces the choice |
| `stream` | `sys.stdout` | Console output stream; pass `sys.stderr` to switch |

```python
# INFO and above on the console, everything in the file, custom directory
log = get_logger("crawler", level="INFO", log_dir="output/logs")

# console only
log = get_logger("quick", to_file=False)
```

### Levels

| Level | Value | Color |
|---|---|---|
| DEBUG | 10 | blue |
| INFO | 20 | default |
| **SUCCESS** | **25** | green |
| WARNING | 30 | orange |
| ERROR | 40 | red |
| CRITICAL | 50 | bold white on red |

`SUCCESS` is added by this package. Use `level="SUCCESS"` to hide INFO messages while
keeping success messages visible.

### Color detection

1. `NO_COLOR` is set: always off
2. `FORCE_COLOR` is set: always on
3. `TERM=dumb`: off
4. Jupyter (ipykernel) output stream: on
5. Otherwise on only when the stream is a TTY, so colors disappear automatically when piped or redirected

On Windows 10 and later the console's ANSI mode is enabled automatically.

### Daily files

- File names follow `logs/YYYY-MM-DD.log` in local time.
- A process running past midnight writes subsequent records to the new day's file.
- Multiple runs on the same day append to the same file.
- Add `logs/` to your `.gitignore`.

### Working with existing `logging` code

`get_logger()` returns a subclass of the standard `logging.Logger`. If a logger with the
same name was already created with `logging.getLogger(__name__)`, `get_logger(__name__)`
attaches the handlers and a `success()` method to that existing logger.

## Development

```bash
conda create -n simpac-logger python=3.12 -y
conda activate simpac-logger
pip install -e ".[dev]"
pytest
python examples/demo.py
```

### Releasing

1. Bump `version` in `pyproject.toml` and add a section to `CHANGELOG.md`.
2. Commit and push to `main`.
3. Tag and push the tag:

   ```bash
   git tag -a v0.1.2 -m "simpac-logger 0.1.2"
   git push origin v0.1.2
   ```

The `Publish` workflow checks that the tag matches the version, builds the package, uploads
it to TestPyPI and then PyPI through Trusted Publishing, and creates a GitHub release with
the built files. A version number can never be re-used on PyPI, so fix mistakes with a new
patch release.

## License

MIT
