mixin-logging 0.5.0__tar.gz

mixin_logging-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install ${{ matrix.python-version }}
+      - name: Sync dependencies
+        run: uv sync --all-extras
+      - name: Test
+        run: uv run pytest -v --cov --cov-fail-under=95
+
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install Python 3.12
+        run: uv python install 3.12
+      - name: Sync dependencies
+        run: uv sync --all-extras
+      - name: Type-check
+        run: uv run mypy mixin_logging/
+

mixin_logging-0.5.0/.github/workflows/cleanup-guard.yml

@@ -0,0 +1,63 @@
+name: Cleanup Guard
+
+on:
+  pull_request
+
+jobs:
+  adapter-documentation:
+    name: Verify all adapters have audit and review docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check adapter documentation completeness
+        run: |
+          set -e
+
+          echo "Checking that all adapter packages have audit and review documentation..."
+
+          ADAPTERS_DIR="mixin_logging/adapters"
+          AUDITS_DIR="docs/audits"
+          REVIEWS_DIR="docs/reviews"
+
+          if [ ! -d "$ADAPTERS_DIR" ]; then
+            echo "ERROR: Adapters directory not found: $ADAPTERS_DIR"
+            exit 1
+          fi
+
+          # Find all adapter directories (exclude non-adapter dirs like constants, tests, __pycache__)
+          ADAPTERS=$(find "$ADAPTERS_DIR" -maxdepth 1 -type d ! -name "__pycache__" ! -name "tests" ! -name "constants" ! -name "adapters" ! -path "$ADAPTERS_DIR")
+
+          MISSING_DOCS=0
+
+          for adapter_dir in $ADAPTERS; do
+            adapter_name=$(basename "$adapter_dir")
+
+            # Skip if no adapter files (empty directory)
+            if [ -z "$(find "$adapter_dir" -maxdepth 1 -type f -name "*.py")" ]; then
+              continue
+            fi
+
+            audit_file=$(find "$AUDITS_DIR" -name "*$adapter_name*audit*" 2>/dev/null | head -1)
+            review_file=$(find "$REVIEWS_DIR" -name "*$adapter_name*review*" 2>/dev/null | head -1)
+
+            if [ -z "$audit_file" ]; then
+              echo "FAIL: Adapter '$adapter_name' missing audit doc in $AUDITS_DIR"
+              MISSING_DOCS=$((MISSING_DOCS + 1))
+            fi
+
+            if [ -z "$review_file" ]; then
+              echo "FAIL: Adapter '$adapter_name' missing review doc in $REVIEWS_DIR"
+              MISSING_DOCS=$((MISSING_DOCS + 1))
+            fi
+          done
+
+          if [ $MISSING_DOCS -gt 0 ]; then
+            echo ""
+            echo "ERROR: $MISSING_DOCS adapter(s) missing documentation."
+            echo "Each adapter under mixin_logging/adapters/<name>/ must have:"
+            echo "  - docs/audits/*<name>*audit*.md"
+            echo "  - docs/reviews/*<name>*review*.md"
+            exit 1
+          fi
+
+          echo "✓ All adapter packages have corresponding audit and review docs."

mixin_logging-0.5.0/.github/workflows/dto-strict.yml

@@ -0,0 +1,37 @@
+name: dto-strict
+
+# DTO-discipline lint (frozen+slots, facade-ban, R001-R006). Per-repo copy of
+# the canonical gate; runs on the root-layout package. Empty baseline at
+# v0.2.0 (clean rebuild — 0 violations).
+# Lint step: whole package (native test-file exemption via R007/R008 rules).
+# LOC-cap step: source dirs only (test density exempt from cap per review record).
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install Python 3.12
+        run: uv python install 3.12
+      - name: Run dto-strict
+        run: uvx --python 3.12 dto-strict@0.3.0 mixin_logging/ --format github
+      - name: Check LOC cap
+        run: |
+          for dir in mixin_logging/adapters/{aiohttp,asgi,botocore,celery,cloud,constants,graphql,grpc,httpx,requests,stdlib,urllib3,websocket,wsgi} mixin_logging/common/{constants,utils} mixin_logging/config mixin_logging/context/{constants,correlation} mixin_logging/decorators/{constants,logged} mixin_logging/mixin; do
+            uvx --python 3.12 dto-strict@0.3.0 loc-cap "$dir"
+          done

mixin_logging-0.5.0/.github/workflows/no-ai-attribution.yml

@@ -0,0 +1,73 @@
+name: Attribution Gate
+
+# Server-side enforcement: rejects pushes/PRs whose commit messages contain
+# Claude/Anthropic attribution. Catches GitHub squash-merge propagation that
+# bypasses local commit-msg, pre-push, and PreToolUse hooks.
+#
+# Per-repo copy of the canonical attribution gate.
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  scan:
+    name: Scan commit messages for attribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (full history)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Determine commit range
+        id: range
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PR_BASE: ${{ github.event.pull_request.base.sha }}
+          PR_HEAD: ${{ github.event.pull_request.head.sha }}
+          PUSH_BEFORE: ${{ github.event.before }}
+          PUSH_AFTER: ${{ github.event.after }}
+        run: |
+          set -euo pipefail
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            BASE="$PR_BASE"
+            HEAD="$PR_HEAD"
+          else
+            BASE="$PUSH_BEFORE"
+            HEAD="$PUSH_AFTER"
+            if [ "$BASE" = "0000000000000000000000000000000000000000" ] || [ -z "$BASE" ]; then
+              git fetch origin main:refs/remotes/origin/main 2>/dev/null || true
+              BASE=$(git merge-base origin/main "$HEAD" 2>/dev/null || git rev-list --max-parents=0 "$HEAD" | tail -1)
+            fi
+          fi
+          echo "base=$BASE" >> "$GITHUB_OUTPUT"
+          echo "head=$HEAD" >> "$GITHUB_OUTPUT"
+
+      - name: Scan for Claude/Anthropic attribution
+        env:
+          BASE: ${{ steps.range.outputs.base }}
+          HEAD: ${{ steps.range.outputs.head }}
+          PATTERN: 'co-authored-by.*(claude|anthropic)|generated with claude|@claude|noreply@anthropic|🤖'
+        run: |
+          set -uo pipefail
+          OFFENDING=""
+          for sha in $(git rev-list "$BASE..$HEAD"); do
+            MSG=$(git log -1 --pretty=format:"%B" "$sha")
+            if echo "$MSG" | grep -qiE "$PATTERN"; then
+              AUTHOR=$(git log -1 --pretty=format:"%an" "$sha")
+              SUBJECT=$(git log -1 --pretty=format:"%s" "$sha")
+              OFFENDING="${OFFENDING}  ${sha:0:8} | author=${AUTHOR} | ${SUBJECT}"$'\n'
+            fi
+          done
+          if [ -n "$OFFENDING" ]; then
+            echo "::error::Claude/Anthropic attribution detected in commit messages"
+            echo "Offending commits in range $BASE..$HEAD:"
+            printf '%s' "$OFFENDING"
+            exit 1
+          fi
+          echo "OK: no attribution detected in $BASE..$HEAD"

mixin_logging-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Build + publish
+    runs-on: ubuntu-latest
+    environment: pypi  # second-layer GitHub deployment-environment gate
+    permissions:
+      id-token: write  # OIDC trusted publisher
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build deps
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Verify artifacts
+        run: python -m pip install --upgrade twine && python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mixin_logging-0.5.0/.github/workflows/ruff.yml

@@ -0,0 +1,29 @@
+name: Ruff
+
+# Ruff lint + format check. Pinned to 0.15.14 to match local version.
+# Format drift was previously undetected; this gate prevents future drift.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Ruff lint
+        run: uvx ruff@0.15.14 check mixin_logging/
+      - name: Ruff format check
+        run: uvx ruff@0.15.14 format --check mixin_logging/

mixin_logging-0.5.0/.gitignore

@@ -0,0 +1,132 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store

mixin_logging-0.5.0/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.0] - 2026-07-06
+
+### Changed
+
+- **Package rename: logging-mixin to mixin-logging**: Following the govtech OSS suite category-first naming convention (`<category>-<name>`). Distribution name on PyPI changes from `logging-mixin` to `mixin-logging`. Import root changes from `logging_mixin` to `mixin_logging`. The old `logging-mixin` distribution stays live on PyPI for backward compatibility; old pins continue to work.
+- **All public symbols remain unchanged**: `LoggingMixin`, `@logged`, correlation ID API (`set_correlation_id`, `get_correlation_id`, `clear_correlation_id`), and all 13 adapters retain their names and signatures. Only the module path changes.
+- **Version bump to 0.5.0**: Minor version bump reflects the rename; code content is identical to v0.4.0.
+
+### Migration Guide
+
+Update your imports:
+```python
+# Old (v0.4.0)
+from logging_mixin import LoggingMixin
+
+# New (v0.5.0+)
+from mixin_logging import LoggingMixin
+```
+
+Update your dependency pin:
+```bash
+# Old
+uv add logging-mixin
+
+# New
+uv add mixin-logging
+```
+
+## [0.3.0] - 2026-06-10
+
+### Added
+
+- **Public API surface**: Explicit `PUBLIC_API` export from top-level package with lockstep conformance test. `LoggingMixin`, `CorrelationIdInjector`, and adapter middleware classes available directly from `logging_mixin`. Sub-package constants surfaced via `logging_mixin.constants.<adapter>`.
+
+### Changed
+
+- **Standards-conformance sweep**: Unified constants organization and semantic-literal extraction across all adapters and common modules. Canonical docstring-format section headers and deep extraction to dedicated constants modules. Integration with `dto-strict` v0.2.2+ for dataclass configuration and metadata validation.
+- **Docstring and naming conformance**: Package-wide consistency in documentation and parameter naming. All public methods, classes, and packages now start with imperative action verbs. One-line verb-phrase docstrings and scoped module docstrings for semantic clarity.
+- **Publish workflow trigger**: Release workflow now triggered by version-tag push instead of release-branch. Chore/release-* branch pattern deprecated.
+
+## [0.4.0] - 2026-06-29
+
+### Added
+
+- **5 new correlation-ID adapters**: Extended adapter suite from 8 to 13 for broader protocol coverage:
+  - **aiohttp Adapter** (`logging_mixin/adapters/aiohttp/`): Outbound `aiohttp.ClientSession` instrumentation. Injects `X-Correlation-ID` header via `TraceConfig` on every request.
+  - **urllib3 Adapter** (`logging_mixin/adapters/urllib3/`): Outbound `urllib3.PoolManager` instrumentation. Injects `X-Correlation-ID` header on every request via `urlopen()` override.
+  - **gRPC Adapter** (`logging_mixin/adapters/grpc/`): Inbound gRPC server interceptor. Extracts correlation ID from invocation metadata; auto-generates fallback. Sets context for handler execution.
+  - **WebSocket Adapter** (`logging_mixin/adapters/websocket/`): Inbound ASGI WebSocket middleware. Extracts correlation ID from handshake headers; auto-generates fallback. Sets context for WebSocket connection lifecycle.
+  - **GraphQL Adapter** (`logging_mixin/adapters/graphql/`): Resolver-context injector. Reads correlation ID from upstream context (set by ASGI/WSGI); exposes via resolver context dict.
+
+- **Optional dependency extras**: Added 3 new extras for the new adapters:
+  - `[aiohttp]`: aiohttp client instrumentation
+  - `[urllib3]`: urllib3 client instrumentation
+  - `[grpc]`: gRPC server instrumentation (requires `grpcio`)
+
+### Changed
+
+- **Canonical import-idiom enforcement**: Applied `ruff isort` + `PLC0414` (redundant-self-aliases) to standardize imports across adapters. Removed self-referential re-exports in adapter `__init__` files (PR #51).
+- **LOC-cap scoping refinement**: Adjusted line-count enforcement to target source code only, excluding tests. Configuration in `[tool.dto-strict.loc-cap]` remains (hard_cap=300, soft_target=200), but scope now focuses on maintainability of production code (PR #50).
+- **Documentation improvements**: Extensive docs refresh: adapter table expansion, correlation semantics clarification, FAQ additions, version sweep across README and guides. Code of Conduct alignment with Contributor Covenant 2.1 (PR #44, #47).
+
+### Fixed
+
+- **Publish workflow trigger**: Corrected publish.yml to fire on GitHub Release published (suite standard), not on push to main. Prevents accidental PyPI uploads from merge commits (PR #49).
+- **Pyright editor integration**: Added `venv` binding in pyrightconfig.json for editor type-server resolution, enabling accurate type hints in VS Code (PR #48).
+
+## [0.2.0] - 2026-06-05
+
+### Added
+
+- **Complete correlation-ID adapter suite**: 8 adapters for end-to-end correlation ID propagation across the full request/response lifecycle:
+  - **ASGI Adapter** (`logging_mixin/adapters/asgi/`): FastAPI, Starlette, Quart, and other ASGI frameworks. `AsgiCorrelation` value object extracts or generates correlation ID from ASGI request scope. `CorrelationIdMiddleware` propagates across request lifecycle. Input validation via `_is_safe()` rejects control characters (`\r\n\0`), enforces max length (128 bytes), guards against invalid UTF-8. Response header injection automatically echoes correlation ID.
+  - **WSGI Adapter** (`logging_mixin/adapters/wsgi/`): Django, Flask, Pyramid, and other WSGI frameworks. Inbound middleware extraction + response header injection.
+  - **HTTPX Adapter** (`logging_mixin/adapters/httpx/`): Outbound `httpx.Client` and async `httpx.AsyncClient` instrumentation. Injects `X-Correlation-ID` on every request.
+  - **Requests Adapter** (`logging_mixin/adapters/requests/`): Outbound `requests.Session` instrumentation via `CorrelationHTTPAdapter`. Injects `X-Correlation-ID` on every request.
+  - **Botocore Adapter** (`logging_mixin/adapters/botocore/`): AWS SDK instrumentation. Injects `X-Correlation-ID` into all AWS service calls via event system hooks.
+  - **Celery Adapter** (`logging_mixin/adapters/celery/`): Task-boundary propagation via Celery signals (publish → prerun → postrun). Maintains correlation ID across async task execution.
+  - **Stdlib Adapter** (`logging_mixin/adapters/stdlib/`): `logging.Filter` implementation. Stamps `correlation_id` on every `LogRecord` automatically.
+  - **Cloud Adapter** (`logging_mixin/adapters/cloud/`): Inbound AWS Lambda event extraction. Supports API Gateway, ALB, SQS, SNS, EventBridge, and top-level direct-invoke. Auto-generates fallback correlation ID if not present.
+
+- **ASGI Adapter Robustness Hardening**: Input validation and defensive decoding to prevent log/header injection and resource exhaustion:
+  - CRLF injection and log injection prevention via `_is_safe()`: rejects control characters (`\r\n\0`), enforces 128-byte max length, and requires non-empty values.
+  - UTF-8 decoding safety: try-except guard on header decoding; invalid UTF-8 triggers UUID4 fallback rather than crash.
+  - Empty-string rejection: validation guards against semantic invariant violation (empty correlation IDs).
+  - Type-safe header iteration: defensive handling of ASGI header byte-tuples; malformed headers skipped gracefully.
+
+- **Optional-dependency extras**: Added explicit package extras for all adapter dependencies:
+  - `[httpx]`: HTTPX client instrumentation
+  - `[requests]`: Requests client instrumentation
+  - `[celery]`: Celery task propagation
+  - `[botocore]`: AWS SDK instrumentation
+  - `[all]`: Installs all adapter dependencies at once (convenience extra)
+
+### Changed
+
+- **Dependency management**: Adopted `uv` for faster, more predictable lock-file generation. Committed `uv.lock`; CI migrated to `astral-sh/setup-uv@v4`.
+- **Python version requirement**: Dropped Python 3.10 support. Now requires Python >=3.11 (3.11 and 3.12 supported).
+- **Package layout**: Root-layout restructure: `logging_mixin/adapters/` package with 8 specialized adapter modules (objects/ + client/ split per adapter type).
+- **LOC-cap CI gate**: Automated line-count enforcement via `dto-strict loc-cap` subcommand; vendored `scripts/check_loc_cap.py` removed. Configuration in `[tool.dto-strict.loc-cap]` (hard_cap=300, soft_target=200).
+
+### Removed
+
+- **Python 3.10 classifier**: Dropped from supported versions in `pyproject.toml`.
+
+## [0.1.0] - 2026-05-15
+
+### Added
+
+- Initial release.
+- Core logging mixin infrastructure.
+- Correlation ID context management.

mixin_logging-0.5.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Code of Conduct
+
+## My Commitment
+
+I maintain this project solo, and I am committed to keeping it a welcoming space for everyone who participates in issues, pull requests, and discussions. I pledge to treat every participant with respect and dignity, regardless of age, body size, caste, disability, ethnicity, sex characteristics, gender, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, sexual identity and orientation, or any other dimension of diversity.
+
+## Standards
+
+Behavior that keeps this a positive space:
+
+- Welcoming and inclusive language
+- Respect for differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the project
+- Empathy toward other participants
+
+Behavior I will not accept:
+
+- Harassment or insulting or derogatory comments
+- Personal attacks
+- Public or private harassment
+- Publishing someone's private information without consent
+- Conduct that could reasonably be considered inappropriate
+
+## Enforcement
+
+Report unacceptable behavior to me through GitHub, either by opening an issue or, where discretion is warranted, through private vulnerability reporting. I review and act on every report promptly and fairly, and I respect the privacy and security of anyone who reports.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

mixin_logging-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing
+
+Thank you for your interest in contributing to logging-mixin!
+
+## Development Setup
+
+### Prerequisites
+- Python 3.11 or later
+- [uv](https://docs.astral.sh/uv/) for dependency management
+
+### Local Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/jekhator/logging-mixin.git
+   cd logging-mixin
+   ```
+
+2. Install dependencies and all optional extras:
+   ```bash
+   uv sync --all-extras
+   ```
+
+3. Verify the setup by running tests:
+   ```bash
+   uv run pytest
+   ```
+
+## Running Tests
+
+Execute the full test suite:
+```bash
+uv run pytest
+```
+
+For coverage report:
+```bash
+uv run pytest --cov=logging_mixin
+```
+
+## Linting and Code Style
+
+Format and lint your code before committing:
+```bash
+uv run ruff check --fix .
+uv run ruff format .
+```
+
+## Submitting Changes
+
+1. Create a feature branch from `main`
+2. Make your changes with clear, focused commits
+3. Add tests for new functionality
+4. Ensure all tests pass: `uv run pytest`
+5. Ensure linting passes: `uv run ruff check .`
+6. Push your branch and open a pull request against `main`
+
+## Pull Request Requirements
+
+All pull requests must:
+- Pass all CI checks (tests, linting, type checks)
+- Include tests for new code
+- Update documentation if needed
+- Have clear commit messages
+
+Thank you for contributing!