cuneus 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

cuneus/__init__.py

@@ -16,19 +16,21 @@ Example:
 """
 
 from .core.application import build_app
-from .core.execptions import (
+from .core.exceptions import (
     AppException,
     BadRequest,
-    Unauthorized,
+    Conflict,
+    DatabaseError,
+    ErrorResponse,
+    ExceptionExtension,
+    ExternalServiceError,
     Forbidden,
     NotFound,
-    Conflict,
     RateLimited,
-    ServiceUnavailable,
-    DatabaseError,
     RedisError,
-    ExternalServiceError,
-    ExceptionExtension,
+    ServiceUnavailable,
+    Unauthorized,
+    error_responses,
 )
 from .core.extensions import BaseExtension, Extension
 from .core.settings import Settings
@@ -46,14 +48,16 @@ __all__ = [
     # Exceptions
     "AppException",
     "BadRequest",
-    "Unauthorized",
+    "Conflict",
+    "DatabaseError",
+    "ErrorResponse",
+    "ExceptionExtension",
+    "ExternalServiceError",
     "Forbidden",
     "NotFound",
-    "Conflict",
     "RateLimited",
-    "ServiceUnavailable",
-    "DatabaseError",
     "RedisError",
-    "ExternalServiceError",
-    "ExceptionExtension",
+    "ServiceUnavailable",
+    "Unauthorized",
+    "error_responses",
 ]

cuneus/cli.py

@@ -44,7 +44,7 @@ def get_user_cli() -> click.Group | None:
 
 @click.group()
 @click.pass_context
-def cli(ctx: click.Context) -> None:
+def cli(ctx: click.Context) -> None:  # pragma: no cover
     """Cuneus CLI - FastAPI application framework."""
     ctx.ensure_object(dict)
 
@@ -63,6 +63,8 @@ def dev(host: str, port: int) -> None:
         host=host,
         port=port,
         reload=True,
+        log_config=None,
+        server_header=False,
     )
 
 
@@ -81,6 +83,8 @@ def prod(host: str, port: int, workers: int) -> None:
         host=host,
         port=port,
         workers=workers,
+        log_config=None,
+        server_header=False,
     )
 
 
@@ -91,7 +95,7 @@ def routes() -> None:
     app = import_from_string(config.app_module)
 
     for route in app.routes:
-        if hasattr(route, "methods"):
+        if hasattr(route, "methods"):  # pragma: no branch
             methods = ",".join(route.methods - {"HEAD", "OPTIONS"})
             click.echo(f"{methods:8} {route.path}")
 

cuneus/core/application.py

@@ -11,44 +11,43 @@ from contextlib import AsyncExitStack, asynccontextmanager
 from typing import Any, AsyncIterator, Callable
 
 import click
+import structlog
 import svcs
 from fastapi import FastAPI
 from starlette.middleware import Middleware
 
 from .settings import Settings
-from .execptions import ExceptionExtension
+from .exceptions import ExceptionExtension
 from .logging import LoggingExtension
-from .extensions import Extension, HasCLI, HasMiddleware
+from .extensions import Extension, HasCLI, HasExceptionHandler, HasMiddleware
 from ..ext.health import HealthExtension
 
+logger = structlog.stdlib.get_logger("cuneus")
 
 type ExtensionInput = Extension | Callable[..., Extension]
 
-DEFAULT_EXTENSIONS = (
+DEFAULTS = (
     LoggingExtension,
     HealthExtension,
     ExceptionExtension,
 )
 
 
+class ExtensionConflictError(Exception):
+    """Raised when extensions have conflicting state keys."""
+
+    pass
+
+
 def _instantiate_extension(
     ext: ExtensionInput, settings: Settings | None = None
 ) -> Extension:
     if isinstance(ext, type) or callable(ext):
-        sig = inspect.signature(ext)
-
-        # Check if it accepts a 'settings' parameter
-        if "settings" in sig.parameters:
-            return ext(settings=settings)
-
-        # Check if it accepts **kwargs
-        has_var_keyword = any(
-            p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
-        )
-        if has_var_keyword:
+        try:
             return ext(settings=settings)
+        except TypeError:
+            return ext()
 
-        return ext()
     return ext
 
 
@@ -90,13 +89,7 @@ def build_app(
 
     settings = settings or Settings()
 
-    if include_defaults:
-        # Allow users to override a default extension
-        user_types = {type(ext) for ext in extensions}
-        defaults = [ext for ext in DEFAULT_EXTENSIONS if type(ext) not in user_types]
-        all_inputs = (*defaults, *extensions)
-    else:
-        all_inputs = extensions
+    all_inputs = (*DEFAULTS, *extensions) if include_defaults else extensions
 
     all_extensions = [_instantiate_extension(ext, settings) for ext in all_inputs]
 
@@ -115,10 +108,13 @@ def build_app(
             state: dict[str, Any] = {}
 
             for ext in all_extensions:
+                ext_name = ext.__class__.__name__
                 ext_state = await stack.enter_async_context(ext.register(registry, app))
                 if ext_state:
                     if overlap := state.keys() & ext_state.keys():
-                        raise ValueError(f"Extension state key collision: {overlap}")
+                        msg = f"Extension {ext_name} state key collision: {overlap}"
+                        logger.error(msg, ext=ext_name, overlap=overlap)
+                        raise ExtensionConflictError(msg).with_traceback(None) from None
                     state.update(ext_state)
 
             yield state
@@ -127,10 +123,21 @@ def build_app(
     middleware: list[Middleware] = []
 
     for ext in all_extensions:
+        ext_name = ext.__class__.__name__
         if isinstance(ext, HasMiddleware):
+            logger.debug(f"Loading middleware from {ext_name}")
             middleware.extend(ext.middleware())
         if isinstance(ext, HasCLI):
+            logger.debug(f"Adding cli commands from {ext_name}")
             ext.register_cli(app_cli)
 
     app = FastAPI(lifespan=lifespan, middleware=middleware, **fastapi_kwargs)
+
+    # Preform post app initialization extension customization
+    for ext in all_extensions:
+        ext_name = ext.__class__.__name__
+        if isinstance(ext, HasExceptionHandler):
+            logger.debug(f"Loading exception handlers from {ext_name}")
+            ext.add_exception_handler(app)
+
     return app, app_cli

cuneus/core/{execptions.py → exceptions.py}

@@ -7,7 +7,6 @@ from __future__ import annotations
 from typing import Any
 
 import structlog
-import svcs
 from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel
@@ -152,24 +151,14 @@ class ExceptionExtension(BaseExtension):
 
     Catches AppException subclasses and converts to JSON responses.
     Catches unexpected exceptions and returns generic 500s.
-
-    Usage:
-        from qtip import build_app
-        from qtip.core.exceptions import ExceptionExtension, ExceptionSettings
-
-        app = build_app(
-            settings,
-            extensions=[ExceptionExtension(settings)],
-        )
     """
 
     def __init__(self, settings: Settings | None = None) -> None:
         self.settings = settings or Settings()
 
-    async def startup(self, registry: svcs.Registry, app: FastAPI) -> dict[str, Any]:
+    def add_exception_handler(self, app: FastAPI) -> None:
         app.add_exception_handler(AppException, self._handle_app_exception)  # type: ignore[arg-type]
         app.add_exception_handler(Exception, self._handle_unexpected_exception)
-        return {}
 
     def _handle_app_exception(
         self, request: Request, exc: AppException
@@ -179,7 +168,7 @@ class ExceptionExtension(BaseExtension):
         else:
             log.warning("client_error", error_code=exc.error_code, message=exc.message)
 
-        response = exc.to_response(request.state.get("request_id", None))
+        response = exc.to_response(getattr(request.state, "request_id", None))
 
         headers = {}
         if isinstance(exc, RateLimited) and exc.retry_after:
@@ -194,8 +183,7 @@ class ExceptionExtension(BaseExtension):
     def _handle_unexpected_exception(
         self, request: Request, exc: Exception
     ) -> JSONResponse:
-        log.exception("unexpected_error")
-
+        log.exception("unexpected_error", exc_info=exc)
         response: dict[str, Any] = {
             "error": {
                 "code": "internal_error",
@@ -203,7 +191,7 @@ class ExceptionExtension(BaseExtension):
             }
         }
 
-        if hasattr(request.state, "request_id"):
+        if hasattr(request.state, "request_id"):  # pragma: no branch
             response["error"]["request_id"] = request.state.request_id
 
         if self.settings.debug:

cuneus/core/extensions.py

@@ -35,7 +35,7 @@ class Extension(Protocol):
 
     def register(
         self, registry: svcs.Registry, app: FastAPI
-    ) -> AsyncContextManager[dict[str, Any]]:
+    ) -> AsyncContextManager[dict[str, Any]]:  # pragma: no cover
         """
         Async context manager for lifecycle.
 
@@ -50,14 +50,21 @@ class Extension(Protocol):
 class HasMiddleware(Protocol):
     """Extension that provides middleware."""
 
-    def middleware(self) -> list[Middleware]: ...
+    def middleware(self) -> list[Middleware]: ...  # pragma: no cover
 
 
 @runtime_checkable
 class HasCLI(Protocol):
     """Extension that provides CLI commands."""
 
-    def register_cli(self, cli_group: Group) -> None: ...
+    def register_cli(self, cli_group: Group) -> None: ...  # pragma: no cover
+
+
+@runtime_checkable
+class HasExceptionHandler(Protocol):
+    """Extension that provides exception handlers."""
+
+    def add_exception_handler(self, app: FastAPI) -> None: ...  # pragma: no cover
 
 
 class BaseExtension:

cuneus/core/logging.py

@@ -4,22 +4,73 @@ Structured logging with structlog and request context.
 
 from __future__ import annotations
 
-from contextvars import ContextVar
 import logging
 import time
 import uuid
-from typing import Any, Awaitable, Callable, MutableMapping
+from typing import Any, Awaitable, Callable
 
 import structlog
 import svcs
 from fastapi import FastAPI, Request, Response
 from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.middleware import Middleware
-from starlette.types import ASGIApp, Scope, Send, Receive
+from starlette.types import ASGIApp
 
 from .extensions import BaseExtension
 from .settings import Settings
 
+logger = structlog.stdlib.get_logger("cuneus")
+
+
+def configure_structlog(settings: Settings | None = None) -> None:
+    log_settings = settings or 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", utc=True),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.UnicodeDecoder(),
+    ]
+
+    renderer: structlog.types.Processor = structlog.dev.ConsoleRenderer(colors=True)
+    if log_settings.log_json:  # pragma: no cover
+        renderer = structlog.processors.JSONRenderer()
+
+    # 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(log_settings.log_level.upper())
+
+    # Quiet noisy loggers
+    logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+
 
 class LoggingExtension(BaseExtension):
     """
@@ -27,69 +78,11 @@ class LoggingExtension(BaseExtension):
 
     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 = None) -> None:
         self.settings = settings or 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(),
-        ]
-
-        renderer: structlog.types.Processor = structlog.dev.ConsoleRenderer(colors=True)
-        if settings.log_json:
-            renderer = structlog.processors.JSONRenderer()
-
-        # 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)
+        configure_structlog(settings)
 
     async def startup(self, registry: svcs.Registry, app: FastAPI) -> dict[str, Any]:
         # app.add_middleware(RequestLoggingMiddleware)
@@ -120,18 +113,24 @@ class LoggingMiddleware(BaseHTTPMiddleware):
     async def dispatch(
         self, request: Request, call_next: Callable[..., Awaitable[Response]]
     ) -> Response:
+        path = request.url.path
+        # Exclude health routes as these are just noise
+        # TODO(rmyers): make this configurable
+        if path.startswith("/health"):
+            return await call_next(request)
+
         request_id = request.headers.get(self.header_name) or str(uuid.uuid4())[:8]
 
         structlog.contextvars.clear_contextvars()
         structlog.contextvars.bind_contextvars(
             request_id=request_id,
             method=request.method,
-            path=request.url.path,
+            path=path,
         )
 
         request.state.request_id = request_id
 
-        log = structlog.get_logger()
+        log = structlog.stdlib.get_logger("cuneus")
         start_time = time.perf_counter()
 
         try:
@@ -151,71 +150,3 @@ class LoggingMiddleware(BaseHTTPMiddleware):
             raise
         finally:
             structlog.contextvars.clear_contextvars()
-
-
-# Used by httpx for request ID propagation
-request_id_ctx: ContextVar[str | None] = ContextVar("request_id", default=None)
-
-
-class RequestIDMiddleware:
-    def __init__(self, app: ASGIApp, header_name: str = "X-Request-ID") -> None:
-        self.app = app
-        self.header_name = header_name
-
-    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
-        if scope["type"] != "http":
-            await self.app(scope, receive, send)
-            return
-
-        headers = dict(scope.get("headers", []))
-        request_id = headers.get(
-            self.header_name.lower().encode(), str(uuid.uuid4())[:8].encode()
-        ).decode()
-
-        if "state" not in scope:
-            scope["state"] = {}
-        scope["state"]["request_id"] = request_id
-
-        # Set contextvar for use in HTTP clients
-        token = request_id_ctx.set(request_id)
-
-        async def send_with_request_id(message: MutableMapping[str, Any]) -> None:
-            if message["type"] == "http.response.start":
-                headers = list(message.get("headers", []))
-                headers.append((self.header_name.encode(), request_id.encode()))
-                message["headers"] = headers
-            await send(message)
-
-        try:
-            await self.app(scope, receive, send_with_request_id)
-        finally:
-            request_id_ctx.reset(token)
-
-
-# === 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.stdlib.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.5.dist-info → cuneus-0.2.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cuneus
-Version: 0.2.5
+Version: 0.2.7
 Summary: ASGI application wrapper
 Project-URL: Homepage, https://github.com/rmyers/cuneus
 Project-URL: Documentation, https://github.com/rmyers/cuneus#readme
@@ -31,6 +31,7 @@ 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-mock; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: redis>=5.0; extra == 'dev'
 Requires-Dist: ruff>=0.3; extra == 'dev'

cuneus-0.2.7.dist-info/RECORD

@@ -0,0 +1,15 @@
+cuneus/__init__.py,sha256=AJXN9dnXIWn0Eg6JxWOgOf0C386EqBNdHiQG2akTpKc,1295
+cuneus/cli.py,sha256=rcJDqU28FMPSw7tkmKUz95ERKzgYv43Y2kKVZw24rLo,3864
+cuneus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/core/application.py,sha256=Xoqs3fREJ-KPzSilq4ua65JzKv6w5LgugGaMklDELdU,4376
+cuneus/core/exceptions.py,sha256=gyHgVy4UC7gBjs5pXpCzIIyIVsV7K8xt-KZKi8eLJtM,5496
+cuneus/core/extensions.py,sha256=wqN2rbaqhiTkfK_fA5AkFlefOAV2GJr6zTLf9Oi-n4c,2771
+cuneus/core/logging.py,sha256=YXF_-QzcNqfzIl6H4niiW3yR5IBzh2VJxUosfBvb0SM,4583
+cuneus/core/settings.py,sha256=PaYXQ_ubeSt3AFpxNNErii-h1_ehHYPrajFWRT42mTI,1703
+cuneus/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/ext/health.py,sha256=5dWVVEPFL1tWFBhQwZv8C-IvZRzg28V-4sk_g1jJ0vc,3854
+cuneus-0.2.7.dist-info/METADATA,sha256=6xs5SVnhEMudG9taaPSruvbee6aPiaOixc9XndBD9lc,6837
+cuneus-0.2.7.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cuneus-0.2.7.dist-info/entry_points.txt,sha256=tzPgom-_UkpP_uLKv3V_XyoIsKg84FBAc9ddjYl0W0Y,43
+cuneus-0.2.7.dist-info/RECORD,,

cuneus-0.2.5.dist-info/RECORD

@@ -1,15 +0,0 @@
-cuneus/__init__.py,sha256=JJ3nZ4757GU9KKuurxP1FfJSdSVrcO-xaorLFSvUJ5E,1211
-cuneus/cli.py,sha256=NHk_hI_KtXPQ0EXCCfottDwOFrSG6vcYSZPrzuzyZk8,3715
-cuneus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cuneus/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cuneus/core/application.py,sha256=6yKbrkkSaWlt3UHiKo68Dc9B1EAcNXd6BxO5W8ZTZuc,4058
-cuneus/core/execptions.py,sha256=beQE3gD-14BUK4Se6yE2J2U92xgr0yarVmVeibkudxs,5753
-cuneus/core/extensions.py,sha256=qqBnAD_wN6wTTun7C2hfVqxHhA3WgScNSrgRTMsYa04,2515
-cuneus/core/logging.py,sha256=OlcWxBCLDqBORzTXZXKlMc_rGD8OkfOBfHgSwEpMCM4,6778
-cuneus/core/settings.py,sha256=PaYXQ_ubeSt3AFpxNNErii-h1_ehHYPrajFWRT42mTI,1703
-cuneus/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cuneus/ext/health.py,sha256=5dWVVEPFL1tWFBhQwZv8C-IvZRzg28V-4sk_g1jJ0vc,3854
-cuneus-0.2.5.dist-info/METADATA,sha256=hIVlKfIT3uwqzSeoX8nXeEN6oCnfKcb5HaT-y3YETBQ,6794
-cuneus-0.2.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-cuneus-0.2.5.dist-info/entry_points.txt,sha256=tzPgom-_UkpP_uLKv3V_XyoIsKg84FBAc9ddjYl0W0Y,43
-cuneus-0.2.5.dist-info/RECORD,,