Metadata-Version: 2.4
Name: stdlogkit
Version: 0.2.0
Summary: A small stdlib logging auto-configuration kit with colored multiline logs and log-once helpers.
Author-email: Your Name <you@example.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/your-org/stdlogkit
Project-URL: Repository, https://github.com/your-org/stdlogkit
Project-URL: Issues, https://github.com/your-org/stdlogkit/issues
Keywords: logging,stdlib,colored-logs,python-logging
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"

# stdlogkit

`stdlogkit` is a vLLM-style, vLLM-independent wrapper around Python's
standard `logging` package.

Importing it configures logging immediately. Like vLLM, the default
configuration installs a handler on a named root logger, `stdlogkit`, and child
loggers propagate to it.

```python
import stdlogkit

logger = stdlogkit.init_logger("stdlogkit.app")
logger.info("hello")
logger.warning_once("this warning appears once")
```

Default output:

```text
INFO 06-24 12:00:01 [example.py:5] hello
WARNING 06-24 12:00:01 [example.py:6] this warning appears once
```

The default format intentionally does not include process name or PID, matching
vLLM. Single-process and multiprocessing logs therefore use the same fields.

## vLLM Compatibility

This package mirrors vLLM's logging behavior while remaining fully decoupled:

- Uses `logging.config.dictConfig`.
- Configures one named logger by default, `stdlogkit`, with `propagate=false`.
- Child loggers such as `stdlogkit.app` have no handler and propagate upward.
- `init_logger(name)` patches `debug_once`, `info_once`, and `warning_once`
  onto that returned logger instance.
- `*_once` uses `functools.lru_cache`, so arguments must be hashable, as in
  vLLM.
- Multiline logs are aligned with the same prefix strategy as vLLM.
- Color constants match vLLM exactly.

## Colors

The ANSI color values are identical to vLLM:

| Level/field | ANSI code |
| --- | --- |
| `DEBUG` | `\033[37m` |
| `INFO` | `\033[32m` |
| `WARNING` | `\033[33m` |
| `ERROR` | `\033[31m` |
| `CRITICAL` | `\033[35m` |
| timestamp and file info | `\033[90m` |
| reset | `\033[0m` |

## Environment Variables

| Variable | Default | Description |
| --- | --- | --- |
| `STDLOGKIT_CONFIGURE_LOGGING` | `1` | Set `0` to disable auto configuration. |
| `STDLOGKIT_LOGGING_LEVEL` | `INFO` | Named logger and handler level. |
| `STDLOGKIT_LOGGING_STREAM` | `ext://sys.stdout` | Handler stream. |
| `STDLOGKIT_LOGGING_PREFIX` | empty | Prefix prepended to every log line. |
| `STDLOGKIT_LOGGING_COLOR` | `auto` | `auto`, `1`, or `0`. |
| `STDLOGKIT_LOGGING_CONFIG_PATH` | unset | Path to a JSON `dictConfig` file. |
| `STDLOGKIT_LOGGER_NAME` | `stdlogkit` | Named logger to configure. |
| `NO_COLOR` | `0` | Standard flag to disable ANSI colors. |

## Custom JSON Config

```json
{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "plain": {
      "class": "stdlogkit.formatter.NewLineFormatter",
      "format": "%(levelname)s %(asctime)s [%(fileinfo)s:%(lineno)d] %(message)s",
      "datefmt": "%m-%d %H:%M:%S"
    }
  },
  "handlers": {
    "console": {
      "class": "logging.StreamHandler",
      "formatter": "plain",
      "level": "INFO",
      "stream": "ext://sys.stdout"
    }
  },
  "loggers": {
    "stdlogkit": {
      "handlers": ["console"],
      "level": "INFO",
      "propagate": false
    }
  }
}
```

Run with:

```bash
STDLOGKIT_LOGGING_CONFIG_PATH=/path/to/logging.json python app.py
```

## Development

```bash
cd standalone_logging_pkg
uv venv --python 3.12
uv pip install -e ".[dev]"
PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v
uv build
```

## Publish to PyPI

Before publishing, make sure the project name in `pyproject.toml` is available
on PyPI and replace the placeholder author/repository metadata.

```bash
cd standalone_logging_pkg
uv build
uv publish --token "$PYPI_TOKEN"
```

For TestPyPI:

```bash
uv publish --publish-url https://test.pypi.org/legacy/ --token "$TEST_PYPI_TOKEN"
```
