Context Logger Wrapper

context_logger_wrapper is a small Python package for adding scoped context to standard logging output, including messages emitted through warnings.warn.

It wraps a normal logging.Logger with log-with-context support while keeping the underlying logger's attributes and methods available through passthroughs. That lets existing logging setup keep using handlers, propagation, filters, and formatters while application code adds contextual fields around blocks of work.

Why It Exists

Python warnings can be routed into logging with logging.captureWarnings(True), but the resulting py.warnings logger is just a regular logger. This package adds a wrapper and a warning hook so warnings can receive the same context as normal log calls.

The context is attached through logging extra fields. To see those fields in output, configure a formatter that renders them, such as a JSON formatter that includes extra record attributes.

Installation

pip install context_logger_wrapper

The package requires Python 3.8 or newer and depends on log-with-context and extendanything.

For local development:

pip install -r requirements_dev.txt
pip install -e .

Usage

import logging
import warnings

from context_logger_wrapper import (
    ContextLoggerWrapper,
    capture_warnings_with_context,
)
from log_with_context import add_logging_context

logger = ContextLoggerWrapper(name=__name__)

# Equivalent when you already have a logger:
# logger = ContextLoggerWrapper(logger=logging.getLogger(__name__))

# Optional: route warnings.warn(...) through a context-aware py.warnings logger.
capture_warnings_with_context()

with add_logging_context(request_id="abc123"):
    logger.info("started")

    with add_logging_context(step="load-data"):
        logger.info("running step", extra={"attempt": 1})
        warnings.warn("example warning")

How It Works

ContextLoggerWrapper subclasses log_with_context.Logger and initializes it with either a logger name or an existing logging.Logger. It also stores the wrapped base logger in ExtendAnything, so unknown attributes are forwarded to the underlying logger.

capture_warnings_with_context() replaces warnings.showwarning with a hook that formats warnings and logs them through a wrapped logging.getLogger("py.warnings"). If a warning is explicitly directed to a file object, the hook delegates back to the original warnings.showwarning.

Nested add_logging_context(...) blocks accumulate context for log records created inside them.

Behavior and Limitations

• The package does not install or configure logging handlers or formatters.
• Warning capture changes process-global warning behavior by replacing warnings.showwarning.
• The source notes successful use with joblib.Parallel multiprocessing and threading backends, with mixed results for the loky backend.

Development

make test
make lint
make docs

The repository also includes Sphinx documentation configuration and CI settings for tests, linting, package publishing, and optional docs deployment.

Changelog

0.0.1

• First release on PyPI.