Metadata-Version: 2.4
Name: context_logger_wrapper
Version: 0.0.2
Summary: Context Logger Wrapper
Home-page: https://github.com/maximz/context-logger-wrapper
Author: Maxim Zaslavsky
Author-email: maxim@maximz.com
License: MIT license
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: log-with-context
Requires-Dist: extendanything
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Context Logger Wrapper

[![](https://img.shields.io/pypi/v/context_logger_wrapper.svg)](https://pypi.python.org/pypi/context_logger_wrapper)
[![CI](https://github.com/maximz/context-logger-wrapper/actions/workflows/ci.yaml/badge.svg?branch=master)](https://github.com/maximz/context-logger-wrapper/actions/workflows/ci.yaml)
[![](https://img.shields.io/badge/docs-here-blue.svg)](https://context-logger-wrapper.maximz.com)
[![](https://img.shields.io/github/stars/maximz/context-logger-wrapper?style=social)](https://github.com/maximz/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

```bash
pip install context_logger_wrapper
```

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

For local development:

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

## Usage

```python
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

```bash
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.
