Metadata-Version: 2.4
Name: structlog-configfile
Version: 1.0.0rc1
Summary: Structlog Configurator Helper
Project-URL: Homepage, https://github.com/johnvox/structlog-configfile
Project-URL: Issues, https://github.com/johnvox/structlog-configfile/issues
License-Expression: MIT
License-File: LICENSE
Keywords: log,logging,structure,structured
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: System :: Logging
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jinja2-getenv-extension>=1.0.3
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: structlog>=25.5.0
Requires-Dist: toml>=0.10.2
Requires-Dist: ujson>=5.13.0
Description-Content-Type: text/markdown

# structlog-configfile

Helpers to configure structlog together with standard-library logging from a small configuration module.

## Installation

```bash
pip install structlog-configfile
```

## Quick start

Replace the standard structlog logger factory with the package helper:

```python
import structlog_configfile

logger = structlog_configfile.get_logger()
logger.info("hello", user="alice")
```

This loads the built-in defaults and configures both structlog and stdlib logging.

## Using a custom configuration module

You can point the helper at your own Python configuration module:

```python
import structlog_configfile

logger = structlog_configfile.get_logger(config_file="path/to/my_config.py"[, struct_log_logger_args])
```

You can also set the environment variable `STRUCTLOG_CONFIG_FILE` to avoid passing the path explicitly.

Example configuration module:

```python
from pathlib import Path
import structlog

logging_config_file = Path(__file__).parent.joinpath("logging.yaml")

pre_process_processors = [
    structlog.processors.TimeStamper(fmt="iso"),
]

structlog_processors = []
logging_processors = []
post_process_processors = []
renderer = structlog.processors.JSONRenderer()
handleStdlib = True
```

## Supported configuration knobs

The configuration module can define the following values:

- `logging_config_file`: path to the stdlib logging configuration file (https://docs.python.org/3/library/logging.config.html)
- `pre_process_processors`: processors applied before other processors
- `structlog_processors`: processors used for structlog logs
- `logging_processors`: processors used for stdlib logging
- `post_process_processors`: processors applied after all others
- `renderer`: the final renderer used by the logging formatter
- `stdlib_preprocessor`: processors for stdlib log preparation
- `stdlib_processor`: processors for stdlib log handling
- `stdlib_postprocessor`: processors applied after stdlib processing
- `embeds_std_lib`: enable or disable stdlib logging setup

## Logging configuration file formats

The file referenced by `logging_config_file` can be a Jinja template or a YAML, JSON, or TOML file. The package will load it and use it for stdlib logging configuration.

## Notes

The package exposes both `get_logger()` and `getLoger()` for compatibility.
