logging-mixin 0.1.0__tar.gz

logging_mixin-0.1.0/.gitignore

@@ -0,0 +1,131 @@
+# 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

logging_mixin-0.1.0/LICENSE

@@ -0,0 +1,149 @@
+Apache License
+Version 2.0, January 2004
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined in Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by the
+   copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all other
+   entities that control, are controlled by, or are under common control
+   with that entity. For the purposes of this definition, "control" means
+   (i) the power, direct or indirect, to cause the direction or management
+   of such entity, whether by contract or otherwise, or (ii) ownership of
+   fifty percent (50%) or more of the outstanding shares, or (iii) beneficial
+   ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity exercising
+   permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation source,
+   and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical transformation
+   or translation of a Source form, including but not limited to compiled
+   object code, generated documentation, and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or Object
+   form, made available under the License, as indicated by a copyright notice
+   that is included in or attached to the work (an example is provided in
+   the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object form,
+   that is based on (or derived from) the Work and for which the editorial
+   revisions, annotations, elaborations, or other modifications represent
+   originally authored expressions of authorship. For the purposes of this
+   License, Derivative Works shall not include works that remain separable
+   from, or merely link (or bind by name) to the interfaces of, the Work and
+   Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including the original
+   version of the Work and any derivative works thereof, and any modifications
+   to those works or derivative works, including without limitation any
+   additions to that Work or Derivative Work that constitutes, in whole or
+   in part, an original work of authorship.
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity on
+   behalf of whom a Contribution has been received by Licensor and subsequently
+   incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+   License, each Contributor hereby grants to You a perpetual, worldwide,
+   non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+   reproduce, prepare Derivative Works of, publicly display, publicly perform,
+   sublicense, and distribute the Work and such Derivative Works in Source or
+   Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+   each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+   no-charge, royalty-free, irrevocable (except as stated in this section)
+   patent license to make, have made, use, offer to sell, sell, import, and
+   otherwise transfer the Work, where such license applies only to those patent
+   claims licensable by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s) with the
+   Work to which such Contribution was submitted. If You institute patent
+   litigation against any entity (including a cross-claim or counterclaim in
+   a lawsuit) alleging that the Work or a Contribution incorporated within the
+   Work constitutes direct or contributory patent infringement, then any patent
+   licenses granted to You under this License for that Work shall terminate as
+   of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+   Derivative Works thereof in any medium, with or without modifications, and
+   in Source or Object form, provided that You meet the following conditions:
+
+   (a) You must give any other recipients of the Work or Derivative Works a
+       copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices stating
+       that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works that You
+       distribute, all copyright, patent, trademark, and attribution notices
+       from the Source form of the Work, excluding those notices that do not
+       pertain to any part of the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file, then any Derivative Works
+       that You distribute must include a readable copy of the attribution
+       notices contained within such NOTICE file, excluding those notices that
+       do not pertain to any part of the Derivative Works.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+   Contribution intentionally submitted for inclusion in the Work by You to
+   Licensor shall be under the terms and conditions of this License, without
+   any additional terms or conditions. Notwithstanding the above, nothing herein
+   shall supersede or modify the terms of any separate license agreement you
+   may have executed with Licensor regarding such Contribution.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+   trademarks, service marks, or product names of the Licensor, except as
+   required for reasonable and customary use in describing the origin of the
+   Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+   writing, Licensor provides the Work (and each Contributor provides its
+   Contributions) on an "AS-IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied, including without limitation any warranties
+   or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any risks
+   associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+   tort (including negligence), contract, or otherwise, unless required by
+   applicable law (such as deliberate and grossly negligent acts) or agreed to
+   in writing, shall any Contributor be liable to You for damages, including
+   any direct, indirect, special, incidental, or consequential damages of any
+   character arising as a result of this License or out of the use or inability
+   to use the Work.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+   Derivative Works thereof, You may choose to offer, and charge a fee for,
+   acceptance of support, warranty, indemnity, or other liability obligations
+   and/or rights consistent with this License. However, in accepting such
+   obligations, You may act only on Your own behalf and on Your sole
+   responsibility, not on behalf of any other Contributor, and only if You
+   agree to indemnify, defend, and hold each Contributor harmless for any
+   liability incurred by, or claims asserted against, such Contributor by
+   reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 James Ekhator
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use this file except in compliance with the License. You may obtain a copy of
+the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

logging_mixin-0.1.0/PKG-INFO

@@ -0,0 +1,352 @@
+Metadata-Version: 2.4
+Name: logging-mixin
+Version: 0.1.0
+Summary: Class-bound structured logging with auto-injected correlation IDs for Python services.
+Project-URL: Homepage, https://github.com/jekhator/logging-mixin
+Project-URL: Repository, https://github.com/jekhator/logging-mixin.git
+Project-URL: Issues, https://github.com/jekhator/logging-mixin/issues
+Author: James Ekhator
+License: Apache-2.0
+License-File: LICENSE
+Keywords: correlation-id,distributed-tracing,logging,observability,structured-logging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: aws-lambda
+Provides-Extra: dev
+Requires-Dist: django>=4.2; extra == 'dev'
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# logging-mixin
+
+**Class-bound structured logging with auto-injected correlation IDs for Python services.**
+
+Replaces module-level loggers in business logic with per-class loggers that automatically inject correlation IDs and class context into every log record. Enables clean distributed tracing without boilerplate.
+
+## Why?
+
+Production services need correlation IDs for tracing requests through distributed systems. Traditional approaches require passing context through every function or managing global state:
+
+```python
+# Traditional approach: manual context passing (boilerplate)
+logger = logging.getLogger(__name__)
+
+def create_user(name: str, correlation_id: str):
+    logger.info("Creating user", extra={"correlation_id": correlation_id, "name": name})
+    # Must thread correlation_id through every call
+    save_user(name, correlation_id)
+
+def save_user(name: str, correlation_id: str):
+    logger.info("Saving user", extra={"correlation_id": correlation_id, "name": name})
+```
+
+`logging-mixin` solves this with automatic injection:
+
+```python
+from logging_mixin import LoggingMixin
+
+class UserService(LoggingMixin):
+    def create_user(self, name: str):
+        self.log_info("Creating user", name=name)
+        # correlation_id automatically injected by LoggingMixin
+        self.save_user(name)
+
+    def save_user(self, name: str):
+        self.log_info("Saving user", name=name)
+        # correlation_id still available, no parameter needed
+```
+
+## Installation
+
+```bash
+pip install logging-mixin
+```
+
+Requires Python 3.10+.
+
+### Optional framework extras
+
+```bash
+# Django support
+pip install logging-mixin[django]
+
+# FastAPI support
+pip install logging-mixin[fastapi]
+
+# AWS Lambda support
+pip install logging-mixin[aws-lambda]
+
+# All together
+pip install logging-mixin[django,fastapi,aws-lambda]
+
+# Development (includes all extras + testing tools)
+pip install logging-mixin[dev]
+```
+
+## Quick Start
+
+### 1. Create a service using LoggingMixin
+
+```python
+from logging_mixin import LoggingMixin
+
+class OrderService(LoggingMixin):
+    def create_order(self, user_id: int, items: list[str]):
+        self.log_info("order.create", user_id=user_id, item_count=len(items))
+        # Logs with:
+        #   logger name: "myapp.services.OrderService"
+        #   extra: {"correlation_id": "abc123", "user_id": 123, "item_count": 3}
+        ...
+```
+
+### 2. Set correlation ID in your framework
+
+#### Django
+
+Add the middleware to `settings.py`:
+
+```python
+MIDDLEWARE = [
+    "logging_mixin.adapters.django.CorrelationIdMiddleware",
+    # ... other middleware
+]
+```
+
+#### FastAPI
+
+Add middleware:
+
+```python
+from fastapi import FastAPI
+from logging_mixin.adapters.fastapi import correlation_id_middleware
+
+app = FastAPI()
+app.add_middleware(correlation_id_middleware)
+```
+
+#### AWS Lambda
+
+Call in handler:
+
+```python
+from logging_mixin.adapters.aws_lambda import setup_correlation_id
+
+def lambda_handler(event, context):
+    setup_correlation_id(event, context)
+    # Now LoggingMixin can access correlation_id
+    ...
+```
+
+### 3. Use in background tasks
+
+Correlation IDs automatically propagate to Celery tasks, background jobs, and async functions via Python's `contextvars`:
+
+```python
+from celery import shared_task
+from logging_mixin import LoggingMixin
+
+@shared_task
+def process_order(order_id: int):
+    service = OrderService()
+    service.log_info("order.processing", order_id=order_id)
+    # Inherits correlation_id from the original request context
+```
+
+## Design
+
+### Instance-only (no @classmethod/@staticmethod)
+
+LoggingMixin's `log_*` methods are instance methods. They cannot be called from `@classmethod` or `@staticmethod` because they read `self._logger`:
+
+```python
+class MyService(LoggingMixin):
+    def instance_method(self):
+        self.log_info("works")  # ✓ OK
+
+    @classmethod
+    def class_method(cls):
+        self.log_info("FAILS")  # ✗ TypeError: missing 1 required positional argument 'self'
+
+    @staticmethod
+    def static_method():
+        self.log_info("FAILS")  # ✗ TypeError
+```
+
+**Workaround:** Use module-level logger for class methods and manually inject correlation ID:
+
+```python
+import logging
+from logging_mixin import get_correlation_id
+
+logger = logging.getLogger(__name__)
+
+class MyService(LoggingMixin):
+    def instance_method(self):
+        self.log_info("instance.event")  # ✓ Automatic injection
+
+    @classmethod
+    def class_method(cls):
+        cid = get_correlation_id()
+        logger.info("class.event", extra={"correlation_id": cid or "-"})  # ✓ Manual injection
+```
+
+### Correlation ID lifecycle
+
+Correlation IDs are stored in a `contextvars.ContextVar`, which means they:
+- Survive async/await boundaries (async-safe)
+- Cross thread boundaries when using thread pool executors
+- Are automatically reset at the start of each HTTP request (Django/FastAPI middleware)
+- Propagate to background tasks (Celery, threading, async)
+
+### Composition with masking
+
+LoggingMixin automatically composes with masking libraries. If your instance has a `mask_for_logging()` method (e.g., from a masking mixin), its output is added to the log record:
+
+```python
+from logging_mixin import LoggingMixin
+from some_library import MaskingMixin
+
+class Response(LoggingMixin, MaskingMixin):
+    def trace(self):
+        self.log_debug("response")
+        # Logs with extra: {"correlation_id": "...", "instance": <masked dict>}
+```
+
+## API Reference
+
+### LoggingMixin
+
+Class-bound logger providing five methods:
+
+```python
+class Service(LoggingMixin):
+    def do_thing(self):
+        self.log_debug("event", detail="verbose")      # DEBUG level
+        self.log_info("event", status="ok")             # INFO level
+        self.log_warning("event", issue="slow")         # WARNING level
+        self.log_error("event", error="failure")        # ERROR level
+        self.log_exception("event")                     # ERROR level + traceback
+```
+
+Each method:
+- Takes an event name (string) and optional keyword arguments
+- Automatically injects correlation_id into the log record's `extra` dict
+- Reads from the per-class logger (`module.ClassName`)
+- Composes with `mask_for_logging()` if available
+
+### Context functions
+
+```python
+from logging_mixin import get_correlation_id, set_correlation_id, clear_correlation_id
+
+# Get the current correlation ID (returns None if not set)
+cid = get_correlation_id()
+
+# Manually set (for background tasks, tests, non-request contexts)
+set_correlation_id("abc123def456")
+
+# Clear (useful for test isolation)
+clear_correlation_id()
+```
+
+### Framework adapters
+
+#### Django middleware
+
+Automatically sets correlation ID from `X-Correlation-ID` header or generates UUID.
+
+```python
+from logging_mixin.adapters.django import CorrelationIdMiddleware
+
+MIDDLEWARE = ["logging_mixin.adapters.django.CorrelationIdMiddleware", ...]
+```
+
+#### FastAPI dependency
+
+Two approaches:
+
+```python
+# Middleware (auto for all routes):
+from logging_mixin.adapters.fastapi import correlation_id_middleware
+app.add_middleware(correlation_id_middleware)
+
+# Or dependency (per-route opt-in):
+from fastapi import Depends
+from logging_mixin.adapters.fastapi import correlation_id_dependency
+
+@app.get("/items/")
+def get_items(cid: str = Depends(correlation_id_dependency)):
+    ...
+```
+
+#### AWS Lambda
+
+```python
+from logging_mixin.adapters.aws_lambda import setup_correlation_id
+
+def lambda_handler(event, context):
+    setup_correlation_id(event, context)
+    # Now LoggingMixin can access correlation_id via get_correlation_id()
+    ...
+```
+
+## Testing
+
+LoggingMixin is test-friendly:
+
+```python
+import logging
+from logging_mixin import LoggingMixin, set_correlation_id
+
+class TestMyService:
+    def test_logs_with_correlation_id(self, caplog):
+        set_correlation_id("test-123")
+
+        service = MyService()
+        with caplog.at_level(logging.INFO):
+            service.do_something()
+
+        assert caplog.records[0].correlation_id == "test-123"
+```
+
+## Design Principles
+
+- **Class-bound:** Each class gets its own logger (`module.ClassName`) for clean grouping
+- **Instance-only:** Methods read `self._logger` (cannot be used from @classmethod/@staticmethod)
+- **Async-safe:** Uses `contextvars.ContextVar` (survives async/await, thread pools)
+- **Framework-agnostic:** Core mixin has zero framework dependencies
+- **Composable:** Works naturally with masking mixins and other mixins
+- **Zero boilerplate:** No function signature changes needed
+
+## Trade-offs
+
+- **Cannot use in @classmethod/@staticmethod:** Use module-level logger + manual correlation ID injection instead
+- **Requires ContextVar setup:** Framework adapters or manual `set_correlation_id()` call needed
+- **Implicit behavior:** Correlation ID is silently injected (can be surprising if not expected)
+
+## License
+
+Apache 2.0 — see LICENSE file.
+
+## See Also
+
+- [contextvars](https://docs.python.org/3/library/contextvars.html) — Python standard library
+- [logging](https://docs.python.org/3/library/logging.html) — Python standard library
+- [Django middleware](https://docs.djangoproject.com/en/stable/topics/http/middleware/) — Django framework
+- [FastAPI middleware](https://fastapi.tiangolo.com/tutorial/middleware/) — FastAPI framework