Metadata-Version: 2.4
Name: stdlogkit
Version: 0.1.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 tiny, vLLM-independent wrapper around Python's standard
`logging` package.

Importing it configures standard logging immediately:

```python
import logging
import stdlogkit  # noqa: F401

logger = logging.getLogger(__name__)
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
```

## Features

- Uses only Python's standard `logging` machinery.
- Auto-configures logging on `import stdlogkit`.
- Configures the root logger by default, so normal `logging.getLogger(...)`
  calls work immediately.
- Adds `debug_once`, `info_once`, and `warning_once` to standard logger
  instances.
- Supports multiline log alignment.
- Supports ANSI colors with `auto`, forced-on, and forced-off modes.
- Supports custom JSON config through `logging.config.dictConfig`.
- Includes optional uvicorn access-log filtering helpers.
- Has no runtime dependency on vLLM or any other third-party package.

## Environment Variables

| Variable | Default | Description |
| --- | --- | --- |
| `STDLOGKIT_CONFIGURE_LOGGING` | `1` | Set `0` to disable auto configuration. |
| `STDLOGKIT_LOGGING_LEVEL` | `INFO` | Root or named logger 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` | empty | Configure a named logger instead of root. |
| `STDLOGKIT_ROOT_DIR` | current working directory | Base path for relative file display. |
| `STDLOGKIT_SHOW_REL_PATH` | `debug` | `debug`, `always`, or `never`. |
| `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"
    }
  },
  "root": {
    "handlers": ["console"],
    "level": "INFO"
  }
}
```

Run with:

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

## Named Logger Mode

By default, stdlogkit configures the root logger. If you want behavior closer
to a framework-specific logger, configure only a named logger:

```bash
STDLOGKIT_LOGGER_NAME=my_app python app.py
```

Then loggers under `my_app.*` propagate to that logger:

```python
import logging
import stdlogkit  # noqa: F401

logger = logging.getLogger("my_app.service")
logger.info("hello")
```

## Development

```bash
cd standalone_logging_pkg
uv venv --python 3.12
uv pip install -e ".[dev]"
.venv/bin/python -m pytest -q
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"
```
