structlog-config 0.7.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

structlog_config/__init__.py

@@ -1,5 +1,5 @@
 from contextlib import _GeneratorContextManager
-from typing import Generator, Protocol
+from typing import Protocol
 
 import orjson
 import structlog
@@ -20,11 +20,12 @@ from structlog_config.formatters import (
 
 from . import (
     packages,
-    trace,  # noqa: F401
+    trace,  # noqa: F401 (import has side effects for trace level setup)
 )
 from .constants import NO_COLOR, package_logger
-from .environments import is_production, is_pytest, is_staging
+from .environments import is_pytest
 from .levels import get_environment_log_level_as_string
+from .hook import install_exception_hook
 from .stdlib_logging import (
     redirect_stdlib_loggers,
 )
@@ -62,12 +63,16 @@ def log_processors_for_mode(json_logger: bool) -> list[structlog.types.Processor
             structlog.processors.JSONRenderer(serializer=orjson_dumps_sorted),
         ]
 
+    # Passing None skips the ConsoleRenderer default, so use the explicit dev default.
+    exception_formatter = structlog.dev.default_exception_formatter
+
+    if packages.beautiful_traceback:
+        exception_formatter = beautiful_traceback_exception_formatter
+
     return [
         structlog.dev.ConsoleRenderer(
             colors=not NO_COLOR,
-            exception_formatter=beautiful_traceback_exception_formatter
-            if packages.beautiful_traceback
-            else structlog.dev.default_exception_formatter,
+            exception_formatter=exception_formatter,
         )
     ]
 
@@ -142,6 +147,10 @@ class LoggerWithContext(FilteringBoundLogger, Protocol):
         "clear thread-local context"
         ...
 
+    def trace(self, *args, **kwargs) -> None:  # noqa: F811
+        "trace level logging"
+        ...
+
 
 # TODO this may be a bad idea, but I really don't like how the `bound` stuff looks and how to access it, way too ugly
 def add_simple_context_aliases(log) -> LoggerWithContext:
@@ -153,7 +162,10 @@ def add_simple_context_aliases(log) -> LoggerWithContext:
 
 
 def configure_logger(
-    *, logger_factory=None, json_logger: bool | None = None
+    *,
+    json_logger: bool = False,
+    logger_factory=None,
+    install_exception_hook: bool = False,
 ) -> LoggerWithContext:
     """
     Create a struct logger with some special additions:
@@ -166,9 +178,10 @@ def configure_logger(
     >>> log.clear()
 
     Args:
+        json_logger: Flag to use JSON logging. Defaults to False.
         logger_factory: Optional logger factory to override the default
-        json_logger: Optional flag to use JSON logging. If None, defaults to
-            production or staging environment sourced from PYTHON_ENV.
+        install_exception_hook: Optional flag to install a global exception hook
+            that logs uncaught exceptions using structlog. Defaults to False.
     """
     setup_trace()
 
@@ -176,8 +189,10 @@ def configure_logger(
     # This is important for tests where configure_logger might be called multiple times
     structlog.reset_defaults()
 
-    if json_logger is None:
-        json_logger = is_production() or is_staging()
+    if install_exception_hook:
+        from .hook import install_exception_hook as _install_hook
+
+        _install_hook(json_logger)
 
     redirect_stdlib_loggers(json_logger)
     redirect_showwarnings()

structlog_config/environments.py

@@ -1,31 +1,8 @@
 import os
-import typing as t
-
-from decouple import config
-
-
-def python_environment() -> str:
-    return t.cast(str, config("PYTHON_ENV", default="development", cast=str)).lower()
-
-
-def is_testing():
-    return python_environment() == "test"
-
-
-def is_production():
-    return python_environment() == "production"
-
-
-def is_staging():
-    return python_environment() == "staging"
-
-
-def is_development():
-    return python_environment() == "development"
 
 
 def is_pytest():
     """
     PYTEST_CURRENT_TEST is set by pytest to indicate the current test being run
     """
-    return "PYTEST_CURRENT_TEST" in os.environ
+    return "PYTEST_CURRENT_TEST" in os.environ

structlog_config/fastapi_access_logger.py

@@ -61,7 +61,7 @@ def client_ip_from_request(request: Request | WebSocket) -> str | None:
     Uses fastapi-ipware library to properly extract client IP from various proxy headers.
     Fallback to direct client connection if no proxy headers found.
     """
-    ip, trusted_route = ipware.get_client_ip_from_request(request)
+    ip, trusted_route = ipware.get_client_ip_from_request(request)  # type: ignore
     if ip:
         log.debug(
             "extracted client IP from headers", ip=ip, trusted_route=trusted_route

structlog_config/formatters.py

@@ -21,9 +21,9 @@ def simplify_activemodel_objects(
     What's tricky about this method, and other structlog processors, is they are run *after* a response
     is returned to the user. So, they don't error out in tests and it doesn't impact users. They do show up in Sentry.
     """
-    from activemodel import BaseModel
-    from sqlalchemy.orm.base import object_state
-    from typeid import TypeID
+    from activemodel import BaseModel  # type: ignore
+    from sqlalchemy.orm.base import object_state  # type: ignore
+    from typeid import TypeID  # type: ignore
 
     for key, value in list(event_dict.items()):
         if isinstance(value, BaseModel):
@@ -77,6 +77,7 @@ def beautiful_traceback_exception_formatter(sio: TextIO, exc_info: ExcInfo) -> N
     from beautiful_traceback.formatting import exc_to_traceback_str
 
     _, exc_value, traceback = exc_info
+    assert traceback is not None
     # 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)
@@ -180,7 +181,7 @@ def add_fastapi_context(
 
     https://github.com/tomwojcik/starlette-context/blob/master/example/setup_logging.py
     """
-    from starlette_context import context
+    from starlette_context import context  # type: ignore
 
     if context.exists():
         event_dict.update(context.data)

structlog_config/hook.py

@@ -0,0 +1,20 @@
+import sys
+
+import structlog
+
+
+def install_exception_hook(json_logger: bool = False):
+    def structlog_excepthook(exc_type, exc_value, exc_traceback):
+        if issubclass(exc_type, KeyboardInterrupt):
+            sys.__excepthook__(exc_type, exc_value, exc_traceback)
+            return
+
+        logger = structlog.get_logger()
+
+        # We rely on structlog's configuration (configured in __init__.py) 
+        # to handle the exception formatting based on whether it's JSON or Console mode.
+        logger.exception(
+            "uncaught_exception", exc_info=(exc_type, exc_value, exc_traceback)
+        )
+
+    sys.excepthook = structlog_excepthook

structlog_config/packages.py

@@ -3,36 +3,36 @@ Determine if certain packages are installed to conditionally enable processors
 """
 
 try:
-    import orjson
+    import orjson  # type: ignore
 except ImportError:
     orjson = None
 
 try:
-    import sqlalchemy
+    import sqlalchemy  # type: ignore
 except ImportError:
     sqlalchemy = None
 
 try:
-    import activemodel
+    import activemodel  # type: ignore
 except ImportError:
     activemodel = None
 
 try:
-    import typeid
+    import typeid  # type: ignore
 except ImportError:
     typeid = None
 
 try:
-    import beautiful_traceback
+    import beautiful_traceback  # type: ignore
 except ImportError:
     beautiful_traceback = None
 
 try:
-    import starlette_context
+    import starlette_context  # type: ignore
 except ImportError:
     starlette_context = None
 
 try:
-    import whenever
+    import whenever  # type: ignore
 except ImportError:
     whenever = None

structlog_config/pytest_plugin.py

@@ -1,222 +1,404 @@
-"""
-Pytest plugin for capturing and displaying logs only on test failures.
+"""Pytest plugin for capturing test output to files on failure.
+
+This plugin captures stdout, stderr, and exceptions from failing tests and writes
+them to organized output directories. It supports both simple capture (via sys.stdout/stderr
+replacement) and fd-level capture (for subprocess output).
+
+Relationship to pytest's built-in capture:
+    - pytest has built-in output capture that shows output only for failing tests
+    - This plugin REPLACES pytest's capture (we require -s to disable it)
+    - Instead of showing output inline, we write it to organized files
+    - Useful for CI/CD where you need persistent files to inspect later
+
+Capture modes:
+    1. SimpleCapture (default): Like pytest's capture, replaces sys.stdout/stderr
+       - Captures: print(), logging, most Python output
+       - Misses: subprocess output, direct fd writes
 
-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.
+    2. FdCapture (opt-in): OS-level file descriptor redirection
+       - Captures: everything SimpleCapture does PLUS subprocess output
+       - Activate via _fd_capture fixture in conftest.py
 
 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
+    pytest --structlog-output=./test-output -s
+
+Options:
+    --structlog-output=DIR      Enable output capture and write to DIR
+
+Requirements:
+    - Must use -s (--capture=no) flag to disable pytest's built-in capture
+
+Output Structure:
+    DIR/
+        test_module__test_name/
+            stdout.txt      # stdout from test
+            stderr.txt      # stderr from test
+            exception.txt   # exception traceback
+
+Enabling fd-level capture (optional):
+    To capture subprocess output, you have three options:
+
+    1. Single test - add to function signature:
+       def test_foo(file_descriptor_output_capture):
+           ...
+
+    2. Single test - use marker decorator:
+       @pytest.mark.usefixtures("file_descriptor_output_capture")
+       def test_foo():
+           ...
+
+    3. All tests in directory - add to conftest.py:
+       import pytest
+       pytestmark = pytest.mark.usefixtures("file_descriptor_output_capture")
 """
 
-import logging
 import os
-import re
-import shutil
+import sys
 import tempfile
+from dataclasses import dataclass
 from pathlib import Path
-from typing import Generator
 
 import pytest
+import structlog
+
+logger = structlog.get_logger(logger_name=__name__)
 
-logger = logging.getLogger(__name__)
+CAPTURE_KEY = pytest.StashKey[dict]()
 
-PLUGIN_KEY = pytest.StashKey[dict]()
-SESSION_TMPDIR_KEY = "session_tmpdir"
 
+@dataclass
+class CapturedOutput:
+    """Container for captured output from a test phase."""
 
-def sanitize_filename(name: str) -> str:
-    """Replace non-filename-safe characters with underscores.
+    stdout: str
+    stderr: str
+    exception: str | None = None
 
-    Args:
-        name: The filename to sanitize (typically a pytest nodeid).
 
-    Returns:
-        A filesystem-safe filename string.
+class SimpleCapture:
+    """Captures via sys.stdout/sys.stderr replacement. No subprocess support.
+
+    This works similarly to pytest's built-in capture (which we disable with -s).
+    It replaces sys.stdout and sys.stderr with StringIO objects, capturing any
+    Python code that writes to these streams (print(), logging, etc.).
+
+    Limitations:
+    - Does NOT capture subprocess output (subprocesses inherit file descriptors,
+      not Python sys.stdout/stderr objects)
+    - Does NOT capture direct file descriptor writes (os.write(1, ...))
+    - Only captures output from the current Python process
+
+    This is the default capture mode and works for most tests. Use FdCapture
+    (via the _fd_capture fixture) if you need to capture subprocess output.
     """
-    return re.sub(r"[^A-Za-z0-9_.-]", "_", name)
 
+    def __init__(self):
+        self._stdout_capture = None
+        self._stderr_capture = None
+        self._orig_stdout = None
+        self._orig_stderr = None
+
+    def start(self):
+        """Start capturing stdout and stderr."""
+        import io
+        import logging
+
+        self._orig_stdout = sys.stdout
+        self._orig_stderr = sys.stderr
+        self._stdout_capture = io.StringIO()
+        self._stderr_capture = io.StringIO()
+        sys.stdout = self._stdout_capture
+        sys.stderr = self._stderr_capture
+
+        # Update any existing logging handlers that point to the old stdout/stderr
+        # This ensures stdlib loggers created before capture started will output
+        # to our StringIO objects instead of the original streams
+        for handler in logging.root.handlers[:]:
+            if isinstance(handler, logging.StreamHandler):
+                if handler.stream == self._orig_stdout:
+                    handler.setStream(self._stdout_capture)  # type: ignore[arg-type]
+                elif handler.stream == self._orig_stderr:
+                    handler.setStream(self._stderr_capture)  # type: ignore[arg-type]
+
+    def stop(self) -> CapturedOutput:
+        """Stop capturing and return captured output."""
+        import logging
+
+        # Restore logging handlers to original streams
+        for handler in logging.root.handlers[:]:
+            if isinstance(handler, logging.StreamHandler):
+                if handler.stream == self._stdout_capture:
+                    handler.setStream(self._orig_stdout)  # type: ignore[arg-type]
+                elif handler.stream == self._stderr_capture:
+                    handler.setStream(self._orig_stderr)  # type: ignore[arg-type]
+
+        sys.stdout = self._orig_stdout
+        sys.stderr = self._orig_stderr
+
+        stdout = self._stdout_capture.getvalue() if self._stdout_capture else ""
+        stderr = self._stderr_capture.getvalue() if self._stderr_capture else ""
+
+        return CapturedOutput(stdout=stdout, stderr=stderr)
+
+
+class FdCapture:
+    """Captures at file descriptor level. Supports subprocess output.
+
+    This provides deeper capture than SimpleCapture by redirecting at the OS level.
+    Instead of just replacing Python's sys.stdout/stderr objects, it redirects
+    the actual file descriptors (1=stdout, 2=stderr) that the OS uses.
+
+    How it works:
+    1. Backup original file descriptors using os.dup(1) and os.dup(2)
+    2. Create temporary files to receive the output
+    3. Use os.dup2() to redirect fd 1 and 2 to point to the temp files
+    4. Reopen sys.stdout/stderr to match the new file descriptors
+    5. All writes to fd 1/2 now go to temp files (including from subprocesses!)
+    6. On stop(), restore original fds, read temp file contents, cleanup
+
+    What this captures:
+    - Everything SimpleCapture captures (print(), logging, etc.)
+    - Subprocess output (when subprocess inherits stdout/stderr)
+    - Direct file descriptor writes (os.write(1, ...))
+    - C extension output that writes directly to fds
+
+    Comparison to pytest's built-in capture:
+    - pytest's -s flag disables pytest's capture (which is SimpleCapture-like)
+    - This plugin works INSTEAD of pytest's capture, writing to files rather
+      than showing output inline in test results
+    - FdCapture is more comprehensive than pytest's default capture
+
+    Note: Opt-in only via _fd_capture fixture due to added complexity.
+    """
 
-def pytest_addoption(parser: pytest.Parser) -> None:
-    """Register the --capture-logs-on-fail command line option.
+    def __init__(self):
+        self._stdout_fd: int | None = None
+        self._stderr_fd: int | None = None
+        self._stdout_file: tempfile._TemporaryFileWrapper | None = None
+        self._stderr_file: tempfile._TemporaryFileWrapper | None = None
+        self._orig_stdout_fd: int | None = None
+        self._orig_stderr_fd: int | None = None
+        self._orig_stdout = None
+        self._orig_stderr = None
+
+    def start(self):
+        """Start capturing stdout and stderr at the file descriptor level."""
+        sys.stdout.flush()
+        sys.stderr.flush()
+
+        self._orig_stdout = sys.stdout
+        self._orig_stderr = sys.stderr
+        self._orig_stdout_fd = os.dup(1)
+        self._orig_stderr_fd = os.dup(2)
+
+        self._stdout_file = tempfile.NamedTemporaryFile(
+            mode="w+b", delete=False
+        )
+        self._stderr_file = tempfile.NamedTemporaryFile(
+            mode="w+b", delete=False
+        )
+
+        os.dup2(self._stdout_file.fileno(), 1)
+        os.dup2(self._stderr_file.fileno(), 2)
+
+        sys.stdout = open(1, "w", encoding="utf-8", errors="replace", closefd=False)
+        sys.stderr = open(2, "w", encoding="utf-8", errors="replace", closefd=False)
+
+    def stop(self) -> CapturedOutput:
+        """Stop capturing and return captured output."""
+        try:
+            sys.stdout.flush()
+            sys.stderr.flush()
+            os.fsync(1)
+            os.fsync(2)
+
+            assert self._orig_stdout_fd is not None
+            assert self._orig_stderr_fd is not None
+            assert self._stdout_file is not None
+            assert self._stderr_file is not None
+
+            os.dup2(self._orig_stdout_fd, 1)
+            os.dup2(self._orig_stderr_fd, 2)
+            os.close(self._orig_stdout_fd)
+            os.close(self._orig_stderr_fd)
+
+            sys.stdout = self._orig_stdout
+            sys.stderr = self._orig_stderr
 
-    Args:
-        parser: The pytest parser to add options to.
+            self._stdout_file.flush()
+            self._stderr_file.flush()
+            self._stdout_file.seek(0)
+            self._stderr_file.seek(0)
+            stdout = self._stdout_file.read().decode("utf-8", errors="replace")
+            stderr = self._stderr_file.read().decode("utf-8", errors="replace")
+
+            self._stdout_file.close()
+            self._stderr_file.close()
+
+            os.unlink(self._stdout_file.name)
+            os.unlink(self._stderr_file.name)
+
+            return CapturedOutput(stdout=stdout, stderr=stderr)
+        except Exception:
+            sys.stdout = self._orig_stdout
+            sys.stderr = self._orig_stderr
+            raise
+
+
+def _validate_pytest_config(config: pytest.Config) -> bool:
+    """Check that -s is enabled. Log error if not.
+
+    Note: We also recommend using -p no:logging to disable pytest's logging plugin,
+    but we can't reliably detect if it's enabled. The pluginmanager.has_plugin()
+    check doesn't work consistently across pytest versions. The plugin will work
+    regardless, but having both logging captures enabled may cause confusion.
     """
-    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",
+    capture_mode = config.option.capture
+
+    if capture_mode != "no":
+        logger.error(
+            "structlog output capture requires -s flag to disable pytest's built-in capture",
+            pytest_capture_mode=capture_mode,
+            required_flag="-s or --capture=no",
+        )
+        return False
+
+    return True
+
+
+def pytest_addoption(parser: pytest.Parser):
+    """Add command line options for output capture."""
+    group = parser.getgroup("Structlog Capture")
+    group.addoption(
+        "--structlog-output",
+        type=str,
         default=None,
-        help="Directory to persist all test logs (disables automatic cleanup).",
+        metavar="DIR",
+        help="Enable output capture on test failure and write to DIR",
     )
 
 
 @pytest.hookimpl(tryfirst=True)
-def pytest_configure(config: pytest.Config) -> None:
-    """Configure the plugin at pytest startup.
+def pytest_configure(config: pytest.Config):
+    """Configure the plugin."""
+    output_dir_str = config.option.structlog_output
 
-    Stores configuration state on the config object for use by fixtures and hooks.
+    if not output_dir_str:
+        config.stash[CAPTURE_KEY] = {"enabled": False}
+        return
 
-    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)),
+    if not _validate_pytest_config(config):
+        config.stash[CAPTURE_KEY] = {"enabled": False}
+        return
+
+    output_dir = Path(output_dir_str)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    config.stash[CAPTURE_KEY] = {
+        "enabled": True,
+        "output_dir": str(output_dir),
     }
-    config.stash[PLUGIN_KEY] = plugin_config
 
+    logger.info(
+        "structlog output capture enabled",
+        output_directory=str(output_dir),
+    )
 
-@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.fixture
+def file_descriptor_output_capture(request):
+    """Activates fd-level capture for a test.
 
+    This fixture can be used in three ways:
 
-@pytest.hookimpl(trylast=True)
-def pytest_sessionfinish(session: pytest.Session) -> None:
-    """Clean up session-level temp directory unless --capture-logs-dir was used.
+    1. Single test - add to function signature:
+       def test_foo(file_descriptor_output_capture):
+           ...
 
-    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)
+    2. Single test - use marker decorator:
+       @pytest.mark.usefixtures("file_descriptor_output_capture")
+       def test_foo():
+           ...
 
+    3. All tests in directory - add to conftest.py:
+       pytestmark = pytest.mark.usefixtures("file_descriptor_output_capture")
+    """
+    request.node._fd_capture_active = True
+    capture = FdCapture()
+    capture.start()
+    yield
+    output = capture.stop()
+    request.node._fd_captured_output = output
 
-@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.
+def _is_fd_capture_active(item: pytest.Item) -> bool:
+    """Check if the fd-level capture fixture is active for this test."""
+    return getattr(item, "_fd_capture_active", False)
 
-    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
+def _write_output_files(item: pytest.Item):
+    """Write captured output to files on failure."""
+    config = item.config.stash.get(CAPTURE_KEY, {"enabled": False})
+    if not config["enabled"]:
         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
+    if not hasattr(item, "_excinfo"):
         return
 
-    tmpdir = plugin_config.get(SESSION_TMPDIR_KEY)
-    if not tmpdir:
-        logger.warning("Session temp directory not initialized")
-        yield
+    output_dir_value = config["output_dir"]
+    if not isinstance(output_dir_value, (str, Path)):
         return
+    output_dir = Path(output_dir_value)
 
-    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)
+    test_name = item.nodeid.replace("::", "__").replace("/", "_")
+    test_dir = output_dir / test_name
+    test_dir.mkdir(parents=True, exist_ok=True)
 
-    logger.info(f"Logs for test '{request.node.nodeid}' will be stored at: {log_file}")
+    if hasattr(item, "_full_captured_output"):
+        output = item._full_captured_output  # type: ignore[attr-defined]
+    elif _is_fd_capture_active(item) and hasattr(item, "_fd_captured_output"):
+        output = item._fd_captured_output  # type: ignore[attr-defined]
+    else:
+        output = CapturedOutput(stdout="", stderr="")
 
-    yield
+    exception_parts = []
+    for _when, excinfo in item._excinfo:  # type: ignore[attr-defined]
+        exception_parts.append(str(excinfo.getrepr(style="long")))
 
-    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"]
+    output.exception = "\n\n".join(exception_parts) if exception_parts else None
 
+    if output.stdout:
+        (test_dir / "stdout.txt").write_text(output.stdout)
 
-def pytest_runtest_makereport(item: pytest.Item, call: pytest.CallInfo) -> None:
-    """Hook called after each test phase to create test reports.
+    if output.stderr:
+        (test_dir / "stderr.txt").write_text(output.stderr)
 
-    On test failure, reads and prints the captured log file to stdout.
-    Handles failures in setup, call, and teardown phases.
+    if output.exception:
+        (test_dir / "exception.txt").write_text(output.exception)
+
+
+@pytest.hookimpl(wrapper=True, tryfirst=True)
+def pytest_runtest_protocol(item: pytest.Item, nextitem: pytest.Item | None):  # noqa: ARG001
+    """Capture output for entire test lifecycle including makereport phases."""
+    config = item.config.stash.get(CAPTURE_KEY, {"enabled": False})
+
+    if not config["enabled"] or _is_fd_capture_active(item):
+        return (yield)
+
+    capture = SimpleCapture()
+    capture.start()
+    try:
+        result = yield
+        return result
+    finally:
+        output = capture.stop()
+        item._full_captured_output = output  # type: ignore[attr-defined]
+        _write_output_files(item)
 
-    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
 
+def pytest_runtest_makereport(item: pytest.Item, call: pytest.CallInfo):
+    """Track exception info for failed tests."""
     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")
+        if not hasattr(item, "_excinfo"):
+            item._excinfo = []  # type: ignore[attr-defined]
+        item._excinfo.append((call.when, call.excinfo))  # type: ignore[attr-defined]

structlog_config/stdlib_logging.py

@@ -5,6 +5,7 @@ Redirect all stdlib loggers to use the structlog configuration.
 import logging
 import sys
 from pathlib import Path
+from typing import Any
 
 import structlog
 from decouple import config
@@ -101,7 +102,7 @@ def redirect_stdlib_loggers(json_logger: bool):
 
     # 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 = {
+    std_logging_configuration: dict[str, dict[str, Any]] = {
         "httpx": {
             "levels": {
                 "INFO": "WARNING",

structlog_config/trace.py

@@ -12,7 +12,8 @@ import logging
 import typing
 from functools import partial, partialmethod
 
-from structlog._log_levels import NAME_TO_LEVEL
+from structlog import _output
+from structlog._log_levels import LEVEL_TO_NAME, NAME_TO_LEVEL
 from structlog._native import LEVEL_TO_FILTERING_LOGGER, _make_filtering_bound_logger
 
 from structlog_config.constants import TRACE_LOG_LEVEL
@@ -28,11 +29,6 @@ class Logger(logging.Logger):
     ) -> None: ...  # pragma: nocover
 
 
-# def trace(self, message: str, *args: typing.Any, **kwargs: typing.Any) -> None:
-#     if self.isEnabledFor(TRACE_LOG_LEVEL):
-#         self._log(TRACE_LOG_LEVEL, message, args, **kwargs)
-
-
 def setup_trace() -> None:
     """Setup TRACE logging level. Safe to call multiple times."""
     global _setup_called
@@ -41,24 +37,55 @@ def setup_trace() -> None:
         return
 
     # TODO consider adding warning to check the state of the underlying patched code
-    # patch structlog maps to include the additional level
+
+    # patch structlog maps to include the additional level, there are three separate places that need to be patched
     NAME_TO_LEVEL["trace"] = TRACE_LOG_LEVEL
+    LEVEL_TO_NAME[TRACE_LOG_LEVEL] = "trace"
     LEVEL_TO_FILTERING_LOGGER[TRACE_LOG_LEVEL] = _make_filtering_bound_logger(
         TRACE_LOG_LEVEL
     )
 
-    logging.TRACE = TRACE_LOG_LEVEL
+    # Check if TRACE attribute already exists in logging module
+    if not hasattr(logging, "TRACE"):
+        setattr(logging, "TRACE", TRACE_LOG_LEVEL)
+
     logging.addLevelName(TRACE_LOG_LEVEL, "TRACE")
 
+    # patches are guarded with hasattr since the user could have patched this on their own
+
     if hasattr(logging.Logger, "trace"):
         logging.warning("Logger.trace method already exists, not overriding it")
     else:
-        logging.Logger.trace = partialmethod(logging.Logger.log, logging.TRACE)
+        setattr(
+            logging.Logger,
+            "trace",
+            partialmethod(logging.Logger.log, TRACE_LOG_LEVEL),
+        )
 
-    # Check if trace function already exists in logging module
     if hasattr(logging, "trace"):
-        logging.warning("logging.trace function already exists, overriding it")
+        logging.warning("logging.trace function already exists, not overriding it")
     else:
-        logging.trace = partial(logging.log, logging.TRACE)
+        setattr(logging, "trace", partial(logging.log, TRACE_LOG_LEVEL))
+
+    _patch_structlog_output_loggers()
 
     _setup_called = True
+
+
+def _patch_structlog_output_loggers() -> None:
+    """
+    Each individual logger backend needs to be patched.
+
+    There's no structlog API to get a list of all available loggers.
+    """
+    logger_classes = (
+        _output.PrintLogger,
+        _output.WriteLogger,
+        _output.BytesLogger,
+    )
+
+    for logger_class in logger_classes:
+        if hasattr(logger_class, "trace"):
+            continue
+
+        setattr(logger_class, "trace", logger_class.msg)

{structlog_config-0.7.0.dist-info → structlog_config-0.9.0.dist-info}/METADATA

@@ -1,13 +1,13 @@
 Metadata-Version: 2.3
 Name: structlog-config
-Version: 0.7.0
+Version: 0.9.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
 Author-email: Michael Bianco <mike@mikebian.co>
 Requires-Dist: orjson>=3.10.15
 Requires-Dist: python-decouple-typed>=3.11.0
-Requires-Dist: python-ipware>=3.0.0
+Requires-Dist: fastapi-ipware>=0.1.1
 Requires-Dist: structlog>=25.2.0
 Requires-Dist: fastapi-ipware>=0.1.0 ; extra == 'fastapi'
 Requires-Python: >=3.11
@@ -26,19 +26,16 @@ Here are the main goals:
 * High performance JSON logging in production
 * All loggers, even plugin or system loggers, should route through the same formatter
 * Structured logging everywhere
+* Pytest plugin to easily capture logs and dump to a directory on failure. This is really important for LLMs so they can
+  easily consume logs and context for each test and handle them sequentially.
 * Ability to easily set thread-local log context
 * Nice log formatters for stack traces, ORM ([ActiveModel/SQLModel](https://github.com/iloveitaly/activemodel)), etc
 * 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
+* [Improved exception logging with beautiful-traceback](https://github.com/iloveitaly/beautiful-traceback)
 
 ## Installation
 
-```bash
-pip install structlog-config
-```
-
-Or with [uv](https://docs.astral.sh/uv/):
-
 ```bash
 uv add structlog-config
 ```
@@ -51,9 +48,12 @@ from structlog_config import configure_logger
 log = configure_logger()
 
 log.info("the log", key="value")
+
+# named logger just like stdlib, but with a different syntax
+custom_named_logger = structlog.get_logger(logger_name="test")
 ```
 
-## JSON Logging for Production
+## JSON Logging in Production
 
 JSON logging is automatically enabled in production and staging environments (`PYTHON_ENV=production` or `PYTHON_ENV=staging`):
 
@@ -72,11 +72,13 @@ log = configure_logger(json_logger=True)
 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).
+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.
+This package adds support for a custom `TRACE` logging level (level 5) that's even more verbose than `DEBUG`.
 
 The `TRACE` level is automatically set up when you call `configure_logger()`. You can use it like any other logging level:
 
@@ -88,7 +90,7 @@ log = configure_logger()
 
 # Using structlog
 log.info("This is info")
-log.debug("This is debug") 
+log.debug("This is debug")
 log.trace("This is trace")  # Most verbose
 
 # Using stdlib logging
@@ -136,8 +138,6 @@ log.info("Processing file", file_path=Path.cwd() / "data" / "users.csv")
 
 ### Whenever Datetime Formatter
 
-**Note:** Requires `pip install whenever` to be installed.
-
 Formats [whenever](https://github.com/ariebovenberg/whenever) datetime objects without their class wrappers for cleaner output:
 
 ```python
@@ -152,8 +152,6 @@ Supports all whenever datetime types: `ZonedDateTime`, `Instant`, `LocalDateTime
 
 ### ActiveModel Object Formatter
 
-**Note:** Requires `pip install activemodel` and `pip install typeid-python` to be installed.
-
 Automatically converts [ActiveModel](https://github.com/iloveitaly/activemodel) BaseModel instances to their ID representation and TypeID objects to strings:
 
 ```python
@@ -166,8 +164,6 @@ log.info("User action", user=user)
 
 ### FastAPI Context
 
-**Note:** Requires `pip install starlette-context` to be installed.
-
 Automatically includes all context data from [starlette-context](https://github.com/tomwojcik/starlette-context) in your logs, useful for request tracing:
 
 ```python
@@ -193,63 +189,102 @@ 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
+## Pytest Plugin: Capture Output 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.
+A pytest plugin that captures stdout, stderr, and exceptions from failing tests and writes them to organized output files. This is useful for debugging test failures, especially in CI/CD environments where you need to inspect output after the fact.
 
 ### 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
+- Captures stdout, stderr, and exception tracebacks for failing tests
+- Only creates output for failing tests (keeps directories clean)
+- Separate files for each output type (stdout.txt, stderr.txt, exception.txt)
+- Captures all test phases (setup, call, teardown)
+- Optional fd-level capture for subprocess output
 
 ### Usage
 
-Enable the plugin with the `--capture-logs-on-fail` flag:
+Enable the plugin with the `--structlog-output` flag and `-s` (to disable pytest's built-in capture):
 
 ```bash
-pytest --capture-logs-on-fail
+pytest --structlog-output=./test-output -s
 ```
 
-Or enable it permanently in `pytest.ini` or `pyproject.toml`:
+The `--structlog-output` flag both enables the plugin and specifies where output files should be written.
+
+**Recommended:** Also disable pytest's logging plugin with `-p no:logging` to avoid duplicate/interfering capture:
 
-```toml
-[tool.pytest.ini_options]
-addopts = ["--capture-logs-on-fail"]
+```bash
+pytest --structlog-output=./test-output -s -p no:logging
 ```
 
-### Persist Logs to Directory
+While the plugin works without this flag, disabling pytest's logging capture ensures cleaner output and avoids any potential conflicts between the two capture mechanisms.
 
-To keep all test logs for later inspection (useful for CI/CD debugging):
+### Output Structure
 
-```bash
-pytest --capture-logs-dir=./test-logs
+Each failing test gets its own directory with separate files:
+
+```
+test-output/
+    test_module__test_name/
+        stdout.txt      # stdout from test (includes setup, call, and teardown phases)
+        stderr.txt      # stderr from test (includes setup, call, and teardown phases)
+        exception.txt   # exception traceback
+```
+
+### Advanced: fd-level Capture
+
+For tests that spawn subprocesses or write directly to file descriptors, you can enable fd-level capture. This is useful for integration tests that run external processes (such a server which replicates a production environment).
+
+#### Add fixture to function signature
+
+Great for a single single test:
+
+```python
+def test_with_subprocess(file_descriptor_output_capture):
+    # subprocess.run() output will be captured
+    subprocess.run(["echo", "hello from subprocess"])
+
+    # multiprocessing.Process output will be captured
+    from multiprocessing import Process
+    proc = Process(target=lambda: print("hello from process"))
+    proc.start()
+    proc.join()
+
+    assert False  # Trigger failure to write output files
 ```
 
-This creates a log file for each test and disables automatic cleanup.
+Alternatively, you can use `@pytest.mark.usefixtures("file_descriptor_output_capture")`
 
-### 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)
+#### All tests in directory
 
-### Example Output
+Add to `conftest.py`:
 
-When a test fails, you'll see:
+```python
+import pytest
 
+pytestmark = pytest.mark.usefixtures("file_descriptor_output_capture")
 ```
-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
+### Example
+
+When a test fails:
+
+```python
+def test_user_login():
+    print("Starting login process")
+    print("ERROR: Connection failed", file=sys.stderr)
+    assert False, "Login failed"
 ```
 
-For passing tests, no log output is shown, keeping your test output clean and focused.
+You'll get:
+
+```
+test-output/test_user__test_user_login/
+    stdout.txt: "Starting login process"
+    stderr.txt: "ERROR: Connection failed"
+    exception.txt: Full traceback with "AssertionError: Login failed"
+```
 
 ## Beautiful Traceback Support
 

structlog_config-0.9.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+structlog_config/__init__.py,sha256=02rdVud040i_yENnPhjAFrQvAcqePffueHwBmqXWid0,7266
+structlog_config/constants.py,sha256=O1nPnB29yZdqqaI7aeTUrimA3LOtA5WpP6BGPLWJvj8,510
+structlog_config/env_config.py,sha256=_EJO0rgAKndRPSh4wuBaH3bui9F3nIpn8FaEkjAjZso,1737
+structlog_config/environments.py,sha256=9rojSoyjS5ZOglB7X86gZIzhIsavQ03mJ1ICVk1IuLk,171
+structlog_config/fastapi_access_logger.py,sha256=NAnYJZ3uHpdrJ8Dd48I0DV6JGQtfVDT5QAYGYmHuOQI,4379
+structlog_config/formatters.py,sha256=u1u88lz-h6-NMZzpEkbvKeXq1AzbplxuyE_yIMjPOps,6812
+structlog_config/hook.py,sha256=97C9TB88Gpit8s7beTh1n3OAtt8YkAgS-Zr2Crvp9HA,656
+structlog_config/levels.py,sha256=LqXG4l01mIpxS2qI7PF_Vp9K7IrO0D5qU_x-Uo3LNuM,2372
+structlog_config/packages.py,sha256=D27IijZy2igLRPe8aNoSMM_gKL0EGyH_sCl6OTXF3ac,703
+structlog_config/pytest_plugin.py,sha256=kKhDm_Y4wOtcsAoYJ2OplnBdHaNIfF5z2XNzinvEvb0,14259
+structlog_config/stdlib_logging.py,sha256=amLVZUw46mIenTDp3LVW1sYXdHAMLOecJHkQcIuZ--c,7431
+structlog_config/trace.py,sha256=fh6gYGUrWBjk6BzZbyeLN1uo3AGGRs7rysfKC0v5wYE,2808
+structlog_config/warnings.py,sha256=gKEcuHWqH0BaKitJtQkv-uJ0Z3uCH5nn6k8qpqjR-RM,998
+structlog_config-0.9.0.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+structlog_config-0.9.0.dist-info/entry_points.txt,sha256=ZSQscydGXSpu4dzPkbUCQuRA8FjNQPwHXyZut8VzkDw,62
+structlog_config-0.9.0.dist-info/METADATA,sha256=6RGsl6gC7GLnAypkpi-19EC439n2AzlSll74geqa5OA,12356
+structlog_config-0.9.0.dist-info/RECORD,,

{structlog_config-0.7.0.dist-info → structlog_config-0.9.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.8.13
+Generator: uv 0.9.28
 Root-Is-Purelib: true
-Tag: py3-none-any
+Tag: py3-none-any

structlog_config-0.9.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[pytest11]
+structlog_config = structlog_config.pytest_plugin
+

structlog_config-0.7.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-structlog_config/__init__.py,sha256=wTIMChYHwuzzgqoahCyF6YkJxjIYb-Gpyx8LkPkUpGk,6798
-structlog_config/constants.py,sha256=O1nPnB29yZdqqaI7aeTUrimA3LOtA5WpP6BGPLWJvj8,510
-structlog_config/env_config.py,sha256=_EJO0rgAKndRPSh4wuBaH3bui9F3nIpn8FaEkjAjZso,1737
-structlog_config/environments.py,sha256=JpZYVVDGxEf1EaKdPdn6Jo-4wJK6SqF0ueFl7e2TBvI,612
-structlog_config/fastapi_access_logger.py,sha256=CYZsww0AIcdfrU5Wgr6POwdJxJ5vMB96ttsYqoE30BU,4363
-structlog_config/formatters.py,sha256=KJ3PlkrFva1RKz5SmFmEwVCqJuHxq3Qsqhd9ezB983I,6715
-structlog_config/levels.py,sha256=LqXG4l01mIpxS2qI7PF_Vp9K7IrO0D5qU_x-Uo3LNuM,2372
-structlog_config/packages.py,sha256=xO4wHPIhAwGG6jv0kHdCr9NHpoIFx4VUeRzmztXp2is,591
-structlog_config/pytest_plugin.py,sha256=XBtef1KpuGV_RmXoWf13b0EUy69iAKMAk4-e5ZZnAuM,6819
-structlog_config/stdlib_logging.py,sha256=iHApYdsAs_ZC7Y8NpbKs23AHAJB1qLUCZPvFd-Nf_4I,7381
-structlog_config/trace.py,sha256=esSzTulaVr63H3iOYpHlU-NXPSwpEGS7GEYbv6Iq-3A,2118
-structlog_config/warnings.py,sha256=gKEcuHWqH0BaKitJtQkv-uJ0Z3uCH5nn6k8qpqjR-RM,998
-structlog_config-0.7.0.dist-info/WHEEL,sha256=4n27za1eEkOnA7dNjN6C5-O2rUiw6iapszm14Uj-Qmk,79
-structlog_config-0.7.0.dist-info/METADATA,sha256=yjnflk2btwm0xBy-0xRjhe8lwXPmsdToMx2Kn2doylU,10994
-structlog_config-0.7.0.dist-info/RECORD,,