logctx 0.0.0__tar.gz

logctx-0.0.0/.github/workflows/cicd.yml

@@ -0,0 +1,12 @@
+name: CICD
+
+on:
+  pull_request: {}
+
+jobs:
+  python-checks:
+    name: Python Quality Checks
+    uses: ./.github/workflows/python-checks.yml
+    with:
+      python-versions: '["3.9", "3.10", "3.11", "3.12", "3.13"]'
+    secrets: inherit

logctx-0.0.0/.github/workflows/python-checks.yml

@@ -0,0 +1,75 @@
+name: Python Quality Checks
+
+on:
+  workflow_call:
+    inputs:
+      python-versions:
+        required: true
+        type: string
+
+env:
+  UV_FROZEN: true
+
+jobs:
+  lint:
+    name: Ruff Lint (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ${{ fromJSON(inputs.python-versions) }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install lint dependencies
+        run: uv sync --group linting
+
+      - name: Run ruff
+        run: uv run ruff check .
+
+  typecheck:
+    name: Mypy Type Check (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ${{ fromJSON(inputs.python-versions) }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install type-checking dependencies
+        run: uv sync --group typechecking
+
+      - name: Run mypy
+        run: uv run mypy .
+
+  test:
+    name: Pytest (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ${{ fromJSON(inputs.python-versions) }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install test dependencies
+        run: uv sync --group testing
+
+      - name: Run tests
+        run: uv run pytest .

logctx-0.0.0/.github/workflows/release.yml

@@ -0,0 +1,152 @@
+name: Semantic Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  python-checks:
+    name: Python Quality Checks
+    uses: ./.github/workflows/python-checks.yml
+    with:
+      python-versions: '["3.9", "3.10", "3.11", "3.12", "3.13"]'
+    secrets: inherit
+
+  release:
+    name: Semantic Version Release
+    runs-on: ubuntu-latest
+    needs: python-checks
+    environment: release
+    concurrency:
+      group: ${{ github.workflow }}-release-${{ github.ref_name }}
+      cancel-in-progress: false
+
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - name: Setup | Checkout Repository on Release Branch
+        uses: actions/checkout@v4
+        # the checkout action persists the passed credentials by default
+        # subsequent git commands will pick them up automatically
+        with:
+          ref: ${{ github.ref_name }}
+          fetch-depth: 0 
+          token: ${{ secrets.RELEASE_PAT }}
+
+      - name: Setup | Force release branch to be at workflow sha
+        run: |
+          git reset --hard ${{ github.sha }}
+
+      - name: Evaluate | Verify upstream has NOT changed
+        shell: bash
+        run: |
+          set +o pipefail
+
+          UPSTREAM_BRANCH_NAME="$(git status -sb | head -n 1 | cut -d' ' -f2 | grep -E '\.{3}' | cut -d'.' -f4)"
+          printf '%s\n' "Upstream branch name: $UPSTREAM_BRANCH_NAME"
+
+          set -o pipefail
+
+          if [ -z "$UPSTREAM_BRANCH_NAME" ]; then
+              printf >&2 '%s\n' "::error::Unable to determine upstream branch name!"
+              exit 1
+          fi
+
+          git fetch "${UPSTREAM_BRANCH_NAME%%/*}"
+
+          if ! UPSTREAM_SHA="$(git rev-parse "$UPSTREAM_BRANCH_NAME")"; then
+              printf >&2 '%s\n' "::error::Unable to determine upstream branch sha!"
+              exit 1
+          fi
+
+          HEAD_SHA="$(git rev-parse HEAD)"
+
+          if [ "$HEAD_SHA" != "$UPSTREAM_SHA" ]; then
+              printf >&2 '%s\n' "[HEAD SHA] $HEAD_SHA != $UPSTREAM_SHA [UPSTREAM SHA]"
+              printf >&2 '%s\n' "::error::Upstream has changed, aborting release..."
+              exit 1
+          fi
+
+          printf '%s\n' "Verified upstream branch has not changed, continuing with release..."
+
+      - name: Action | Semantic Version Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v9.21.1
+        with:
+          github_token: ${{ secrets.RELEASE_PAT }}
+          git_committer_name: "github-actions"
+          git_committer_email: "actions@users.noreply.github.com"
+
+      - name: Publish | Upload to GitHub Release Assets
+        uses: python-semantic-release/publish-action@v9.21.1
+        with:
+          github_token: ${{ secrets.RELEASE_PAT }}
+          tag: ${{ needs.release.outputs.tag }}
+
+  build:
+    name: Build Distribution Packages
+    runs-on: ubuntu-latest
+    needs: release
+    environment: release
+
+    steps:
+      - name: Setup | Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup | Install Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+
+      - name: Build | Create Distribution Packages
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build
+      
+      - name: Upload | Upload Distribution Packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: logctx-distributions
+          path: dist/
+
+  testpypi:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    needs: build
+    environment: testpypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download | Download Distribution Packages
+        uses: actions/download-artifact@v4
+        with:
+          name: logctx-distributions
+          path: dist/
+
+      - name: Publish | Upload package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: testpypi
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download | Download Distribution Packages
+        uses: actions/download-artifact@v4
+        with:
+          name: logctx-distributions
+          path: dist/
+
+      - name: Publish | Upload package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

logctx-0.0.0/.gitignore

@@ -0,0 +1,26 @@
+# Virtual environments
+.venv/
+__pypackages__/
+
+# IDEs and editors
+.vscode/
+
+# Package distribution and build files
+*.egg-info/
+dist/
+/build/
+_build/
+
+# Python bytecode and cache files
+*.py[cod]
+.cache/
+.mypy_cache/
+.pytest_cache/
+/.ruff_cache/
+
+# Benchmark and test files
+.coverage
+
+# Other files and folders
+.python-version
+/sandbox/

logctx-0.0.0/CHANGELOG.md

@@ -0,0 +1,4 @@
+# CHANGELOG
+
+
+<!-- version list -->

logctx-0.0.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,39 @@
+[![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/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-0.0.0/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