logctx 0.0.0__py3-none-any.whl

logctx/__init__.py

@@ -0,0 +1,32 @@
+"""logctx package
+
+This package provides a convenient way to manage logging contexts in Python.
+
+It allows you to manage key-value pairs for log-contexts which can be automatically
+added to log messages within their respective context.
+"""
+
+__author__ = "Alexander Schulte"
+__maintainer__ = "Alexander Schulte"
+
+__version__ = "0.0.0"
+
+from logctx import decorators
+from logctx._core import (
+    ContextInjectingLoggingFilter,
+    LogContext,
+    clear,
+    get_current,
+    new_context,
+    update,
+)
+
+__all__ = [
+    "ContextInjectingLoggingFilter",
+    "LogContext",
+    "clear",
+    "get_current",
+    "new_context",
+    "update",
+    "decorators",
+]

logctx/_core.py

@@ -0,0 +1,165 @@
+import contextvars
+import dataclasses
+import logging
+from contextlib import contextmanager
+from typing import Any, Generator, Mapping, Optional
+
+__all__: list[str] = [
+    "LogContext",
+    "get_current",
+    "new_context",
+    "update",
+    "clear",
+    "ContextInjectingLoggingFilter",
+]
+
+
+@dataclasses.dataclass(frozen=True)
+class LogContext:
+    """Dataclass holding information about one specific log context.
+
+    This class is used to store key-value pairs that are relevant for the
+    current logging context. It is designed to be immutable to prevent
+    accidental mutations by users.
+
+    If you want to update the context, use `logctx.update()` or `logctx.new_context()`.
+
+    Attributes:
+        data (Mapping[str, Any]): A mapping of key-value pairs representing
+            the context data.
+    """
+
+    data: Mapping[str, Any] = dataclasses.field(default_factory=dict)
+
+    def with_values(self, **kwargs) -> "LogContext":
+        """Create a new context with additional key-value pairs.
+
+        This method returns a new instance of LogContext with the current
+        context data merged with the provided key-value pairs. Duplicate keys
+        will be overwritten by the new values.
+
+        Caution:
+            This method does not affect the current active context, meaning that the
+            resulting context will not be included in any log messages.
+
+        Args:
+            **kwargs: Key-value pairs to be added to the new context.
+        Returns:
+            LogContext: A new instance of LogContext with the merged data.
+        """
+
+        return LogContext({**self.data, **kwargs})
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the context to a dictionary."""
+
+        return dict(self.data)
+
+
+_mdc_context: contextvars.ContextVar[LogContext] = contextvars.ContextVar("_mdc_context")
+
+
+# TODO: return None or raise on no context
+def get_current() -> LogContext:
+    """Retrieve current context.
+
+    This function retrieves the current logging context from the context
+    variable. If no context is found, it returns an empty LogContext
+    instance.
+
+    Returns:
+        LogContext: The current logging context.
+    """
+    try:
+        return _mdc_context.get()
+    except LookupError:
+        return LogContext()
+
+
+@contextmanager
+def new_context(**kwargs) -> Generator[LogContext, None, None]:
+    """Create a new context with the provided key-value pairs.
+
+    The new context inherits all key-value pairs from the current context and
+    adds the provided pairs. Duplicate keys will be overwritten by the new values.
+
+    Args:
+        **kwargs: Key-value pairs to be included in the new context.
+
+    Yields:
+        LogContext: The new logging context.
+    """
+
+    current_log_ctx: LogContext = get_current()
+    new_log_ctx = current_log_ctx.with_values(**kwargs)
+    token = _mdc_context.set(new_log_ctx)
+    try:
+        yield new_log_ctx
+    finally:
+        _mdc_context.reset(token)
+
+
+def update(**kwargs) -> LogContext:
+    """Append key-value pairs to the current context.
+
+    Duplicate keys will be overwritten by the new values.
+
+    Will not affect log calls in current context made before the update.
+
+    Args:
+        **kwargs: Key-value pairs to be added to the current context.
+
+    Returns:
+        LogContext: The updated logging context with the appended key-value
+            pairs.
+    """
+    current_log_ctx = get_current()
+    updated_log_ctx = current_log_ctx.with_values(**kwargs)
+    _mdc_context.set(updated_log_ctx)
+
+    return updated_log_ctx
+
+
+def clear() -> None:
+    """Clear the current context.
+
+    Only affects current context. After leaving current context, the context
+    will be reset to its previous state.
+
+    Example:
+    ```python
+    with logctx.new_context(a=1, b=2):
+        with logctx.new_context(c=3):
+            # Context is now: {'a': 1, 'b': 2, 'c': 3}
+            logctx.clear()
+            # Context is now: {}
+        # Context is now: {'a': 1, 'b': 2}
+    ```
+    """
+    _mdc_context.set(LogContext())
+
+
+class ContextInjectingLoggingFilter(logging.Filter):
+    """Logging filter that injects the current context into log records.
+
+    Attributes:
+        name (str): The name of the filter. This is used to identify the
+            filter in the logging system.
+
+        output_field (str): The name of the field in the log record where the
+            context data will be injected. If not provided, the context data
+            will be injected into the log record as root level attributes.
+    """
+
+    def __init__(self, name: str = "", output_field: Optional[str] = None) -> None:
+        super().__init__(name=name)
+        self._output_field: Optional[str] = output_field
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        context: LogContext = get_current()
+        if self._output_field is not None:
+            setattr(record, self._output_field, context.to_dict())
+        else:
+            for k, v in context.to_dict().items():
+                setattr(record, k, v)
+        return True

logctx/decorators.py

@@ -0,0 +1,187 @@
+"""Decorators for function based context injection.
+
+This module provides decorators for injecting static context or function arguments
+into functions and methods.
+
+The decorators automatically create a new context around the
+decorated function, including all provided keyword arguments into the new context.
+"""
+
+import inspect
+from collections.abc import Callable, Generator
+from functools import wraps
+from typing import AsyncGenerator, Awaitable, Optional, TypeVar
+
+from typing_extensions import ParamSpec
+
+from logctx import _core
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+def _sync_wrapper(func: Callable[_P, _R], **static_context) -> Callable[_P, _R]:
+    """Context wrapper for synchronous functions."""
+
+    @wraps(func)
+    def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+        with _core.new_context(**static_context):
+            return func(*args, **kwargs)
+
+    return wrapper
+
+
+def _async_wrapper(
+    func: Callable[_P, Awaitable[_R]], **static_context
+) -> Callable[_P, Awaitable[_R]]:
+    """Context wrapper for async functions."""
+
+    @wraps(func)
+    async def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+        with _core.new_context(**static_context):
+            return await func(*args, **kwargs)
+
+    return wrapper
+
+
+_GenYield = TypeVar("_GenYield")
+_GenSend = TypeVar("_GenSend")
+_GenReturn = TypeVar("_GenReturn")
+
+
+def _sync_generator_wrapper(
+    func: Callable[_P, Generator[_GenYield, _GenSend, _GenReturn]], **static_context
+) -> Callable[_P, Generator[_GenYield, _GenSend, _GenReturn]]:
+    """Context wrapper for synchronous generators."""
+
+    @wraps(func)
+    def wrapper(
+        *args: _P.args, **kwargs: _P.kwargs
+    ) -> Generator[_GenYield, _GenSend, _GenReturn]:
+        gen = func(*args, **kwargs)
+        with _core.new_context(**static_context):
+            first_element: _GenYield = next(gen)
+
+        to_send: _GenSend = yield first_element
+
+        while True:
+            try:
+                with _core.new_context(**static_context):
+                    to_yield: _GenYield = gen.send(to_send)
+
+            except StopIteration as e:
+                # since PEP 479 generators should gracefully return a value without
+                # raising StopIteration.
+                return e.value
+            else:
+                to_send = yield to_yield
+
+    return wrapper
+
+
+def _async_generator_wrapper(
+    func: Callable[_P, AsyncGenerator[_GenYield, _GenSend]], **static_context
+):
+    @wraps(func)
+    async def wrapper(
+        *args: _P.args, **kwargs: _P.kwargs
+    ) -> AsyncGenerator[_GenYield, _GenSend]:
+        gen = func(*args, **kwargs)
+
+        with _core.new_context(**static_context):
+            first_element: _GenYield = await gen.__anext__()
+
+        to_send: _GenSend = yield first_element
+
+        while True:
+            try:
+                with _core.new_context(**static_context):
+                    to_yield: _GenYield = await gen.asend(to_send)
+            except StopAsyncIteration:
+                return
+            else:
+                to_send = yield to_yield
+
+    return wrapper
+
+
+def inject_context(**static_context):
+    """Decorator injecting static context into a function.
+
+    This decorator will automatically create a new context around the decorated function
+    including all provided keyword arguments into the new context.
+
+    Args:
+        **static_context: Keyword arguments representing the static context
+            to be injected.
+    """
+
+    def _decorator(func):
+        if inspect.isgeneratorfunction(func):
+            return _sync_generator_wrapper(func, **static_context)
+
+        elif inspect.isasyncgenfunction(func):
+            return _async_generator_wrapper(func, **static_context)
+
+        elif inspect.iscoroutinefunction(func):
+            return _async_wrapper(func, **static_context)
+
+        elif inspect.isfunction(func):
+            return _sync_wrapper(func, **static_context)
+
+        else:
+            raise TypeError(
+                f"Unsupported function type: {type(func)}. "
+                "Function must be a coroutine, generator, or regular function."
+            )
+
+    return _decorator
+
+
+def log_arguments(args: Optional[list[str]] = None, **kwargs):
+    """Decorator for auto-injecting function arguments into log context.
+
+    This decorator will automatically create a new context around the decorated function
+    including specified function arguments into the new context.
+
+    Args:
+        args (list[str], optional): A list of function argument names to log.
+            Each argument will be injected into the context with its normal key.
+        **kwargs: A mapping of function argument names to context keys.
+
+    Raises:
+        ValueError: If any specified argument is not found in the function's signature.
+    """
+    args = args or []
+
+    def decorator(func: Callable[_P, _R]) -> Callable[_P, _R]:
+        func_params = inspect.signature(func).parameters
+        for arg in args:
+            if arg not in func_params:
+                raise ValueError(
+                    f"Argument '{arg}' not found in the function's signature."
+                )
+        for arg in kwargs:
+            if arg not in func_params:
+                raise ValueError(
+                    f"Argument '{arg}' not found in the function's signature."
+                )
+
+        @wraps(func)
+        def wrapper(*func_args: _P.args, **func_kwargs: _P.kwargs) -> _R:
+            signature = inspect.signature(func)
+            bound = signature.bind(*func_args, **func_kwargs)
+            bound.apply_defaults()
+
+            context_data = {}
+            for arg in args:
+                context_data[arg] = bound.arguments[arg]
+            for arg, dest in kwargs.items():
+                context_data[dest] = bound.arguments[arg]
+
+            with _core.new_context(**context_data):
+                return func(*func_args, **func_kwargs)
+
+        return wrapper
+
+    return decorator

logctx-0.0.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: logctx
+Version: 0.0.0
+Summary: Management and injection of contextual variables into log messages.
+Author: Alexander Schulte
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aschulte201/logctx
+Project-URL: Source, https://github.com/aschulte201/logctx
+Project-URL: Documentation, https://github.com/aschulte201/logctx/blob/README.md
+Project-URL: Changelog, https://github.com/aschulte201/logctx/blob/CHANGELOG.md
+Keywords: logging,context,log,logger,logctx,log-context
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions>=4.12
+Dynamic: license-file
+
+[![CICD](https://github.com/aschulte201/logctx/actions/workflows/cicd.yml/badge.svg?branch=main)](https://github.com/aschulte201/logctx/actions/workflows/cicd.yml)
+
+## Enabling
+
+The core module provides a `logging.Filter` subclass designed to inject the current active context into any log messages.
+
+Below is a demo usage on how to enable context injection:
+
+```python
+import logging
+import logctx
+
+root_logger = logging.getLogger()
+console_handler = logging.StreamHandler()
+
+formatter = jsonlogger.JsonFormatter("%(logctx)s")
+context_filter = ContextInjectingLoggingFilter(output_field="logctx")
+
+console_handler.setFormatter(formatter)
+console_handler.addFilter(context_filter)
+
+root_logger.addHandler(console_handler)
+logger.setLevel(logging.DEBUG)
+```
+
+# Generators
+* During execution
+* Between yields
+
+## Log Arguments
+* Raises during initializtaion
+* Value Error
+* Able to rename args
+* Unable to extract from kwargs
+* Unable to work on generators
+* Unable to work on async functions
+
+# update
+* can change root context

logctx-0.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+logctx/__init__.py,sha256=ykMLP_N00UDG1NTo3efsNuK8b3Z9U7yiYB58jSH1iWQ,655
+logctx/_core.py,sha256=rUvs_6Kxq-IrWMeVxIav4sJlNAZC0CG5W4e3thl8XoM,5042
+logctx/decorators.py,sha256=MWvIbQPLn1gtBJw8l9EFK72kQR2Gsuq5AuazD4WdgiE,5942
+logctx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+logctx-0.0.0.dist-info/licenses/LICENSE,sha256=IkyD1DVxC2xxRy7n0jM5t1WUT-zply0h_Uv34hJPbEs,1082
+logctx-0.0.0.dist-info/METADATA,sha256=3UiNUrPiRCfaOBMb2dbuyfGPlRyKSqII_37hYsYa22Q,2289
+logctx-0.0.0.dist-info/WHEEL,sha256=DnLRTWE75wApRYVsjgc6wsVswC54sMSJhAEd4xhDpBk,91
+logctx-0.0.0.dist-info/top_level.txt,sha256=9vWyBBL40SUsnQbX02ztlfBFgwg5Dv_1dndj-p9CY7w,7
+logctx-0.0.0.dist-info/RECORD,,

logctx-0.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.4.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

logctx-0.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Alexander Schulte.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

logctx-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+logctx