Environment-driven configuration for Python’s standard library
loggingmodule.
logging-blueprint is a small, stdlib-first library for configuring Python’s built-in
logging module using environment variables.
The library is designed to be:
- Drop-in — integrates directly with
logging.config.dictConfig - Environment-driven — inspired by Rust’s
env_loggerergonomics - Non-invasive — augments existing logging configurations instead of replacing them
- Strictly typed — intended for use in modern, typed Python codebases
logging-blueprint does not introduce a new logging framework.
It exists solely to make configuration of the standard library logging system easier,
more composable, and more production-friendly.
pip install logging-blueprint(Exact installation instructions may change depending on distribution method.)
import logging_blueprint
logging_blueprint.apply_env_logging()This reads logging configuration from environment variables and applies it directly to Python’s standard library logging system.
Run the demo scripts with uv run to see the library in action:
uv run python examples/basic_quickstart.py— minimal quick start using env-driven configPY_LOG_STREAM=stdout PY_LOG_STYLE=plain uv run python examples/devops_cli_demo.py— DevOps-style CLI mixing stdout and logsPY_LOG=debug PY_LOG_STREAM=stdout PY_LOG_STYLE=plain uv run python examples/asgi_app_demo.py— tiny ASGI app emitting request lifecycle logs
The following environment variables are supported:
| Variable | Description |
|---|---|
PY_LOG |
Logging directives (e.g. info,myapp=debug) |
PY_LOG_STYLE |
Output style (plain, pretty, logfmt, json, auto) |
PY_LOG_STREAM |
Output stream (stdout or stderr) |
PY_LOG_FMT |
Log format string (plain/pretty/logfmt styles) |
PY_LOG_DATEFMT |
Datetime format string |
PY_LOG_DISABLE_EXISTING |
Disable existing loggers (1 or 0) |
Exact semantics and defaults are documented in the API reference.
PY_LOG follows a Rust-inspired directive format:
info,myapp=debug,myapp.db=warning
- A bare level sets the default/root log level
module=levelentries override specific loggers- Later directives override earlier ones
This maps directly onto Python logger names.
logging-blueprint is designed to work alongside existing logging configurations.
import logging.config
import logging_blueprint
base_config = {
# existing dictConfig-style configuration
}
config = logging_blueprint.merge_env_into_dict_config(base_config)
logging.config.dictConfig(config)This allows environment variables to override or extend static configurations without duplicating configuration logic.
apply_env_logging(...)
build_dict_config_from_env(...)
merge_env_into_dict_config(...)EnvLoggingConfig.from_env(...)
parse_directives(...)All public APIs are strictly typed.
logging-blueprint supports multiple output styles:
- plain — standard
logging.Formatter - pretty — human-readable output with ANSI colors and extras
- logfmt — key=value output with extras, colorized on TTY
- json — structured JSON suitable for log aggregation
- auto — selects an appropriate style based on environment
Exact formatting behavior is intentionally minimal and configurable.
- Use the Python standard library wherever possible
- Avoid hidden global state
- Avoid opinionated logging frameworks
- Preserve compatibility with existing logging setups
- Be explicit, inspectable, and boring in production
- Replacing Python’s logging system
- Introducing a new logging API
- Providing transport, filtering, or routing beyond stdlib capabilities
- Python: v3.10+
This project is currently:
- ☑ Experimental
- ☐ Beta
- ☐ Stable
APIs may change until a stable release is declared.
Contribution guidelines, development setup, and code style are documented in: CONTRIBUTING.md.
Licensed under the MIT License.
See LICENSE for details.