structlog-config 0.2.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

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/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/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/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.dist-info → structlog_config-0.4.1.dist-info}/METADATA

@@ -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.4.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+structlog_config/__init__.py,sha256=sSO1F6S__4-3FZU1JursNYzudWZd3uT3KndddF-cUck,6816
+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=hHkueC2m-19su5lIEfeJbzMprJ1HeC_WoOKPpaQmHPo,5143
+structlog_config/formatters.py,sha256=ll0Y0QeRs1DMmD-ft1n1zA4Vn2STRSK-mOrczYB2OjE,5898
+structlog_config/levels.py,sha256=z1fTpvCCbAwcFK2k7rHWh_p-FqfFh4yIWCTZ1MNf_4U,993
+structlog_config/packages.py,sha256=asxrzLR-iRYAbkoSYutyTdIRcruTjHgkzfe2pjm2VFM,519
+structlog_config/stdlib_logging.py,sha256=Wnn59oRBIqn708CpR-akqVcG9ccSfCMLh56_7wxZRH0,7350
+structlog_config/trace.py,sha256=dBaSynxmw4Wg79wSHqYEMoByvv--v_oQw61dRdg4xUI,2016
+structlog_config/warnings.py,sha256=gKEcuHWqH0BaKitJtQkv-uJ0Z3uCH5nn6k8qpqjR-RM,998
+structlog_config-0.4.1.dist-info/WHEEL,sha256=4n27za1eEkOnA7dNjN6C5-O2rUiw6iapszm14Uj-Qmk,79
+structlog_config-0.4.1.dist-info/METADATA,sha256=9ZEpVM56Y6ZOXhqwc7YmFIYbB-wVSNfTHwY2mM5wRx8,6329
+structlog_config-0.4.1.dist-info/RECORD,,

structlog_config-0.4.1.dist-info/WHEEL

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

structlog_config-0.2.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-structlog_config/__init__.py,sha256=DyY4x3_dY_hPNbS1aM7JRCGadTa1dYDIPzgrHu3AP68,6733
-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=31tSlpe50joO5uBPAQzUWGfv_Vs_Z-9dMhuq3hwa9iY,3592
-structlog_config/formatters.py,sha256=cprGEjvRFphJixbb0nVCpPn9sfw_Wv4d2vPtKDpM05A,5846
-structlog_config/levels.py,sha256=z1fTpvCCbAwcFK2k7rHWh_p-FqfFh4yIWCTZ1MNf_4U,993
-structlog_config/packages.py,sha256=asxrzLR-iRYAbkoSYutyTdIRcruTjHgkzfe2pjm2VFM,519
-structlog_config/stdlib_logging.py,sha256=oUbd-3joR89hOXTbZxgrsSOyhBMjEyW6h68qQpCXabU,7120
-structlog_config/trace.py,sha256=dBaSynxmw4Wg79wSHqYEMoByvv--v_oQw61dRdg4xUI,2016
-structlog_config/warnings.py,sha256=gKEcuHWqH0BaKitJtQkv-uJ0Z3uCH5nn6k8qpqjR-RM,998
-structlog_config-0.2.0.dist-info/METADATA,sha256=Rq5mcJeFR_0SgIinFLTfSeIXZsGphXDJsvJkJNC-ltY,4606
-structlog_config-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-structlog_config-0.2.0.dist-info/RECORD,,

structlog_config-0.2.0.dist-info/WHEEL

@@ -1,4 +0,0 @@
-Wheel-Version: 1.0
-Generator: hatchling 1.27.0
-Root-Is-Purelib: true
-Tag: py3-none-any