structlog-config 0.2.0__tar.gz → 0.4.1__tar.gz

{structlog_config-0.2.0 → structlog_config-0.4.1}/PKG-INFO

@@ -1,14 +1,16 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.3
 Name: structlog-config
-Version: 0.2.0
+Version: 0.4.1
 Summary: A comprehensive structlog configuration with sensible defaults for development and production environments, featuring context management, exception formatting, and path prettification.
-Project-URL: Repository, https://github.com/iloveitaly/structlog-config
+Keywords: logging,structlog,json-logging,structured-logging
+Author: Michael Bianco
 Author-email: Michael Bianco <mike@mikebian.co>
-Keywords: json-logging,logging,structlog,structured-logging
-Requires-Python: >=3.10
 Requires-Dist: orjson>=3.10.15
 Requires-Dist: python-decouple-typed>=3.11.0
+Requires-Dist: python-ipware>=3.0.0
 Requires-Dist: structlog>=25.2.0
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/iloveitaly/structlog-config
 Description-Content-Type: text/markdown
 
 # Opinionated Defaults for Structlog
@@ -30,12 +32,64 @@ Here are the main goals:
 ## Usage
 
 ```python
-from structlog_config import configure_logging
+from structlog_config import configure_logger
+
+log = configure_logger()
+
+log.info("the log", key="value")
+```
+
+## JSON Logging for Production
+
+JSON logging is automatically enabled in production and staging environments (`PYTHON_ENV=production` or `PYTHON_ENV=staging`):
+
+```python
+from structlog_config import configure_logger
+
+# Automatic JSON logging in production
+log = configure_logger()
+log.info("User login", user_id="123", action="login")
+# Output: {"action":"login","event":"User login","level":"info","timestamp":"2025-09-24T18:03:00Z","user_id":"123"}
+
+# Force JSON logging regardless of environment
+log = configure_logger(json_logger=True)
+
+# Force console logging regardless of environment
+log = configure_logger(json_logger=False)
+```
+
+JSON logs use [orjson](https://github.com/ijl/orjson) for performance, include sorted keys and ISO timestamps, and serialize exceptions cleanly. Note that `PYTHON_LOG_PATH` is ignored with JSON logging (stdout only).
+
+## TRACE Logging Level
+
+This package adds support for a custom `TRACE` logging level (level 5) that's even more verbose than `DEBUG`. This is useful for extremely detailed debugging scenarios.
+
+The `TRACE` level is automatically set up when you call `configure_logger()`. You can use it like any other logging level:
+
+```python
+import logging
+from structlog_config import configure_logger
+
+log = configure_logger()
+
+# Using structlog
+log.info("This is info")
+log.debug("This is debug") 
+log.trace("This is trace")  # Most verbose
+
+# Using stdlib logging
+logging.trace("Module-level trace message")
+logger = logging.getLogger(__name__)
+logger.trace("Instance trace message")
+```
+
+Set the log level to TRACE using the environment variable:
 
-configure_logging()
+```bash
+LOG_LEVEL=TRACE
 ```
 
-## Stdib Log Management
+## Stdlib Log Management
 
 By default, all stdlib loggers are:
 

{structlog_config-0.2.0 → structlog_config-0.4.1}/README.md

@@ -17,12 +17,64 @@ Here are the main goals:
 ## Usage
 
 ```python
-from structlog_config import configure_logging
+from structlog_config import configure_logger
+
+log = configure_logger()
+
+log.info("the log", key="value")
+```
+
+## JSON Logging for Production
+
+JSON logging is automatically enabled in production and staging environments (`PYTHON_ENV=production` or `PYTHON_ENV=staging`):
+
+```python
+from structlog_config import configure_logger
+
+# Automatic JSON logging in production
+log = configure_logger()
+log.info("User login", user_id="123", action="login")
+# Output: {"action":"login","event":"User login","level":"info","timestamp":"2025-09-24T18:03:00Z","user_id":"123"}
+
+# Force JSON logging regardless of environment
+log = configure_logger(json_logger=True)
+
+# Force console logging regardless of environment
+log = configure_logger(json_logger=False)
+```
+
+JSON logs use [orjson](https://github.com/ijl/orjson) for performance, include sorted keys and ISO timestamps, and serialize exceptions cleanly. Note that `PYTHON_LOG_PATH` is ignored with JSON logging (stdout only).
+
+## TRACE Logging Level
+
+This package adds support for a custom `TRACE` logging level (level 5) that's even more verbose than `DEBUG`. This is useful for extremely detailed debugging scenarios.
+
+The `TRACE` level is automatically set up when you call `configure_logger()`. You can use it like any other logging level:
+
+```python
+import logging
+from structlog_config import configure_logger
+
+log = configure_logger()
+
+# Using structlog
+log.info("This is info")
+log.debug("This is debug") 
+log.trace("This is trace")  # Most verbose
+
+# Using stdlib logging
+logging.trace("Module-level trace message")
+logger = logging.getLogger(__name__)
+logger.trace("Instance trace message")
+```
+
+Set the log level to TRACE using the environment variable:
 
-configure_logging()
+```bash
+LOG_LEVEL=TRACE
 ```
 
-## Stdib Log Management
+## Stdlib Log Management
 
 By default, all stdlib loggers are:
 

{structlog_config-0.2.0 → structlog_config-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "structlog-config"
-version = "0.2.0"
+version = "0.4.1"
 description = "A comprehensive structlog configuration with sensible defaults for development and production environments, featuring context management, exception formatting, and path prettification."
 keywords = ["logging", "structlog", "json-logging", "structured-logging"]
 readme = "README.md"
@@ -8,14 +8,19 @@ requires-python = ">=3.10"
 dependencies = [
     "orjson>=3.10.15",
     "python-decouple-typed>=3.11.0",
+    "python-ipware>=3.0.0",
     "structlog>=25.2.0",
 ]
 authors = [{ name = "Michael Bianco", email = "mike@mikebian.co" }]
 urls = { "Repository" = "https://github.com/iloveitaly/structlog-config" }
 
 [build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
+requires = ["uv_build>=0.8.11,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# avoids the src/ directory structure
+module-root = ""
 
 [dependency-groups]
 debugging-extras = [

{structlog_config-0.2.0 → structlog_config-0.4.1}/structlog_config/__init__.py

@@ -9,6 +9,9 @@ from structlog.processors import ExceptionRenderer
 from structlog.tracebacks import ExceptionDictTransformer
 from structlog.typing import FilteringBoundLogger
 
+from structlog_config.fastapi_access_logger import (
+    client_ip_from_request,
+)
 from structlog_config.formatters import (
     PathPrettifier,
     add_fastapi_context,

{structlog_config-0.2.0 → structlog_config-0.4.1}/structlog_config/fastapi_access_logger.py

@@ -3,13 +3,16 @@ from urllib.parse import quote
 
 import structlog
 from fastapi import FastAPI
+from python_ipware import IpWare
 from starlette.middleware.base import RequestResponseEndpoint
 from starlette.requests import Request
 from starlette.responses import Response
 from starlette.routing import Match, Mount
 from starlette.types import Scope
+from starlette.websockets import WebSocket
 
 log = structlog.get_logger("access_log")
+ipw = IpWare()
 
 
 def get_route_name(app: FastAPI, scope: Scope, prefix: str = "") -> str:
@@ -47,20 +50,40 @@ def get_path_with_query_string(scope: Scope) -> str:
     return path_with_query_string
 
 
-def get_client_addr(scope: Scope) -> str:
-    """Get the client's address.
+def client_ip_from_request(request: Request | WebSocket) -> str | None:
+    """
+    Get the client IP address from the request.
 
-    Args:
-        scope (Scope): Current context.
+    Headers are not case-sensitive.
 
-    Returns:
-        str: Client's address in the IP:PORT format.
+    Uses ipware library to properly extract client IP from various proxy headers.
+    Fallback to direct client connection if no proxy headers found.
     """
-    client = scope.get("client")
-    if not client:
-        return ""
-    ip, port = client
-    return f"{ip}:{port}"
+    headers = request.headers
+
+    # TODO this seems really inefficient, we should just rewrite the ipware into this repo :/
+    # Convert Starlette headers to format expected by ipware (HTTP_ prefixed)
+    # ipware expects headers in WSGI/Django-style meta format where HTTP headers
+    # are prefixed with "HTTP_" and dashes become underscores.
+    # See: https://github.com/un33k/python-ipware/blob/main/python_ipware/python_ipware.py#L33-L40
+    meta_dict = {}
+    for name, value in headers.items():
+        # Convert header name to HTTP_ prefixed format
+        meta_key = f"HTTP_{name.upper().replace('-', '_')}"
+        meta_dict[meta_key] = value
+
+    # Use ipware to extract IP from headers
+    ip, trusted_route = ipw.get_client_ip(meta=meta_dict)
+    if ip:
+        log.debug(
+            "extracted client IP from headers", ip=ip, trusted_route=trusted_route
+        )
+        return str(ip)
+
+    # Fallback to direct client connection
+    host = request.client.host if request.client else None
+
+    return host
 
 
 # TODO we should look at the static asset logic and pull the prefix path from tha
@@ -78,13 +101,27 @@ def is_static_assets_request(scope: Scope) -> bool:
         or scope["path"].endswith(".js")
         # .map files are attempted when devtools are enabled
         or scope["path"].endswith(".js.map")
+        or scope["path"].endswith(".ico")
+        or scope["path"].endswith(".png")
+        or scope["path"].endswith(".jpg")
+        or scope["path"].endswith(".jpeg")
+        or scope["path"].endswith(".gif")
     )
 
 
 def add_middleware(
     app: FastAPI,
 ) -> None:
-    """Use this method to add this middleware to your fastapi application."""
+    """
+    Add better access logging to fastapi:
+
+    >>> from structlog_config import fastapi_access_logger
+    >>> fastapi_access_logger.add_middleware(app)
+
+    You'll also want to disable the default uvicorn logs:
+
+    >>> uvicorn.run(..., log_config=None, access_log=False)
+    """
 
     @app.middleware("http")
     async def access_log_middleware(
@@ -113,7 +150,7 @@ def add_middleware(
             method=scope["method"],
             path=scope["path"],
             query=scope["query_string"].decode(),
-            client_ip=get_client_addr(scope),
+            client_ip=client_ip_from_request(request),
             route=route_name,
         )
 

{structlog_config-0.2.0 → structlog_config-0.4.1}/structlog_config/formatters.py

@@ -77,6 +77,7 @@ def pretty_traceback_exception_formatter(sio: TextIO, exc_info: ExcInfo) -> None
     from pretty_traceback.formatting import exc_to_traceback_str
 
     _, exc_value, traceback = exc_info
+    # TODO support local_stack_only env var support
     formatted_exception = exc_to_traceback_str(exc_value, traceback, color=not NO_COLOR)
     sio.write("\n" + formatted_exception)
 

{structlog_config-0.2.0 → structlog_config-0.4.1}/structlog_config/stdlib_logging.py

@@ -97,8 +97,8 @@ def redirect_stdlib_loggers(json_logger: bool):
     root_logger.propagate = True
 
     # TODO there is a JSON-like format that can be used to configure loggers instead :/
+    #      we should probably transition to using that format instead of this customized mapping
     std_logging_configuration = {
-        # "httpcore": {},
         "httpx": {
             "levels": {
                 "INFO": "WARNING",
@@ -109,6 +109,12 @@ def redirect_stdlib_loggers(json_logger: bool):
                 "INFO": "WARNING",
             }
         },
+        # stripe INFO logs are pretty noisy by default
+        "stripe": {
+            "levels": {
+                "INFO": "WARNING",
+            }
+        },
     }
     """
     These loggers either:

structlog_config-0.2.0/.copier-answers.yml

@@ -1,2 +0,0 @@
-# this exact file name is required in this exact location if updates are to work
-{"_commit": "v0.2.1-31-gb45b358", "_src_path": "https://github.com/iloveitaly/python-package-template", "project_name": "structlog-config", "full_name": "Michael Bianco", "email": "mike@mikebian.co", "github_username": "iloveitaly"}

structlog_config-0.2.0/.envrc

@@ -1,11 +0,0 @@
-layout uv
-
-export LOG_LEVEL=DEBUG
-
-# make sure none of the logging is unbuffered
-export PYTHONUNBUFFERED=1
-
-# required in order to avoid color codes in logging output for tests
-export NO_COLOR=1
-
-export PYTHONBREAKPOINT=pdbr.set_trace

structlog_config-0.2.0/.github/dependabot.yml

@@ -1,12 +0,0 @@
-version: 2
-
-updates:
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-
-  - package-ecosystem: "uv"
-    directory: "/"
-    schedule:
-      interval: "weekly"

structlog_config-0.2.0/.github/workflows/build_and_publish.yml

@@ -1,56 +0,0 @@
-name: Build and Publish to PyPI
-on:
-  push:
-    branches:
-      - main
-      - master
-
-permissions:
-  contents: write
-
-env:
-  PIP_DEFAULT_TIMEOUT: 60
-  PIP_RETRIES: 5
-
-  # required otherwise github api calls are rate limited
-  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-jobs:
-  matrix-test:
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-        python-version: ["3.13", "3.12", "3.11"]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: jdx/mise-action@v2
-      - run: mise use python@${{ matrix.python-version }}
-      - uses: iloveitaly/github-action-direnv-load-and-mask@master
-      - run: uv sync
-      - run: uv run pytest
-
-  release-please:
-    needs: matrix-test
-    runs-on: ubuntu-latest
-    outputs:
-      release_created: ${{ steps.release.outputs.release_created }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: googleapis/release-please-action@v4
-        id: release
-        with:
-          release-type: python
-          token: ${{ secrets.GH_PERSONAL_TOKEN }}
-
-  build-and-publish:
-    needs: release-please
-    runs-on: ubuntu-latest
-    if: ${{ needs.release-please.outputs.release_created }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: jdx/mise-action@v2
-      - uses: iloveitaly/github-action-direnv-load-and-mask@master
-      - run: uv sync
-      - run: uv build
-      - run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}

structlog_config-0.2.0/.github/workflows/repo-sync.yml

@@ -1,16 +0,0 @@
-name: Repository Metadata Sync
-
-on:
-  push:
-    branches: [main, master]
-
-jobs:
-  repo_sync:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Fetching Local Repository
-        uses: actions/checkout@v4
-      - name: Repository Metadata Sync
-        uses: iloveitaly/github-actions-metadata-sync@main
-        with:
-          TOKEN: ${{ secrets.GH_PERSONAL_TOKEN }}

structlog_config-0.2.0/.gitignore

@@ -1,129 +0,0 @@
-# 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
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.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
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow
-__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/

structlog_config-0.2.0/.tool-versions

@@ -1,3 +0,0 @@
-python 3.13.2
-uv 0.6.6
-direnv 2.35.0

structlog_config-0.2.0/.vscode/settings.json

@@ -1,36 +0,0 @@
-{
-  "[python]": {
-    "editor.formatOnSave": true,
-    "editor.defaultFormatter": "charliermarsh.ruff",
-    "editor.codeActionsOnSave": {
-      "source.fixAll": "explicit",
-      "source.organizeImports": "explicit"
-    },
-    "editor.tabSize": 4
-  },
-  "[toml]": {
-    "editor.formatOnSave": true,
-    "editor.tabSize": 4
-  },
-  "python.analysis.autoFormatStrings": true,
-
-  // for import autosuggest
-  "python.analysis.indexing": true,
-  "python.analysis.autoImportCompletions": true,
-
-  "python.analysis.packageIndexDepths": [
-    {
-      "name": "",
-      "depth": 3,
-      "includeAllSymbols": true
-    }
-  ],
-
-  "cSpell.words": ["openai", "httpx"],
-
-  "files.exclude": {
-    ".ruff_cache": true,
-    ".pytest_cache": true,
-    ".venv": true
-  }
-}

structlog_config-0.2.0/CHANGELOG.md

@@ -1,53 +0,0 @@
-# Changelog
-
-## [0.2.0](https://github.com/iloveitaly/structlog-config/compare/v0.1.0...v0.2.0) (2025-08-05)
-
-
-### Features
-
-* add custom TRACE log level and logger extension ([73e0551](https://github.com/iloveitaly/structlog-config/commit/73e05513c24e8ffe986105753a9a8d4ae5f5f496))
-* call setup_trace in configure_logger to enable tracing ([85ee622](https://github.com/iloveitaly/structlog-config/commit/85ee622ad5647c7a97032f79cb12cee9ab6bcac1))
-* global level override always set on std loggers, override static overrides if lower ([a7b66ea](https://github.com/iloveitaly/structlog-config/commit/a7b66ea626829b36a46ad4f73a4f1eb5bd12ca86))
-* patch structlog to support custom trace log level ([35c1dca](https://github.com/iloveitaly/structlog-config/commit/35c1dca852b1d746d3538d5082d7f5a25bedc056))
-
-
-### Bug Fixes
-
-* ensure TRACE log level is properly registered and utilized in logger ([87dc788](https://github.com/iloveitaly/structlog-config/commit/87dc788c661bff5daa7d6ed5416cdc0a98322278))
-* include .js.map in static asset request detection ([ff9bb4a](https://github.com/iloveitaly/structlog-config/commit/ff9bb4a6c9cd8bde1e9989399eeb2b4efc7d334a))
-
-
-### Documentation
-
-* clarify description of PYTHONASYNCIODEBUG constant ([2e2e0e9](https://github.com/iloveitaly/structlog-config/commit/2e2e0e9c07bfe80a0ba3e3d8b7278b76619cefa4))
-* ipython logging adjustment ([1990a7c](https://github.com/iloveitaly/structlog-config/commit/1990a7cc130c4e30256a19caf8079a1697d137b8))
-* update README with detailed logging setup instructions ([746fb8f](https://github.com/iloveitaly/structlog-config/commit/746fb8f64b542c74041141d787b62ff084b10805))
-
-## 0.1.0 (2025-04-14)
-
-
-### Features
-
-* add PathPrettifier for structlog path formatting ([b54bc58](https://github.com/iloveitaly/structlog-config/commit/b54bc58ef5d896675a69d809704829b3976763b7))
-* add RenameField processor for log key renaming ([a07bf36](https://github.com/iloveitaly/structlog-config/commit/a07bf363aa97631978c141c7385932f76ac30398))
-* add structured access logging for FastAPI requests ([37d506d](https://github.com/iloveitaly/structlog-config/commit/37d506dec89fc9c0de6a548371724c2342c0bafc))
-* allow loggers to be configured from environment variables ([417acf1](https://github.com/iloveitaly/structlog-config/commit/417acf1b9f5c0219191486c26ccdf6959956f329))
-* configure loggers via env variables in env_config.py ([2b920c4](https://github.com/iloveitaly/structlog-config/commit/2b920c4b0c373aabcb6b7d31503205268308ed83))
-* debug log static asset requests in FastAPI logger ([d8e5ee0](https://github.com/iloveitaly/structlog-config/commit/d8e5ee01af6b4ad5027010bf459fddf55263c8fc))
-* determine which optional packages are installed ([7e062e2](https://github.com/iloveitaly/structlog-config/commit/7e062e2a50902ce53295730d8ad69faa387b1997))
-* improve CI workflow and project setup ([2338dd0](https://github.com/iloveitaly/structlog-config/commit/2338dd06ed1c044123a11f5cc08278130da31d21))
-* update logger config for testing and add is_pytest function ([fe579ca](https://github.com/iloveitaly/structlog-config/commit/fe579ca8c0210934ca7d85294b6d3b5a1d567c68))
-
-
-### Bug Fixes
-
-* dynamically pull the LOG_LEVEL from env for testing ([0cceb7c](https://github.com/iloveitaly/structlog-config/commit/0cceb7c541bd3f2d03ccf71392ee56ba5ae7f0bd))
-* ensure copier uses current HEAD for updates ([20b9f9d](https://github.com/iloveitaly/structlog-config/commit/20b9f9d64f7c09d22d149162af332954cad5d070))
-
-
-### Documentation
-
-* add comments to middleware and formatter functions ([bf43006](https://github.com/iloveitaly/structlog-config/commit/bf43006ad538aa9e369c9a9fa251161feee0ea77))
-* add FastAPI access logger section to README.md ([93c6d98](https://github.com/iloveitaly/structlog-config/commit/93c6d98e5441f6f4c5e69dc9c618dfcfb556e7f4))
-* elaborate on FastAPI Access Logger usage and benefits ([aa4223e](https://github.com/iloveitaly/structlog-config/commit/aa4223e9db3726d5c12e699116ab84063103765b))
-* update project description and keywords in pyproject.toml ([6424d8a](https://github.com/iloveitaly/structlog-config/commit/6424d8a440d474a8feb4c8ddff322b2e17241126))

structlog_config-0.2.0/Makefile

@@ -1,11 +0,0 @@
-setup:
-	uv venv && uv sync
-	@echo "activate: source ./.venv/bin/activate"
-
-clean:
-	rm -rf *.egg-info
-	rm -rf .venv
-
-update_copier:
-	uv tool run --with jinja2_shell_extension \
-		copier@latest update --vcs-ref=HEAD --trust --skip-tasks --skip-answered