structlog-config 0.5.0__tar.gz → 0.6.0__tar.gz

{structlog_config-0.5.0 → structlog_config-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: structlog-config
-Version: 0.5.0
+Version: 0.6.0
 Summary: 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
 Author: Michael Bianco
@@ -9,8 +9,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
+Requires-Dist: fastapi-ipware>=0.1.0 ; extra == 'fastapi'
+Requires-Python: >=3.11
 Project-URL: Repository, https://github.com/iloveitaly/structlog-config
+Provides-Extra: fastapi
 Description-Content-Type: text/markdown
 
 # Opinionated Defaults for Structlog
@@ -29,6 +31,18 @@ Here are the main goals:
 * Ability to log level and output (i.e. file path) *by logger* for easy development debugging
 * If you are using fastapi, structured logging for access logs
 
+## Installation
+
+```bash
+pip install structlog-config
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add structlog-config
+```
+
 ## Usage
 
 ```python
@@ -108,6 +122,8 @@ For example, if you wanted to [mimic `OPENAI_LOG` functionality](https://github.
 
 ## FastAPI Access Logger
 
+**Note:** Requires `pip install structlog-config[fastapi]` for FastAPI dependencies.
+
 Structured, simple access log with request timing to replace the default fastapi access log. Why?
 
 1. It's less verbose
@@ -119,6 +135,64 @@ Here's how to use it:
 1. [Disable fastapi's default logging.](https://github.com/iloveitaly/python-starter-template/blob/f54cb47d8d104987f2e4a668f9045a62e0d6818a/main.py#L55-L56)
 2. [Add the middleware to your FastAPI app.](https://github.com/iloveitaly/python-starter-template/blob/f54cb47d8d104987f2e4a668f9045a62e0d6818a/app/routes/middleware/__init__.py#L63-L65)
 
+## Pytest Plugin: Capture Logs on Failure
+
+A pytest plugin that captures logs per-test and displays them only when tests fail. This keeps your test output clean while ensuring you have all the debugging information you need when something goes wrong.
+
+### Features
+
+- Only shows logs for failing tests (keeps output clean)
+- Captures logs from all test phases (setup, call, teardown)
+- Unique log file per test
+- Optional persistent log storage for debugging
+- Automatically handles `PYTHON_LOG_PATH` environment variable
+
+### Usage
+
+Enable the plugin with the `--capture-logs-on-fail` flag:
+
+```bash
+pytest --capture-logs-on-fail
+```
+
+Or enable it permanently in `pytest.ini` or `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+addopts = ["--capture-logs-on-fail"]
+```
+
+### Persist Logs to Directory
+
+To keep all test logs for later inspection (useful for CI/CD debugging):
+
+```bash
+pytest --capture-logs-dir=./test-logs
+```
+
+This creates a log file for each test and disables automatic cleanup.
+
+### How It Works
+
+1. Sets `PYTHON_LOG_PATH` environment variable to a unique temp file for each test
+2. Your application logs (via `configure_logger()`) write to this file
+3. On test failure, the plugin prints the captured logs to stdout
+4. Log files are cleaned up after the test session (unless `--capture-logs-dir` is used)
+
+### Example Output
+
+When a test fails, you'll see:
+
+```
+FAILED tests/test_user.py::test_user_login
+
+--- Captured logs for failed test (call): tests/test_user.py::test_user_login ---
+2025-11-01 18:30:00 [info] User login started user_id=123
+2025-11-01 18:30:01 [error] Database connection failed timeout=5.0
+```
+
+For passing tests, no log output is shown, keeping your test output clean and focused.
+
 ## iPython
 
 Often it's helpful to update logging level within an iPython session. You can do this and make sure all loggers pick up on it.

{structlog_config-0.5.0 → structlog_config-0.6.0}/README.md

@@ -14,6 +14,18 @@ Here are the main goals:
 * Ability to log level and output (i.e. file path) *by logger* for easy development debugging
 * If you are using fastapi, structured logging for access logs
 
+## Installation
+
+```bash
+pip install structlog-config
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add structlog-config
+```
+
 ## Usage
 
 ```python
@@ -93,6 +105,8 @@ For example, if you wanted to [mimic `OPENAI_LOG` functionality](https://github.
 
 ## FastAPI Access Logger
 
+**Note:** Requires `pip install structlog-config[fastapi]` for FastAPI dependencies.
+
 Structured, simple access log with request timing to replace the default fastapi access log. Why?
 
 1. It's less verbose
@@ -104,6 +118,64 @@ Here's how to use it:
 1. [Disable fastapi's default logging.](https://github.com/iloveitaly/python-starter-template/blob/f54cb47d8d104987f2e4a668f9045a62e0d6818a/main.py#L55-L56)
 2. [Add the middleware to your FastAPI app.](https://github.com/iloveitaly/python-starter-template/blob/f54cb47d8d104987f2e4a668f9045a62e0d6818a/app/routes/middleware/__init__.py#L63-L65)
 
+## Pytest Plugin: Capture Logs on Failure
+
+A pytest plugin that captures logs per-test and displays them only when tests fail. This keeps your test output clean while ensuring you have all the debugging information you need when something goes wrong.
+
+### Features
+
+- Only shows logs for failing tests (keeps output clean)
+- Captures logs from all test phases (setup, call, teardown)
+- Unique log file per test
+- Optional persistent log storage for debugging
+- Automatically handles `PYTHON_LOG_PATH` environment variable
+
+### Usage
+
+Enable the plugin with the `--capture-logs-on-fail` flag:
+
+```bash
+pytest --capture-logs-on-fail
+```
+
+Or enable it permanently in `pytest.ini` or `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+addopts = ["--capture-logs-on-fail"]
+```
+
+### Persist Logs to Directory
+
+To keep all test logs for later inspection (useful for CI/CD debugging):
+
+```bash
+pytest --capture-logs-dir=./test-logs
+```
+
+This creates a log file for each test and disables automatic cleanup.
+
+### How It Works
+
+1. Sets `PYTHON_LOG_PATH` environment variable to a unique temp file for each test
+2. Your application logs (via `configure_logger()`) write to this file
+3. On test failure, the plugin prints the captured logs to stdout
+4. Log files are cleaned up after the test session (unless `--capture-logs-dir` is used)
+
+### Example Output
+
+When a test fails, you'll see:
+
+```
+FAILED tests/test_user.py::test_user_login
+
+--- Captured logs for failed test (call): tests/test_user.py::test_user_login ---
+2025-11-01 18:30:00 [info] User login started user_id=123
+2025-11-01 18:30:01 [error] Database connection failed timeout=5.0
+```
+
+For passing tests, no log output is shown, keeping your test output clean and focused.
+
 ## iPython
 
 Often it's helpful to update logging level within an iPython session. You can do this and make sure all loggers pick up on it.

structlog_config-0.6.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "structlog-config"
+version = "0.6.0"
+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"
+requires-python = ">=3.11"
+dependencies = [
+    "orjson>=3.10.15",
+    "python-decouple-typed>=3.11.0",
+    "python-ipware>=3.0.0",
+    "structlog>=25.2.0",
+]
+urls = { "Repository" = "https://github.com/iloveitaly/structlog-config" }
+authors = [{ name = "Michael Bianco", email = "mike@mikebian.co" }]
+
+[project.optional-dependencies]
+fastapi = ["fastapi-ipware>=0.1.0"]
+
+[build-system]
+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]
+dev = [
+    "fastapi>=0.115.12",
+    "httpx>=0.28.1",
+    "pytest>=8.3.3",
+    "fastapi_ipware>=0.1.0",
+]

{structlog_config-0.5.0 → structlog_config-0.6.0}/structlog_config/__init__.py

@@ -45,8 +45,7 @@ def log_processors_for_mode(json_logger: bool) -> list[structlog.types.Processor
             )
 
         return [
-            # add exc_info=True to a log and get a full stack trace attached to it
-            structlog.processors.format_exc_info,
+            # omit `structlog.processors.format_exc_info` so we can use structured logging for exceptions
             # simple, short exception rendering in prod since sentry is in place
             # https://www.structlog.org/en/stable/exceptions.html this is a customized version of dict_tracebacks
             ExceptionRenderer(

{structlog_config-0.5.0 → structlog_config-0.6.0}/structlog_config/fastapi_access_logger.py

@@ -7,7 +7,7 @@ from urllib.parse import quote
 
 import structlog
 from fastapi import FastAPI
-from python_ipware import IpWare
+from fastapi_ipware import FastAPIIpWare
 from starlette.middleware.base import RequestResponseEndpoint
 from starlette.requests import Request
 from starlette.responses import Response
@@ -15,9 +15,8 @@ from starlette.routing import Match, Mount
 from starlette.types import Scope
 from starlette.websockets import WebSocket
 
-# should name this access "access_log" or something
 log = structlog.get_logger()
-ipw = IpWare()
+ipware = FastAPIIpWare()
 
 
 def get_route_name(app: FastAPI, scope: Scope, prefix: str = "") -> str:
@@ -59,35 +58,17 @@ def client_ip_from_request(request: Request | WebSocket) -> str | None:
     """
     Get the client IP address from the request.
 
-    Headers are not case-sensitive.
-
-    Uses ipware library to properly extract client IP from various proxy headers.
+    Uses fastapi-ipware library to properly extract client IP from various proxy headers.
     Fallback to direct client connection if no proxy headers found.
     """
-    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)
+    ip, trusted_route = ipware.get_client_ip_from_request(request)
     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
 
 
@@ -101,16 +82,8 @@ def is_static_assets_request(scope: Scope) -> bool:
     Returns:
         bool: True if the request is for static assets, False otherwise.
     """
-    return (
-        scope["path"].endswith(".css")
-        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")
+    return scope["path"].endswith(
+        (".css", ".js", ".js.map", ".ico", ".png", ".jpg", ".jpeg", ".gif", ".webp")
     )
 
 

structlog_config-0.6.0/structlog_config/pytest_plugin.py

@@ -0,0 +1,222 @@
+"""
+Pytest plugin for capturing and displaying logs only on test failures.
+
+This plugin integrates with structlog-config's file logging to capture logs per-test
+and display them only when tests fail, keeping output clean for passing tests.
+
+Usage:
+    1. Install the plugin (automatically registered via entry point):
+       pip install structlog-config[fastapi]
+
+    2. Enable in pytest.ini or pyproject.toml:
+       [tool.pytest.ini_options]
+       addopts = ["--capture-logs-on-fail"]
+
+    Or enable for a single test run:
+       pytest --capture-logs-on-fail
+
+    3. Optional: Persist all logs to a directory:
+       pytest --capture-logs-dir=/path/to/logs
+
+How it works:
+    - Sets PYTHON_LOG_PATH to a unique temp file for each test
+    - Logs are written to /tmp/<project-name>-pytest-logs-*/test_name.log
+    - On test failure, prints captured logs to stdout
+    - Cleans up temp files after each test (unless --capture-logs-dir is set)
+    - Automatically disabled if PYTHON_LOG_PATH is already set
+
+Example output on failure:
+    --- Captured logs for failed test: tests/test_foo.py::test_bar ---
+    2025-10-31 23:30:00 [info] Starting test
+    2025-10-31 23:30:01 [error] Something went wrong
+"""
+
+import logging
+import os
+import re
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Generator
+
+import pytest
+
+logger = logging.getLogger(__name__)
+
+PLUGIN_KEY = pytest.StashKey[dict]()
+SESSION_TMPDIR_KEY = "session_tmpdir"
+
+
+def sanitize_filename(name: str) -> str:
+    """Replace non-filename-safe characters with underscores.
+
+    Args:
+        name: The filename to sanitize (typically a pytest nodeid).
+
+    Returns:
+        A filesystem-safe filename string.
+    """
+    return re.sub(r"[^A-Za-z0-9_.-]", "_", name)
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Register the --capture-logs-on-fail command line option.
+
+    Args:
+        parser: The pytest parser to add options to.
+    """
+    parser.addoption(
+        "--capture-logs-on-fail",
+        action="store_true",
+        default=False,
+        help="Capture logs to a temp file and dump them to stdout on test failure.",
+    )
+    parser.addoption(
+        "--capture-logs-dir",
+        action="store",
+        default=None,
+        help="Directory to persist all test logs (disables automatic cleanup).",
+    )
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_configure(config: pytest.Config) -> None:
+    """Configure the plugin at pytest startup.
+
+    Stores configuration state on the config object for use by fixtures and hooks.
+
+    Args:
+        config: The pytest config object.
+    """
+    logs_dir = config.getoption("--capture-logs-dir")
+    enabled = config.getoption("--capture-logs-on-fail") or logs_dir is not None
+    
+    plugin_config = {
+        "enabled": enabled,
+        "logs_dir": logs_dir,
+        "project_name": os.path.basename(str(config.rootdir)),
+    }
+    config.stash[PLUGIN_KEY] = plugin_config
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_sessionstart(session: pytest.Session) -> None:
+    """Create a session-level temp directory for log files.
+
+    Args:
+        session: The pytest session object.
+    """
+    config = session.config
+    plugin_config = config.stash.get(PLUGIN_KEY, {})
+    
+    if not plugin_config.get("enabled"):
+        return
+    
+    logs_dir = plugin_config.get("logs_dir")
+    if logs_dir:
+        tmpdir = Path(logs_dir)
+        tmpdir.mkdir(parents=True, exist_ok=True)
+    else:
+        project_name = plugin_config.get("project_name", "pytest")
+        tmpdir = Path(tempfile.mkdtemp(prefix=f"{project_name}-pytest-logs-"))
+    
+    plugin_config[SESSION_TMPDIR_KEY] = tmpdir
+    config.stash[PLUGIN_KEY] = plugin_config
+
+
+@pytest.hookimpl(trylast=True)
+def pytest_sessionfinish(session: pytest.Session) -> None:
+    """Clean up session-level temp directory unless --capture-logs-dir was used.
+
+    Args:
+        session: The pytest session object.
+    """
+    config = session.config
+    plugin_config = config.stash.get(PLUGIN_KEY, {})
+    
+    if not plugin_config.get("enabled"):
+        return
+    
+    logs_dir = plugin_config.get("logs_dir")
+    tmpdir = plugin_config.get(SESSION_TMPDIR_KEY)
+    
+    if tmpdir and not logs_dir:
+        shutil.rmtree(tmpdir, ignore_errors=True)
+
+
+@pytest.fixture(autouse=True)
+def capture_logs_on_fail(request: pytest.FixtureRequest) -> Generator[None, None, None]:
+    """Set up per-test log capture to a temporary file.
+
+    This fixture runs automatically for every test when --capture-logs-on-fail is enabled.
+    It sets PYTHON_LOG_PATH to redirect logs to a unique temp file, then cleans up after.
+
+    Args:
+        request: The pytest request fixture providing test context.
+
+    Yields:
+        Control back to the test, then handles cleanup after test completion.
+    """
+    config = request.config
+    plugin_config = config.stash.get(PLUGIN_KEY, {})
+    
+    if not plugin_config.get("enabled"):
+        yield
+        return
+
+    if "PYTHON_LOG_PATH" in os.environ:
+        logger.warning(
+            "PYTHON_LOG_PATH is already set; pytest-capture-logs-on-fail plugin is disabled for this test."
+        )
+        yield
+        return
+
+    tmpdir = plugin_config.get(SESSION_TMPDIR_KEY)
+    if not tmpdir:
+        logger.warning("Session temp directory not initialized")
+        yield
+        return
+
+    test_name = sanitize_filename(request.node.nodeid)
+    log_file = tmpdir / f"{test_name}.log"
+    
+    original_log_path = os.environ.get("PYTHON_LOG_PATH")
+    os.environ["PYTHON_LOG_PATH"] = str(log_file)
+
+    logger.info(f"Logs for test '{request.node.nodeid}' will be stored at: {log_file}")
+
+    yield
+
+    setattr(request.node, "_pytest_log_file", str(log_file))
+    
+    if original_log_path is not None:
+        os.environ["PYTHON_LOG_PATH"] = original_log_path
+    else:
+        del os.environ["PYTHON_LOG_PATH"]
+
+
+def pytest_runtest_makereport(item: pytest.Item, call: pytest.CallInfo) -> None:
+    """Hook called after each test phase to create test reports.
+
+    On test failure, reads and prints the captured log file to stdout.
+    Handles failures in setup, call, and teardown phases.
+
+    Args:
+        item: The test item being reported on.
+        call: The call object containing execution info and any exception.
+    """
+    config = item.config
+    plugin_config = config.stash.get(PLUGIN_KEY, {})
+    
+    if not plugin_config.get("enabled"):
+        return
+
+    if call.excinfo is not None:
+        log_file = getattr(item, "_pytest_log_file", None)
+        if log_file and os.path.exists(log_file):
+            with open(log_file, "r") as f:
+                logs = f.read()
+            
+            if logs.strip():
+                phase = call.when
+                print(f"\n--- Captured logs for failed test ({phase}): {item.nodeid} ---\n{logs}\n")

{structlog_config-0.5.0 → structlog_config-0.6.0}/structlog_config/stdlib_logging.py

@@ -11,7 +11,6 @@ from decouple import config
 
 from .constants import PYTHONASYNCIODEBUG
 from .env_config import get_custom_logger_config
-from .environments import is_production, is_staging
 from .levels import (
     compare_log_levels,
     get_environment_log_level_as_string,
@@ -49,14 +48,18 @@ def redirect_stdlib_loggers(json_logger: bool):
 
     default_processors = get_default_processors(json_logger=json_logger)
 
+    if json_logger:
+        # don't use ORJSON here, as the stdlib formatter chain expects a str not a bytes
+        final_renderer = structlog.processors.JSONRenderer(sort_keys=True)
+    else:
+        # use the default renderer, which is the last processor
+        final_renderer = default_processors[-1]
+
     formatter = ProcessorFormatter(
         processors=[
             # required to strip extra keys that the structlog stdlib bindings add in
             structlog.stdlib.ProcessorFormatter.remove_processors_meta,
-            default_processors[-1]
-            if not is_production() and not is_staging()
-            # don't use ORJSON here, as the stdlib formatter chain expects a str not a bytes
-            else structlog.processors.JSONRenderer(sort_keys=True),
+            final_renderer,
         ],
         # processors unique to stdlib logging
         foreign_pre_chain=[

{structlog_config-0.5.0 → structlog_config-0.6.0}/structlog_config/trace.py

@@ -1,9 +1,11 @@
 """
+Adds a TRACE log level to the standard logging module and structlog.
+
+Some people believe that the standard log levels are not enough, and I'm with them.
+
 Adapted from:
 - https://github.com/willmcgugan/httpx/blob/973d1ed4e06577d928061092affe8f94def03331/httpx/_utils.py#L231
 - https://github.com/vladmandic/sdnext/blob/d5d857aa961edbc46c9e77e7698f2e60011e7439/installer.py#L154
-
-TODO this is not fully integrated into the codebase
 """
 
 import logging

structlog_config-0.5.0/pyproject.toml

@@ -1,61 +0,0 @@
-[project]
-name = "structlog-config"
-version = "0.5.0"
-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"
-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 = ["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 = [
-    "colorama>=0.4.6",
-    "datamodel-code-generator>=0.28.5",
-    "debugpy>=1.8.13",
-    "docrepr>=0.2.0",
-    "funcy-pipe>=0.11.1",
-    "httpdbg>=1.1.2",
-    "icecream>=2.1.4",
-    "ipdb",
-    "ipython>=8.34.0",
-    "ipython-autoimport>=0.5.1",
-    "ipython-ctrlr-fzf>=0.2.1",
-    "ipython-playground>=0.2.0",
-    "ipython-suggestions",
-    "ipythonclipboard>=1.0b2",
-    "jedi>=0.19.2",
-    "pdbr[ipython]>=0.9.0",
-    "pipdeptree>=2.26.0",
-    "pre-commit>=4.2.0",
-    "pretty-traceback",
-    "pudb>=2024.1.3",
-    "py-spy>=0.4.0",
-    "pyfzf>=0.3.1",
-    "pytest-fzf>=0.1.2.post1",
-    "rich>=14.0.0",
-    "rpdb>=0.2.0",
-    "sqlparse>=0.5.3",
-    "uv-development-toggle>=0.4.0",
-]
-dev = ["fastapi>=0.115.12", "httpx>=0.28.1", "pytest>=8.3.3"]
-
-[tool.uv.sources]
-ipdb = { git = "https://github.com/iloveitaly/ipdb", rev = "support-executables" }
-pdbr = { git = "https://github.com/iloveitaly/pdbr", rev = "ipython-9.x" }
-pretty-traceback = { git = "https://github.com/iloveitaly/pretty-traceback.git", rev = "custom" }
-ipython-suggestions = { git = "https://github.com/iloveitaly/ipython-suggestions.git", rev = "ipython-9.x" }