cuneus 0.2.1__py3-none-any.whl → 0.2.2__py3-none-any.whl

cuneus/__init__.py

@@ -15,15 +15,8 @@ Example:
     fastapi_app = app.build()
 """
 
-from cuneus.core.application import (
-    BaseExtension,
-    Extension,
-    Settings,
-    build_lifespan,
-    get_settings,
-    load_pyproject_config,
-)
-from cuneus.core.execptions import (
+from .core.application import build_app
+from .core.execptions import (
     AppException,
     BadRequest,
     Unauthorized,
@@ -37,16 +30,19 @@ from cuneus.core.execptions import (
     ExternalServiceError,
     ExceptionExtension,
 )
+from .core.extensions import BaseExtension, Extension
+from .core.settings import Settings
 
 __version__ = "0.2.1"
 __all__ = [
-    # Core
+    # Core exported functions
+    # Application
+    "build_app",
+    # Extension
     "BaseExtension",
     "Extension",
+    # Settings
     "Settings",
-    "build_lifespan",
-    "get_settings",
-    "load_pyproject_config",
     # Exceptions
     "AppException",
     "BadRequest",

cuneus/cli.py

@@ -0,0 +1,129 @@
+"""Base CLI that cuneus provides."""
+
+import click
+import importlib
+import sys
+from typing import Any, cast
+
+from .core.settings import Settings
+
+
+def import_from_string(import_str: str) -> Any:
+    """Import an object from a module:attribute string."""
+    module_path, _, attr = import_str.partition(":")
+    if not attr:
+        attr = "app"  # default attribute name
+
+    module = importlib.import_module(module_path)
+    return getattr(module, attr)
+
+
+def get_user_cli() -> click.Group | None:
+    """Attempt to load user's CLI from config."""
+    config = Settings()
+
+    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
+
+
+@click.group()
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    """Cuneus CLI - FastAPI application framework."""
+    ctx.ensure_object(dict)
+
+
+@cli.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 server."""
+    import uvicorn
+
+    config = Settings()
+
+    uvicorn.run(
+        config.app_module,
+        host=host,
+        port=port,
+        reload=True,
+    )
+
+
+@cli.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 server."""
+    import uvicorn
+
+    config = Settings()
+
+    uvicorn.run(
+        config.app_module,
+        host=host,
+        port=port,
+        workers=workers,
+    )
+
+
+@cli.command()
+def routes() -> None:
+    """List all registered routes."""
+    config = Settings()
+    app = import_from_string(config.app_module)
+
+    for route in app.routes:
+        if hasattr(route, "methods"):
+            methods = ",".join(route.methods - {"HEAD", "OPTIONS"})
+            click.echo(f"{methods:8} {route.path}")
+
+
+class CuneusCLI(click.Group):
+    """Merges base cuneus commands with user's app CLI."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._user_cli: click.Group | None = None
+        self._user_cli_loaded = False
+
+        # Register base commands directly
+        self.add_command(dev)
+        self.add_command(prod)
+        self.add_command(routes)
+
+    @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]:
+        commands = set(super().list_commands(ctx))
+        if self.user_cli:
+            commands.update(self.user_cli.list_commands(ctx))
+        return sorted(commands)
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        # User CLI takes priority
+        if self.user_cli:
+            cmd = self.user_cli.get_command(ctx, cmd_name)
+            if cmd:
+                return cmd
+        return super().get_command(ctx, cmd_name)
+
+
+# This is the actual entry point
+main = CuneusCLI(help="Cuneus CLI - FastAPI application framework")
+
+
+if __name__ == "__main__":
+    main()

cuneus/core/application.py

@@ -6,152 +6,66 @@ Lightweight lifespan management for FastAPI applications.
 
 from __future__ import annotations
 
-import logging
-import tomllib
-import uuid
 from contextlib import AsyncExitStack, asynccontextmanager
-from pathlib import Path
-from typing import Any, AsyncContextManager, AsyncIterator, Protocol, runtime_checkable
+from typing import Any, AsyncIterator, Callable
 
+import click
 import svcs
-from fastapi import FastAPI, Request
-from pydantic import model_validator
-from pydantic_settings import BaseSettings, SettingsConfigDict
-from starlette.types import ASGIApp
-
-logger = logging.getLogger(__name__)
-
-DEFAULT_TOOL_NAME = "cuneus"
-
-
-def load_pyproject_config(
-    tool_name: str = DEFAULT_TOOL_NAME,
-    path: Path | None = None,
-) -> dict[str, Any]:
-    """Load configuration from pyproject.toml under [tool.{tool_name}]."""
-    if path is None:
-        path = Path.cwd()
-
-    for parent in [path, *path.parents]:
-        pyproject = parent / "pyproject.toml"
-        if pyproject.exists():
-            with open(pyproject, "rb") as f:
-                data = tomllib.load(f)
-            return data.get("tool", {}).get(tool_name, {})
-
-    return {}
-
-
-class Settings(BaseSettings):
-    """
-    Base settings that loads from:
-    1. pyproject.toml [tool.cuneus] (lowest priority)
-    2. .env file
-    3. Environment variables (highest priority)
+from fastapi import FastAPI
+from starlette.middleware import Middleware
+
+from .settings import Settings
+from .execptions import ExceptionExtension
+from .logging import LoggingExtension
+from .extensions import Extension, HasCLI, HasMiddleware
+from ..ext.health import HealthExtension
+
+
+type ExtensionInput = Extension | Callable[..., Extension]
+
+DEFAULT_EXTENSIONS = (
+    LoggingExtension,
+    HealthExtension,
+    ExceptionExtension,
+)
+
+
+def _instantiate_extension(
+    ext: ExtensionInput, settings: Settings | None = None
+) -> Extension:
+    if isinstance(ext, type):
+        # It's a class, instantiate it
+        return ext(settings)
+    if callable(ext):
+        # It's a factory function
+        return ext(settings)
+    # Already an instance
+    return ext
+
+
+def build_app(
+    *extensions: ExtensionInput,
+    settings: Settings | None = None,
+    include_defaults: bool = True,
+    **fastapi_kwargs: Any,
+) -> tuple[FastAPI, click.Group]:
     """
-
-    model_config = SettingsConfigDict(
-        env_file=".env",
-        env_file_encoding="utf-8",
-        extra="ignore",
-    )
-
-    app_name: str = "app"
-    app_module: str = "app.main:app"
-    debug: bool = False
-    version: str | None = None
-
-    # logging
-    log_level: str = "INFO"
-    log_json: bool = False
-    log_server_errors: bool = True
-
-    # health
-    health_enabled: bool = True
-    health_prefix: str = "/healthz"
-
-    @model_validator(mode="before")
-    @classmethod
-    def load_from_pyproject(cls, data: dict[str, Any]) -> dict[str, Any]:
-        pyproject_config = load_pyproject_config()
-        return {**pyproject_config, **data}
-
-
-@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]]:
-        """
-        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)
-        """
-        ...
-
-
-class BaseExtension:
-    """
-    Base class for extensions with explicit startup/shutdown hooks.
-
-    For simple extensions, override startup() and shutdown().
-    For full control, override register() directly.
-    """
-
-    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)
-
-
-def build_lifespan(settings: Settings, *extensions: Extension):
-    """
-    Create a lifespan context manager for FastAPI.
+    Build a FastAPI with extensions preconfigured.
 
     The returned lifespan has a `.registry` attribute for testing overrides.
 
     Usage:
-        from cuneus import build_lifespan, Settings
+        from cuneus import build_app, Settings, SettingsExtension
         from myapp.extensions import DatabaseExtension
 
         settings = Settings()
-        lifespan = build_lifespan(
-            settings,
+        app, cli = build_app(
+            SettingsExtension(settings),
             DatabaseExtension(settings),
+            title="Args are passed to FastAPI",
         )
 
-        app = FastAPI(lifespan=lifespan, title="My App")
+        __all__ = ["app", "cli"]
 
     Testing:
         from myapp import app, lifespan
@@ -159,8 +73,29 @@ def build_lifespan(settings: Settings, *extensions: Extension):
         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()
+
+    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_extensions = [_instantiate_extension(ext, settings) for ext in all_inputs]
+
+    @click.group()
+    @click.pass_context
+    def app_cli(ctx: click.Context) -> None:
+        """Application CLI."""
+        ctx.ensure_object(dict)
 
     @svcs.fastapi.lifespan
     @asynccontextmanager
@@ -168,9 +103,9 @@ def build_lifespan(settings: Settings, *extensions: Extension):
         app: FastAPI, registry: svcs.Registry
     ) -> AsyncIterator[dict[str, Any]]:
         async with AsyncExitStack() as stack:
-            state: dict[str, Any] = {"settings": settings}
+            state: dict[str, Any] = {}
 
-            for ext in extensions:
+            for ext in all_extensions:
                 ext_state = await stack.enter_async_context(ext.register(registry, app))
                 if ext_state:
                     if overlap := state.keys() & ext_state.keys():
@@ -179,52 +114,14 @@ def build_lifespan(settings: Settings, *extensions: Extension):
 
             yield state
 
-    return lifespan
-
-
-class RequestIDMiddleware:
-    """
-    Middleware that adds a unique request_id to each request.
-
-    Access via request.state.request_id
-    """
-
-    def __init__(self, app: ASGIApp, header_name: str = "X-Request-ID"):
-        self.app = app
-        self.header_name = header_name
-
-    async def __call__(self, scope, receive, send):
-        if scope["type"] != "http":
-            await self.app(scope, receive, send)
-            return
-
-        # Check for existing request ID in headers, or generate new one
-        headers = dict(scope.get("headers", []))
-        request_id = headers.get(
-            self.header_name.lower().encode(), str(uuid.uuid4())[:8].encode()
-        ).decode()
-
-        # Store in scope state
-        if "state" not in scope:
-            scope["state"] = {}
-        scope["state"]["request_id"] = request_id
-
-        # Add request ID to response headers
-        async def send_with_request_id(message):
-            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)
-
-        await self.app(scope, receive, send_with_request_id)
-
-
-def get_settings(request: Request) -> Settings:
-    """Get settings from request state."""
-    return request.state.settings
+    # Parse extensions for middleware and cli commands
+    middleware: list[Middleware] = []
 
+    for ext in all_extensions:
+        if isinstance(ext, HasMiddleware):
+            middleware.extend(ext.middleware())
+        if isinstance(ext, HasCLI):
+            ext.register_cli(app_cli)
 
-def get_request_id(request: Request) -> str:
-    """Get the request ID from request state."""
-    return request.state.request_id
+    app = FastAPI(lifespan=lifespan, middleware=middleware, **fastapi_kwargs)
+    return app, app_cli

cuneus/core/execptions.py

@@ -12,7 +12,8 @@ from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel
 
-from cuneus.core.application import BaseExtension, Settings
+from .extensions import BaseExtension
+from .settings import Settings
 
 log = structlog.get_logger()
 
@@ -103,7 +104,7 @@ class RateLimited(AppException):
     error_code = "rate_limited"
     message = "Too many requests"
 
-    def __init__(self, retry_after: int | None = None, **kwargs):
+    def __init__(self, retry_after: int | None = None, **kwargs: Any) -> None:
         super().__init__(**kwargs)
         self.retry_after = retry_after
 
@@ -162,11 +163,11 @@ class ExceptionExtension(BaseExtension):
         )
     """
 
-    def __init__(self, settings: Settings) -> None:
-        self.settings = 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]:
-        app.add_exception_handler(AppException, self._handle_app_exception)  # type: ignore[]
+        app.add_exception_handler(AppException, self._handle_app_exception)  # type: ignore[arg-type]
         app.add_exception_handler(Exception, self._handle_unexpected_exception)
         return {}
 

cuneus/core/extensions.py

@@ -0,0 +1,98 @@
+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 __init__(self, settings: Settings | None = None) -> None: ...
+
+    def register(
+        self, registry: svcs.Registry, app: FastAPI
+    ) -> AsyncContextManager[dict[str, Any]]:
+        """
+        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]: ...
+
+
+@runtime_checkable
+class HasCLI(Protocol):
+    """Extension that provides CLI commands."""
+
+    def register_cli(self, cli_group: Group) -> None: ...
+
+
+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)