cuneus 0.2.9__py3-none-any.whl

cuneus/__init__.py

@@ -0,0 +1,63 @@
+"""
+qtip - A wrapper for FastAPI applications, like the artist.
+
+Example:
+    from qtip import Application, Settings
+    from qtip.ext.database import DatabaseExtension
+
+    class AppSettings(Settings):
+        database_url: str
+
+    settings = AppSettings()
+    app = Application(settings)
+    app.add_extension(DatabaseExtension(settings))
+
+    fastapi_app = app.build()
+"""
+
+from .core.application import build_app
+from .core.exceptions import (
+    AppException,
+    BadRequest,
+    Conflict,
+    DatabaseError,
+    ErrorResponse,
+    ExceptionExtension,
+    ExternalServiceError,
+    Forbidden,
+    NotFound,
+    RateLimited,
+    RedisError,
+    ServiceUnavailable,
+    Unauthorized,
+    error_responses,
+)
+from .core.extensions import BaseExtension, Extension
+from .core.settings import Settings
+
+__version__ = "0.2.1"
+__all__ = [
+    # Core exported functions
+    # Application
+    "build_app",
+    # Extension
+    "BaseExtension",
+    "Extension",
+    # Settings
+    "Settings",
+    # Exceptions
+    "AppException",
+    "BadRequest",
+    "Conflict",
+    "DatabaseError",
+    "ErrorResponse",
+    "ExceptionExtension",
+    "ExternalServiceError",
+    "Forbidden",
+    "NotFound",
+    "RateLimited",
+    "RedisError",
+    "ServiceUnavailable",
+    "Unauthorized",
+    "error_responses",
+]

cuneus/cli.py

@@ -0,0 +1,53 @@
+"""Cuneus CLI entry point."""
+
+from typing import Any, cast
+
+import click
+
+from .core.settings import Settings, ensure_project_in_path
+from .utils import import_from_string
+
+
+def get_user_cli(config: Settings = Settings()) -> click.Group | None:
+    """Load CLI from config."""
+    try:
+        return cast(click.Group, import_from_string(config.cli_module))
+    except (ImportError, AttributeError) as e:
+        click.echo(
+            f"Warning: Could not load CLI from {config.cli_module}: {e}", err=True
+        )
+        return None
+
+
+class CuneusCLI(click.Group):
+    """Delegates to the app's CLI from config."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._user_cli: click.Group | None = None
+        self._user_cli_loaded = False
+
+    @property
+    def user_cli(self) -> click.Group | None:
+        if not self._user_cli_loaded:
+            self._user_cli = get_user_cli()
+            self._user_cli_loaded = True
+        return self._user_cli
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        if self.user_cli:
+            return self.user_cli.list_commands(ctx)
+        return []
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        if self.user_cli:
+            return self.user_cli.get_command(ctx, cmd_name)
+        return None
+
+
+ensure_project_in_path()
+main = CuneusCLI(help="Cuneus CLI - FastAPI application framework")
+
+
+if __name__ == "__main__":
+    main()

cuneus/core/application.py

@@ -0,0 +1,143 @@
+"""
+cuneus - The wedge stone that locks the arch together.
+
+Lightweight lifespan management for FastAPI applications.
+"""
+
+from __future__ import annotations
+
+import inspect
+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 .exceptions import ExceptionExtension
+from .logging import LoggingExtension
+from .extensions import Extension, HasCLI, HasExceptionHandler, HasMiddleware, HasRoutes
+from ..ext.health import HealthExtension
+from ..ext.server import ServerExtension
+
+logger = structlog.stdlib.get_logger("cuneus")
+
+type ExtensionInput = Extension | Callable[..., Extension]
+
+DEFAULTS = (
+    LoggingExtension,
+    HealthExtension,
+    ExceptionExtension,
+    ServerExtension,
+)
+
+
+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):
+        try:
+            return ext(settings=settings)
+        except TypeError:
+            return ext()
+
+    return ext
+
+
+def build_app(
+    *extensions: ExtensionInput,
+    settings: Settings | None = None,
+    include_defaults: bool = True,
+    **fastapi_kwargs: Any,
+) -> tuple[FastAPI, click.Group, svcs.fastapi.lifespan]:
+    """
+    Build a FastAPI with extensions preconfigured.
+
+    The returned lifespan has a `.registry` attribute for testing overrides.
+
+    Usage:
+        from cuneus import build_app, Settings, SettingsExtension
+        from myapp.extensions import DatabaseExtension
+
+        settings = Settings()
+        app, cli = build_app(
+            SettingsExtension(settings),
+            DatabaseExtension(settings),
+            title="Args are passed to FastAPI",
+        )
+
+        __all__ = ["app", "cli"]
+
+    Testing:
+        from myapp import app, lifespan
+
+        def test_with_mock_db(client):
+            mock_db = Mock(spec=Database)
+            lifespan.registry.register_value(Database, mock_db)
+    """
+    if "lifespan" in fastapi_kwargs:
+        raise AttributeError("cannot set lifespan with build_app")
+    if "middleware" in fastapi_kwargs:
+        raise AttributeError("cannot set middleware with build_app")
+
+    settings = settings or Settings()
+
+    all_inputs = (*DEFAULTS, *extensions) if include_defaults else extensions
+
+    all_extensions = [_instantiate_extension(ext, settings) for ext in all_inputs]
+
+    @svcs.fastapi.lifespan
+    @asynccontextmanager
+    async def lifespan(
+        app: FastAPI, registry: svcs.Registry
+    ) -> AsyncIterator[dict[str, Any]]:
+        async with AsyncExitStack() as stack:
+            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():
+                        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
+
+    # Parse extensions for middleware and cli commands
+    middleware: list[Middleware] = []
+    app_cli = click.Group()
+
+    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)
+        if isinstance(ext, HasRoutes):
+            logger.debug(f"Loading routes from {ext_name}")
+            ext.add_routes(app)
+
+    return app, app_cli, lifespan

cuneus/core/exceptions.py

@@ -0,0 +1,203 @@
+"""
+Exception handling with consistent API responses.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import structlog
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from .extensions import BaseExtension
+from .settings import Settings
+
+log = structlog.get_logger()
+
+
+class ErrorDetails(BaseModel):
+    status: int
+    code: str
+    message: str
+    request_id: str | None = None
+    details: Any = None
+
+
+class ErrorResponse(BaseModel):
+    error: ErrorDetails
+
+
+class AppException(Exception):
+    """
+    Base exception for application errors.
+
+    Subclass this for domain-specific errors.
+    """
+
+    status_code: int = 500
+    error_code: str = "internal_error"
+    message: str = "An unexpected error occurred"
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        error_code: str | None = None,
+        status_code: int | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        self.message = message or self.message
+        self.error_code = error_code or self.error_code
+        self.status_code = status_code or self.status_code
+        self.details = details or {}
+        super().__init__(self.message)
+
+    def to_response(self, request_id: str | None = None) -> ErrorResponse:
+        error_detail = ErrorDetails(
+            status=self.status_code,
+            code=self.error_code,
+            message=self.message,
+            request_id=request_id,
+            details=self.details,
+        )
+        return ErrorResponse(error=error_detail)
+
+
+# === Common HTTP Exceptions ===
+
+
+class BadRequest(AppException):
+    status_code = 400
+    error_code = "bad_request"
+    message = "Invalid request"
+
+
+class Unauthorized(AppException):
+    status_code = 401
+    error_code = "unauthorized"
+    message = "Authentication required"
+
+
+class Forbidden(AppException):
+    status_code = 403
+    error_code = "forbidden"
+    message = "Access denied"
+
+
+class NotFound(AppException):
+    status_code = 404
+    error_code = "not_found"
+    message = "Resource not found"
+
+
+class Conflict(AppException):
+    status_code = 409
+    error_code = "conflict"
+    message = "Resource conflict"
+
+
+class RateLimited(AppException):
+    status_code = 429
+    error_code = "rate_limited"
+    message = "Too many requests"
+
+    def __init__(self, retry_after: int | None = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.retry_after = retry_after
+
+
+class ServiceUnavailable(AppException):
+    status_code = 503
+    error_code = "service_unavailable"
+    message = "Service temporarily unavailable"
+
+
+# === Infrastructure Exceptions ===
+
+
+class DatabaseError(AppException):
+    status_code = 503
+    error_code = "database_error"
+    message = "Database operation failed"
+
+
+class RedisError(AppException):
+    status_code = 503
+    error_code = "cache_error"
+    message = "Cache operation failed"
+
+
+class ExternalServiceError(AppException):
+    status_code = 502
+    error_code = "external_service_error"
+    message = "External service request failed"
+
+
+def error_responses(*excptions: AppException) -> dict[int, dict[str, Any]]:
+    responses: dict[int, dict[str, Any]] = {}
+    for exception in excptions:
+        responses[exception.status_code] = {
+            "model": ErrorResponse,
+            "description": exception.message,
+        }
+    return responses
+
+
+class ExceptionExtension(BaseExtension):
+    """
+    Exception handling extension.
+
+    Catches AppException subclasses and converts to JSON responses.
+    Catches unexpected exceptions and returns generic 500s.
+    """
+
+    def __init__(self, settings: Settings | None = None) -> None:
+        self.settings = settings or Settings()
+
+    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)
+
+    def _handle_app_exception(
+        self, request: Request, exc: AppException
+    ) -> JSONResponse:
+        if exc.status_code >= 500 and self.settings.log_server_errors:
+            log.exception("server_error", error_code=exc.error_code)
+        else:
+            log.warning("client_error", error_code=exc.error_code, message=exc.message)
+
+        response = exc.to_response(getattr(request.state, "request_id", None))
+
+        headers = {}
+        if isinstance(exc, RateLimited) and exc.retry_after:
+            headers["Retry-After"] = str(exc.retry_after)
+
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=response.model_dump(exclude_none=True, mode="json"),
+            headers=headers,
+        )
+
+    def _handle_unexpected_exception(
+        self, request: Request, exc: Exception
+    ) -> JSONResponse:
+        log.exception("unexpected_error", exc_info=exc)
+        response: dict[str, Any] = {
+            "error": {
+                "code": "internal_error",
+                "message": "An unexpected error occurred",
+            }
+        }
+
+        if hasattr(request.state, "request_id"):  # pragma: no branch
+            response["error"]["request_id"] = request.state.request_id
+
+        if self.settings.debug:
+            response["error"]["details"] = {
+                "exception": type(exc).__name__,
+                "message": str(exc),
+            }
+
+        return JSONResponse(status_code=500, content=response)

cuneus/core/extensions.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import logging
+
+from contextlib import asynccontextmanager
+from typing import (
+    Any,
+    AsyncContextManager,
+    AsyncIterator,
+    Protocol,
+    runtime_checkable,
+)
+
+import svcs
+from click import Group
+from fastapi import FastAPI
+from starlette.middleware import Middleware
+
+from .settings import Settings
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class Extension(Protocol):
+    """
+    Protocol for extensions that hook into app lifecycle.
+
+    Extensions can:
+    - Register services with svcs
+    - Add routes via app.include_router()
+    - Add exception handlers via app.add_exception_handler()
+    - Return state to merge into lifespan state
+    """
+
+    def register(
+        self, registry: svcs.Registry, app: FastAPI
+    ) -> AsyncContextManager[dict[str, Any]]:  # pragma: no cover
+        """
+        Async context manager for lifecycle.
+
+        - Enter: startup (register services, add routes, etc.)
+        - Yield: dict of state to merge into lifespan state
+        - Exit: shutdown (cleanup resources)
+        """
+        ...
+
+
+@runtime_checkable
+class HasMiddleware(Protocol):
+    """Extension that provides 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: ...  # pragma: no cover
+
+
+@runtime_checkable
+class HasExceptionHandler(Protocol):
+    """Extension that provides exception handlers."""
+
+    def add_exception_handler(self, app: FastAPI) -> None: ...  # pragma: no cover
+
+
+@runtime_checkable
+class HasRoutes(Protocol):
+    """Extension that provides routes."""
+
+    def add_routes(self, app: FastAPI) -> None: ...  # pragma: no cover
+
+
+class BaseExtension:
+    """
+    Base class for extensions with explicit startup/shutdown hooks.
+
+    For simple extensions, override startup() and shutdown().
+    For full control, override register() directly.
+    """
+
+    def __init__(self, settings: Settings | None = None):
+        self.settings = settings or Settings()
+
+    async def startup(self, registry: svcs.Registry, app: FastAPI) -> dict[str, Any]:
+        """
+        Override to setup resources during app startup.
+
+        You can call app.include_router(), app.add_exception_handler(), etc.
+        Returns a dict of state to merge into lifespan state.
+        """
+        return {}
+
+    async def shutdown(self, app: FastAPI) -> None:
+        """Override to cleanup resources during app shutdown."""
+        pass
+
+    @asynccontextmanager
+    async def register(
+        self, registry: svcs.Registry, app: FastAPI
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Wraps startup/shutdown into async context manager."""
+        state = await self.startup(registry, app)
+        try:
+            yield state
+        finally:
+            await self.shutdown(app)

cuneus/core/logging.py

@@ -0,0 +1,154 @@
+"""
+Structured logging with structlog and request context.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+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.processors.JSONRenderer()
+
+    if not log_settings.log_json:  # pragma: no branch
+        term_width = shutil.get_terminal_size().columns
+        pad_event = term_width - 36
+        renderer: structlog.types.Processor = structlog.dev.ConsoleRenderer(
+            colors=True, pad_event_to=pad_event
+        )
+
+    # 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)
+
+    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()

cuneus/core/settings.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import pathlib
+import sys
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    PyprojectTomlConfigSettingsSource,
+    SettingsConfigDict,
+)
+
+DEFAULT_TOOL_NAME = "cuneus"
+
+
+class CuneusBaseSettings(BaseSettings):
+    """
+    Base settings that loads from:
+    1. pyproject.toml [tool.cuneus] (lowest priority)
+    2. .env file
+    3. Environment variables (highest priority)
+    """
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (
+            init_settings,
+            PyprojectTomlConfigSettingsSource(settings_cls),
+            env_settings,
+            dotenv_settings,
+            file_secret_settings,
+        )
+
+
+class Settings(CuneusBaseSettings):
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="allow",
+        pyproject_toml_depth=2,
+        pyproject_toml_table_header=("tool", DEFAULT_TOOL_NAME),
+    )
+
+    app_name: str = "app"
+    app_module: str = "app.main:app"
+    cli_module: str = "app.main:cli"
+    debug: bool = False
+    version: str | None = None
+
+    # logging
+    log_level: str = "INFO"
+    log_json: bool = False
+    log_server_errors: bool = True
+    request_id_header: str = "X-Request-ID"
+
+    # health
+    health_enabled: bool = True
+    health_prefix: str = "/healthz"
+
+    @classmethod
+    def get_project_root(cls) -> pathlib.Path:
+        """
+        Get the project root by inspecting where pydantic-settings
+        found the pyproject.toml file.
+        """
+        source = PyprojectTomlConfigSettingsSource(
+            cls,
+        )
+        return source.toml_file_path.parent
+
+
+def ensure_project_in_path() -> None:
+    """Add project root to sys.path if not already present."""
+    project_root = str(Settings.get_project_root())
+    if project_root not in sys.path:  # pragma: no branch
+        sys.path.insert(0, project_root)

cuneus/ext/health.py

@@ -0,0 +1,128 @@
+"""
+Health check endpoints using svcs ping capabilities.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+import structlog
+import svcs
+from fastapi import APIRouter, FastAPI, Request
+from pydantic import BaseModel
+
+from ..core.extensions import BaseExtension
+from ..core.settings import Settings
+
+log = structlog.get_logger()
+health_router = APIRouter()
+
+
+class HealthStatus(str, Enum):
+    HEALTHY = "healthy"
+    UNHEALTHY = "unhealthy"
+
+
+class ServiceHealth(BaseModel):
+    name: str
+    status: HealthStatus
+    message: str | None = None
+
+
+class HealthResponse(BaseModel):
+    status: HealthStatus
+    version: str | None = None
+    services: list[ServiceHealth] = []
+
+
+@health_router.get("", response_model=HealthResponse)
+async def health(
+    services: svcs.fastapi.DepContainer, request: Request
+) -> HealthResponse:
+    """Full health check - pings all registered services."""
+    pings = services.get_pings()
+
+    _services: list[ServiceHealth] = []
+    overall_healthy = True
+
+    for ping in pings:
+        try:
+            await ping.aping()
+            _services.append(
+                ServiceHealth(
+                    name=ping.name,
+                    status=HealthStatus.HEALTHY,
+                )
+            )
+        except Exception as e:
+            log.warning("health_check_failed", service=ping.name, error=str(e))
+            _services.append(
+                ServiceHealth(
+                    name=ping.name,
+                    status=HealthStatus.UNHEALTHY,
+                    message=str(e),
+                )
+            )
+            overall_healthy = False
+
+    return HealthResponse(
+        status=(HealthStatus.HEALTHY if overall_healthy else HealthStatus.UNHEALTHY),
+        version=getattr(request.state, "version", "NA"),
+        services=_services,
+    )
+
+
+@health_router.get("/live")
+async def liveness() -> dict[str, str]:
+    """Liveness probe - is the process running?"""
+    return {"status": "ok"}
+
+
+@health_router.get("/ready")
+async def readiness(services: svcs.fastapi.DepContainer) -> dict[str, str]:
+    """Readiness probe - can we serve traffic?"""
+    from fastapi import HTTPException
+
+    pings = services.get_pings()
+
+    for ping in pings:
+        try:
+            await ping.aping()
+        except Exception as e:
+            log.warning("readiness_check_failed", service=ping.name, error=str(e))
+            raise HTTPException(status_code=503, detail=f"{ping.name} unhealthy")
+
+    return {"status": "ok"}
+
+
+class HealthExtension(BaseExtension):
+    """
+    Health check extension using svcs pings.
+
+    Adds:
+        GET /healthz       - Full health check using svcs pings
+        GET /healthz/live  - Liveness probe (always 200)
+        GET /healthz/ready - Readiness probe (503 if unhealthy)
+
+    Settings:
+        - `health_enabled`: bool to disable health routes, default True
+        - `health_prefix`: prefix to include routes default: '/healthz'
+        - `version`: used to display in the response
+    """
+
+    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]:
+        state = await super().startup(registry, app)
+        state["version"] = self.settings.version
+        return state
+
+    def add_routes(self, app: FastAPI) -> None:
+        if self.settings.health_enabled:
+            app.include_router(
+                health_router,
+                prefix=self.settings.health_prefix,
+                tags=["health"],
+            )

cuneus/ext/server.py

@@ -0,0 +1,54 @@
+import click
+
+from ..core.extensions import BaseExtension
+from ..utils import import_from_string
+
+
+class ServerExtension(BaseExtension):
+    """Provides dev/prod/routes CLI commands."""
+
+    def register_cli(self, cli_group: click.Group) -> None:
+        settings = self.settings
+
+        @cli_group.command()
+        @click.option("--host", default="0.0.0.0", help="Bind host")
+        @click.option("--port", default=8000, type=int, help="Bind port")
+        def dev(host: str, port: int) -> None:
+            """Run the application in development mode with reload."""
+            import uvicorn
+
+            uvicorn.run(
+                settings.app_module,
+                host=host,
+                port=port,
+                reload=True,
+                log_config=None,
+                server_header=False,
+            )
+
+        @cli_group.command()
+        @click.option("--host", default="0.0.0.0", help="Bind host")
+        @click.option("--port", default=8000, type=int, help="Bind port")
+        @click.option("--workers", default=1, type=int, help="Number of workers")
+        def prod(host: str, port: int, workers: int) -> None:
+            """Run the application in production mode."""
+            import uvicorn
+
+            uvicorn.run(
+                settings.app_module,
+                host=host,
+                port=port,
+                workers=workers,
+                log_config=None,
+                server_header=False,
+            )
+
+        @cli_group.command()
+        def routes() -> None:
+            """List all registered routes."""
+            app = import_from_string(settings.app_module)
+
+            for route in app.routes:
+                if hasattr(route, "methods"):  # pragma: no branch
+                    methods = ",".join(route.methods - {"HEAD", "OPTIONS"})
+                    click.echo(f"{methods:8} {route.path}")

cuneus/utils.py

@@ -0,0 +1,14 @@
+import importlib
+import typing
+
+
+def import_from_string(import_str: str) -> typing.Any:
+    """Import an object from a module:attribute string."""
+    module_path, _, attr = import_str.partition(":")
+    if not attr:
+        raise ValueError(
+            f"module_path missing function {import_str} expecting 'module.path:name'"
+        )
+
+    module = importlib.import_module(module_path)
+    return getattr(module, attr)

cuneus-0.2.9.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: cuneus
+Version: 0.2.9
+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.11
+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-mock; 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/main.py
+from fastapi import FastAPI
+from cuneus import build_app, Settings
+
+from myapp.extensions import DatabaseExtension
+
+class MyAppSettings(Settings):
+    my_mood: str = "extatic"
+
+app, cli = build_app(
+    DatabaseExtension,
+    settings=MyAppSettings(),
+)
+
+app.include_router(my_router)
+
+__all__ = ["app", "cli"]
+```
+
+That's it. Extensions handle their lifecycle, registration, and middleware.
+
+## 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()
+
+    def middleware(self) -> list[Middleware]:
+        return [Middleware(DatabaseLoggingMiddleware, level=INFO)]
+
+    def register_cli(self, app_cli: click.Group) -> None:
+        @app_cli.command()
+        @click.option("--workers", default=1, type=int, help="Number of workers")
+        def blow_up_db(workers: int): ...
+```
+
+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
+- `middleware() -> list[Middleware]`: Optional middleware to configure
+- `register_cli(group) -> None`: Optional hook to add click commands
+
+### `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_app()`, does what you need
+- **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.9.dist-info/RECORD

@@ -0,0 +1,17 @@
+cuneus/__init__.py,sha256=AJXN9dnXIWn0Eg6JxWOgOf0C386EqBNdHiQG2akTpKc,1295
+cuneus/cli.py,sha256=c8QbGj9QLcr-XJNUgCiSeaO1n5oY3DWBOMj2ruAxUwM,1512
+cuneus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/utils.py,sha256=WyykPUXwxJWpFny5uL87_Fqd2R34za7gXUOf4IyeC0w,423
+cuneus/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/core/application.py,sha256=LHFLqdQvIbjsN1iCVkFJkPFFoIWNGWP2DAPjmI3IWaY,4489
+cuneus/core/exceptions.py,sha256=gyHgVy4UC7gBjs5pXpCzIIyIVsV7K8xt-KZKi8eLJtM,5496
+cuneus/core/extensions.py,sha256=fO9RaJ00Bw9s0VsnCQAAdo-zR9N8573uO3YP2fYUQc4,2934
+cuneus/core/logging.py,sha256=Ql2VDQesZaDRdhua2HLYzvNhkIPVsTGUqxwYBkUI2dc,4581
+cuneus/core/settings.py,sha256=cHHqdKtAjcTPBKXnfG9_GMJiTr7t-iX7rPvIQ480UkI,2248
+cuneus/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/ext/health.py,sha256=6JG25foR5ln2tnRuGYuTVju8bBv16iVR4xKpdf2OVa0,3596
+cuneus/ext/server.py,sha256=wyQMiHFZEFYt1a4wC4IjorEp70kH7fF2aLx3_X5t5RI,1869
+cuneus-0.2.9.dist-info/METADATA,sha256=90bfNg2zE9iFbH9Rd6luS1txjL6PRutr8e6BZosyyiA,6837
+cuneus-0.2.9.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cuneus-0.2.9.dist-info/entry_points.txt,sha256=tzPgom-_UkpP_uLKv3V_XyoIsKg84FBAc9ddjYl0W0Y,43
+cuneus-0.2.9.dist-info/RECORD,,

cuneus-0.2.9.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.9.dist-info/entry_points.txt

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