cuneus 0.2.5__tar.gz → 0.2.7__tar.gz

{cuneus-0.2.5 → cuneus-0.2.7}/.gitignore

@@ -5,7 +5,12 @@ build/
 dist/
 wheels/
 *.egg-info
+.*_cache
+
+# coverage
 .coverage
+htmlcov
+
 
 # Virtual environments
 .venv

cuneus-0.2.7/Makefile

@@ -0,0 +1,68 @@
+BASE_DIR		:= $(shell git rev-parse --show-toplevel 2>/dev/null || pwd)
+PROG_NAME		:= $(shell basename $(BASE_DIR))
+PYPROJECT		:= $(shell find . -name 'pyproject.toml')
+SHELL			:= /bin/bash
+UV_LOCK			:= uv.lock
+UV				?= uv
+VENV			:= .venv
+MARKER			:= $(VENV)/.installed
+
+################################################################
+#%
+#% Usage:
+#%   make <command>
+#%
+#% Getting Started:
+#%   make setup
+#%
+#% Run the tests locally:
+#%   make test
+#%
+#% Available Commands:
+help: ## Help is on the way
+	@echo " Tools for building, running, and testing $(PROG_NAME)"
+	@grep '^#%' $(MAKEFILE_LIST) | sed -e 's/#%//'
+	@grep '^[a-zA-Z]' $(MAKEFILE_LIST) | awk -F ':.*?## ' 'NF==2 {printf "   %-20s%s\n", $$1, $$2}' | sort
+
+# export env vars in order to be used in commands
+export PYTHONPATH ?= ./src
+
+# uv creates the venv automatically, but this tracks if sync has been run
+$(MARKER): $(PYPROJECT) $(UV_LOCK)
+	$(UV) sync --all-extras
+	touch $(MARKER)
+
+.PHONY: install
+setup: $(MARKER) ## Install dependencies for the project
+
+.PHONY: update
+update: ## Update and lock dependencies
+	$(UV) lock
+	$(UV) sync
+	touch $(MARKER)
+
+.PHONY: clean
+clean: ## Remove virtual environment
+	rm -rf $(VENV)
+
+.PHONY: deps
+deps: $(MARKER) ## Run any dependencies for local dev and test
+	@echo "Starting deps..."
+
+.PHONY: dev
+dev: deps ## Run the application in dev mode
+	$(UV) run cuneus dev
+
+.PHONY: prod
+prod: deps ## Run the application in prod mode
+	$(UV) run cuneus prod
+
+.PHONY: test
+test: deps ## Run pytests
+	$(UV) run pytest
+
+.PHONY: test-failed
+test-failed: deps ## Re-Run pytest on tests that failed
+	$(UV) run pytest --lf
+
+

{cuneus-0.2.5 → cuneus-0.2.7}/PKG-INFO

@@ -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.5 → cuneus-0.2.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cuneus"
-version = "0.2.5"
+version = "0.2.7"
 description = "ASGI application wrapper"
 readme = "README.md"
 authors = [{ name = "Robert Myers", email = "robert@julython.org" }]
@@ -26,6 +26,7 @@ dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
     "pytest-cov>=4.0",
+    "pytest-mock",
     "httpx>=0.27",
     "asgi-lifespan>=2.1.0",
     "ruff>=0.3",
@@ -63,7 +64,28 @@ warn_unused_ignores = true
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
+addopts = [
+    # "--test-alembic",
+    "--log-cli-level=warning",
+    "--cov=cuneus",
+    "--cov-branch",
+    "--cov-report=term-missing:skip-covered",
+    "--cov-report=html",
+    "--strict-markers",
+    "--strict-config",
+    "--verbose",
+]
 
 [tool.coverage.run]
 source = ["src/cuneus"]
 branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]

{cuneus-0.2.5 → cuneus-0.2.7}/src/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-0.2.5 → cuneus-0.2.7}/src/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-0.2.5 → cuneus-0.2.7}/src/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-0.2.5/src/cuneus/core/execptions.py → cuneus-0.2.7/src/cuneus/core/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-0.2.5 → cuneus-0.2.7}/src/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-0.2.7/src/cuneus/core/logging.py

@@ -0,0 +1,152 @@
+"""
+Structured logging with structlog and request context.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+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
+
+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):
+    """
+    Structured logging extension using structlog.
+
+    Integrates with stdlib logging so uvicorn and other libraries
+    also output through structlog.
+    """
+
+    def __init__(self, settings: Settings | None = None) -> None:
+        self.settings = settings or Settings()
+        configure_structlog(settings)
+
+    async def startup(self, registry: svcs.Registry, app: FastAPI) -> dict[str, Any]:
+        # app.add_middleware(RequestLoggingMiddleware)
+        return {}
+
+    def middleware(self) -> list[Middleware]:
+        return [
+            Middleware(
+                LoggingMiddleware,
+                header_name=self.settings.request_id_header,
+            ),
+        ]
+
+
+class LoggingMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware that:
+    - Generates request_id
+    - Binds it to structlog context
+    - Logs request start/end
+    - Adds request_id to response headers
+    """
+
+    def __init__(self, app: ASGIApp, header_name: str = "X-Request-ID") -> None:
+        self.header_name = header_name
+        super().__init__(app)
+
+    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=path,
+        )
+
+        request.state.request_id = request_id
+
+        log = structlog.stdlib.get_logger("cuneus")
+        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[self.header_name] = request_id
+            return response
+
+        except Exception:
+            raise
+        finally:
+            structlog.contextvars.clear_contextvars()