cuneus 0.2.1__py3-none-any.whl

cuneus/middleware/logging.py

@@ -0,0 +1,165 @@
+"""
+Structured logging with structlog and request context.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from typing import Any, AsyncIterator
+
+import structlog
+import svcs
+from fastapi import FastAPI, Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from cuneus.core.application import BaseExtension, Settings
+
+
+class LoggingExtension(BaseExtension):
+    """
+    Structured logging extension using structlog.
+
+    Integrates with stdlib logging so uvicorn and other libraries
+    also output through structlog.
+
+    Usage:
+        from qtip import build_app
+        from qtip.middleware.logging import LoggingExtension, LoggingSettings
+
+        app = build_app(
+            settings,
+            extensions=[LoggingExtension(settings)],
+        )
+    """
+
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+        self._configure_structlog()
+
+    def _configure_structlog(self) -> None:
+        settings = self.settings
+
+        # Shared processors
+        shared_processors: list[structlog.types.Processor] = [
+            structlog.contextvars.merge_contextvars,
+            structlog.stdlib.add_log_level,
+            structlog.stdlib.add_logger_name,
+            structlog.stdlib.PositionalArgumentsFormatter(),
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.UnicodeDecoder(),
+        ]
+
+        if settings.log_json:
+            renderer = structlog.processors.JSONRenderer()
+        else:
+            renderer = structlog.dev.ConsoleRenderer(colors=True)
+
+        # Configure structlog
+        structlog.configure(
+            processors=shared_processors
+            + [
+                structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+            ],
+            logger_factory=structlog.stdlib.LoggerFactory(),
+            cache_logger_on_first_use=True,
+        )
+
+        # Create formatter for stdlib
+        formatter = structlog.stdlib.ProcessorFormatter(
+            foreign_pre_chain=shared_processors,
+            processors=[
+                structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+                renderer,
+            ],
+        )
+
+        # Configure root logger
+        handler = logging.StreamHandler()
+        handler.setFormatter(formatter)
+
+        root_logger = logging.getLogger()
+        root_logger.handlers.clear()
+        root_logger.addHandler(handler)
+        root_logger.setLevel(settings.log_level.upper())
+
+        # Quiet noisy loggers
+        logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+
+    async def startup(self, registry: svcs.Registry, app: FastAPI) -> dict[str, Any]:
+        # app.add_middleware(RequestLoggingMiddleware)
+        return {}
+
+
+class LoggingMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware that:
+    - Generates request_id
+    - Binds it to structlog context
+    - Logs request start/end
+    - Adds request_id to response headers
+    """
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        request_id = request.headers.get("X-Request-ID") or str(uuid.uuid4())[:8]
+
+        structlog.contextvars.clear_contextvars()
+        structlog.contextvars.bind_contextvars(
+            request_id=request_id,
+            method=request.method,
+            path=request.url.path,
+        )
+
+        request.state.request_id = request_id
+
+        log = structlog.get_logger()
+        start_time = time.perf_counter()
+
+        try:
+            response = await call_next(request)
+
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            log.info(
+                f"{request.method} {request.url.path} {response.status_code}",
+                status_code=response.status_code,
+                duration_ms=round(duration_ms, 2),
+            )
+
+            response.headers["X-Request-ID"] = request_id
+            return response
+
+        except Exception:
+            raise
+        finally:
+            structlog.contextvars.clear_contextvars()
+
+
+# === Public API ===
+
+
+def get_logger(**initial_context: Any) -> structlog.stdlib.BoundLogger:
+    """
+    Get a logger with optional initial context.
+
+    Usage:
+        log = get_logger()
+        log.info("user logged in", user_id=123)
+    """
+    log = structlog.get_logger()
+    if initial_context:
+        log = log.bind(**initial_context)
+    return log
+
+
+def bind_contextvars(**context: Any) -> None:
+    """
+    Bind additional context that will appear in all subsequent logs.
+    """
+    structlog.contextvars.bind_contextvars(**context)
+
+
+def get_request_id(request: Request) -> str:
+    """Get request ID from request state."""
+    return getattr(request.state, "request_id", "-")

cuneus-0.2.1.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: cuneus
+Version: 0.2.1
+Summary: ASGI application wrapper
+Project-URL: Homepage, https://github.com/rmyers/cuneus
+Project-URL: Documentation, https://github.com/rmyers/cuneus#readme
+Project-URL: Repository, https://github.com/rmyers/cuneus
+Author-email: Robert Myers <robert@julython.org>
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: structlog>=24.1.0
+Requires-Dist: svcs>=24.1.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Provides-Extra: all
+Requires-Dist: alembic>=1.13.0; extra == 'all'
+Requires-Dist: asyncpg>=0.29.0; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'all'
+Provides-Extra: database
+Requires-Dist: alembic>=1.13.0; extra == 'database'
+Requires-Dist: asyncpg>=0.29.0; extra == 'database'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'database'
+Provides-Extra: dev
+Requires-Dist: alembic>=1.13.0; extra == 'dev'
+Requires-Dist: asgi-lifespan>=2.1.0; extra == 'dev'
+Requires-Dist: asyncpg>=0.29.0; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: redis>=5.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# cuneus
+
+> _The wedge stone that locks the arch together_
+
+**cuneus** is a lightweight lifespan manager for FastAPI applications. It provides a simple pattern for composing extensions that handle startup/shutdown and service registration.
+
+The name comes from Roman architecture: a _cuneus_ is the wedge-shaped stone in a Roman arch. Each stone is simple on its own, but together they lock under pressure to create structures that have stood for millennia—no rebar required.
+
+## Installation
+
+```bash
+uv add cuneus
+```
+
+or
+
+```bash
+pip install cuneus
+```
+
+## Quick Start
+
+```python
+# app.py
+from fastapi import FastAPI
+from cuneus import build_lifespan, Settings
+from cuneus.middleware.logging import LoggingMiddleware
+
+from myapp.extensions import DatabaseExtension
+
+settings = Settings()
+lifespan = build_lifespan(
+    settings,
+    DatabaseExtension(settings),
+)
+
+app = FastAPI(lifespan=lifespan, title="My App", version="1.0.0")
+
+# Add middleware directly to FastAPI
+app.add_middleware(LoggingMiddleware)
+```
+
+That's it. Extensions handle their lifecycle, FastAPI handles the rest.
+
+## Creating Extensions
+
+Use `BaseExtension` for simple cases:
+
+```python
+from cuneus import BaseExtension
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncEngine
+import svcs
+
+class DatabaseExtension(BaseExtension):
+    def __init__(self, settings):
+        self.settings = settings
+        self.engine: AsyncEngine | None = None
+
+    async def startup(self, registry: svcs.Registry, app: FastAPI) -> dict[str, Any]:
+        self.engine = create_async_engine(self.settings.database_url)
+
+        # Register with svcs for dependency injection
+        registry.register_value(AsyncEngine, self.engine)
+
+        # Add routes
+        app.include_router(health_router, prefix="/health")
+
+        # Add exception handlers
+        app.add_exception_handler(DBError, self.handle_db_error)
+
+        # Return state (accessible via request.state.db)
+        return {"db": self.engine}
+
+    async def shutdown(self, app: FastAPI) -> None:
+        if self.engine:
+            await self.engine.dispose()
+```
+
+For full control, override `register()` directly:
+
+```python
+from contextlib import asynccontextmanager
+
+class RedisExtension(BaseExtension):
+    def __init__(self, settings):
+        self.settings = settings
+
+    @asynccontextmanager
+    async def register(self, registry: svcs.Registry, app: FastAPI):
+        redis = await aioredis.from_url(self.settings.redis_url)
+        registry.register_value(Redis, redis)
+
+        try:
+            yield {"redis": redis}
+        finally:
+            await redis.close()
+```
+
+## Testing
+
+The lifespan exposes a `.registry` attribute for test overrides:
+
+```python
+# test_app.py
+from unittest.mock import Mock
+from starlette.testclient import TestClient
+from myapp import app, lifespan, Database
+
+def test_db_error_handling():
+    with TestClient(app) as client:
+        # Override after app startup
+        mock_db = Mock(spec=Database)
+        mock_db.get_user.side_effect = Exception("boom")
+        lifespan.registry.register_value(Database, mock_db)
+
+        resp = client.get("/users/42")
+        assert resp.status_code == 500
+```
+
+## Settings
+
+cuneus includes a base `Settings` class that loads from multiple sources:
+
+```python
+from cuneus import Settings
+
+class AppSettings(Settings):
+    database_url: str = "sqlite+aiosqlite:///./app.db"
+    redis_url: str = "redis://localhost"
+
+    model_config = SettingsConfigDict(env_prefix="APP_")
+```
+
+Load priority (highest wins):
+
+1. Environment variables
+2. `.env` file
+3. `pyproject.toml` under `[tool.cuneus]`
+
+## API Reference
+
+### `build_lifespan(settings, *extensions)`
+
+Creates a lifespan context manager for FastAPI.
+
+- `settings`: Your settings instance (subclass of `Settings`)
+- `*extensions`: Extension instances to register
+
+Returns a lifespan with a `.registry` attribute for testing.
+
+### `BaseExtension`
+
+Base class with `startup()` and `shutdown()` hooks:
+
+- `startup(registry, app) -> dict[str, Any]`: Setup resources, return state
+- `shutdown(app) -> None`: Cleanup resources
+
+### `Extension` Protocol
+
+For full control, implement the protocol directly:
+
+```python
+def register(self, registry: svcs.Registry, app: FastAPI) -> AsyncContextManager[dict[str, Any]]
+```
+
+### Accessors
+
+- `aget(request, *types)` - Async get services from svcs
+- `get(request, *types)` - Sync get services from svcs
+- `get_settings(request)` - Get settings from request state
+- `get_request_id(request)` - Get request ID from request state
+
+## Why cuneus?
+
+- **Simple** — one function, `build_lifespan()`, does what you need
+- **No magic** — middleware added directly to FastAPI, not hidden
+- **Testable** — registry exposed via `lifespan.registry`
+- **Composable** — extensions are just async context managers
+- **Built on svcs** — proper dependency injection, not global state
+
+## License
+
+MIT

cuneus-0.2.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+cuneus/__init__.py,sha256=KB5M0Ll8iffKml3-DmI2_LdafkU8Jhw3BBJkH8MrbpI,1226
+cuneus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/cli/__init__.py,sha256=XlLdZYfjfQxkIi4QTe8NcinmkidX__kd4ryO-Fjwxig,10854
+cuneus/cli/console.py,sha256=e8ElKzkhL4FQQeVE-pjZx-kLgbzAKQrZJJpss3F4vr4,5620
+cuneus/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/core/application.py,sha256=QSOSmo8-YwjbC6QVe_VkDRa0AdRStTZX9bSqcbf3MFw,6670
+cuneus/core/execptions.py,sha256=fM7-KbxYxzixehYd5pSDgWDYBW6IsawdJ6NwCxeIJPM,5695
+cuneus/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/ext/health.py,sha256=YYKKfJ8X71hnqN8vCKydqUK7BmlvZrqeBs7L61r7zp8,3814
+cuneus/middleware/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/middleware/logging.py,sha256=6KYakjrjzjfgdQ80xSsRtT3pX7NFAGkLUwceiEhDLfI,4780
+cuneus-0.2.1.dist-info/METADATA,sha256=c_ZSnSwnY8zjS-p9GQUTFQCYVPzsrboGizwRvISTAwE,6501
+cuneus-0.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cuneus-0.2.1.dist-info/entry_points.txt,sha256=tzPgom-_UkpP_uLKv3V_XyoIsKg84FBAc9ddjYl0W0Y,43
+cuneus-0.2.1.dist-info/RECORD,,

cuneus-0.2.1.dist-info/WHEEL

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

cuneus-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cuneus = cuneus.cli:main