logging-blueprint

Environment-driven configuration for Python’s standard library logging module.

Overview

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_logger ergonomics
• 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.

Installation

pip install logging-blueprint

(Exact installation instructions may change depending on distribution method.)

Quick Start

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.

Examples

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 config
• PY_LOG_STREAM=stdout PY_LOG_STYLE=plain uv run python examples/devops_cli_demo.py — DevOps-style CLI mixing stdout and logs
• PY_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

Environment Variables

The following environment variables are supported:

Exact semantics and defaults are documented in the API reference.

Rust-Style Logging Directives

PY_LOG follows a Rust-inspired directive format:

info,myapp=debug,myapp.db=warning

• A bare level sets the default/root log level
• module=level entries override specific loggers
• Later directives override earlier ones

This maps directly onto Python logger names.

Using With Existing dictConfig / YAML

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.

API Overview

Core Entry Points

apply_env_logging(...)
build_dict_config_from_env(...)
merge_env_into_dict_config(...)

Parsing Utilities

EnvLoggingConfig.from_env(...)
parse_directives(...)

All public APIs are strictly typed.

Output Styles

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.

Design Goals

• 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

Non-Goals

• Replacing Python’s logging system
• Introducing a new logging API
• Providing transport, filtering, or routing beyond stdlib capabilities

Compatibility

• Python: v3.10+

Development Status

This project is currently:

• ☑ Experimental
• ☐ Beta
• ☐ Stable

APIs may change until a stable release is declared.

Contributing

Contribution guidelines, development setup, and code style are documented in: CONTRIBUTING.md.

License

Licensed under the MIT License.

See LICENSE for details.