cuneus 0.2.1__tar.gz → 0.2.2__tar.gz

{cuneus-0.2.1 → cuneus-0.2.2}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: cuneus
-Version: 0.2.1
+Version: 0.2.2
 Summary: ASGI application wrapper
 Project-URL: Homepage, https://github.com/rmyers/cuneus
 Project-URL: Documentation, https://github.com/rmyers/cuneus#readme
 Project-URL: Repository, https://github.com/rmyers/cuneus
 Author-email: Robert Myers <robert@julython.org>
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Requires-Dist: click>=8.0
 Requires-Dist: fastapi>=0.109.0
 Requires-Dist: pydantic-settings>=2.0
@@ -62,26 +62,26 @@ pip install cuneus
 ## Quick Start
 
 ```python
-# app.py
+# app/main.py
 from fastapi import FastAPI
-from cuneus import build_lifespan, Settings
-from cuneus.middleware.logging import LoggingMiddleware
+from cuneus import build_app, Settings
 
 from myapp.extensions import DatabaseExtension
 
-settings = Settings()
-lifespan = build_lifespan(
-    settings,
-    DatabaseExtension(settings),
+class MyAppSettings(Settings):
+    my_mood: str = "extatic"
+
+app, cli = build_app(
+    DatabaseExtension,
+    settings=MyAppSettings(),
 )
 
-app = FastAPI(lifespan=lifespan, title="My App", version="1.0.0")
+app.include_router(my_router)
 
-# Add middleware directly to FastAPI
-app.add_middleware(LoggingMiddleware)
+__all__ = ["app", "cli"]
 ```
 
-That's it. Extensions handle their lifecycle, FastAPI handles the rest.
+That's it. Extensions handle their lifecycle, registration, and middleware.
 
 ## Creating Extensions
 
@@ -115,6 +115,14 @@ class DatabaseExtension(BaseExtension):
     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:
@@ -195,6 +203,8 @@ 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
 
@@ -213,8 +223,7 @@ def register(self, registry: svcs.Registry, app: FastAPI) -> AsyncContextManager
 
 ## Why cuneus?
 
-- **Simple** — one function, `build_lifespan()`, does what you need
-- **No magic** — middleware added directly to FastAPI, not hidden
+- **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

{cuneus-0.2.1 → cuneus-0.2.2}/README.md

@@ -21,26 +21,26 @@ pip install cuneus
 ## Quick Start
 
 ```python
-# app.py
+# app/main.py
 from fastapi import FastAPI
-from cuneus import build_lifespan, Settings
-from cuneus.middleware.logging import LoggingMiddleware
+from cuneus import build_app, Settings
 
 from myapp.extensions import DatabaseExtension
 
-settings = Settings()
-lifespan = build_lifespan(
-    settings,
-    DatabaseExtension(settings),
+class MyAppSettings(Settings):
+    my_mood: str = "extatic"
+
+app, cli = build_app(
+    DatabaseExtension,
+    settings=MyAppSettings(),
 )
 
-app = FastAPI(lifespan=lifespan, title="My App", version="1.0.0")
+app.include_router(my_router)
 
-# Add middleware directly to FastAPI
-app.add_middleware(LoggingMiddleware)
+__all__ = ["app", "cli"]
 ```
 
-That's it. Extensions handle their lifecycle, FastAPI handles the rest.
+That's it. Extensions handle their lifecycle, registration, and middleware.
 
 ## Creating Extensions
 
@@ -74,6 +74,14 @@ class DatabaseExtension(BaseExtension):
     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:
@@ -154,6 +162,8 @@ 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
 
@@ -172,8 +182,7 @@ def register(self, registry: svcs.Registry, app: FastAPI) -> AsyncContextManager
 
 ## Why cuneus?
 
-- **Simple** — one function, `build_lifespan()`, does what you need
-- **No magic** — middleware added directly to FastAPI, not hidden
+- **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

{cuneus-0.2.1 → cuneus-0.2.2}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "cuneus"
-version = "0.2.1"
+version = "0.2.2"
 description = "ASGI application wrapper"
 readme = "README.md"
 authors = [{ name = "Robert Myers", email = "robert@julython.org" }]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 
 dependencies = [
     "fastapi>=0.109.0",
@@ -48,14 +48,14 @@ build-backend = "hatchling.build"
 packages = ["src/cuneus"]
 
 [tool.ruff]
-target-version = "py311"
+target-version = "py312"
 line-length = 100
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B", "SIM", "ASYNC"]
 
 [tool.mypy]
-python_version = "3.11"
+python_version = "3.12"
 strict = true
 warn_return_any = true
 warn_unused_ignores = true

{cuneus-0.2.1 → cuneus-0.2.2}/src/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-0.2.2/src/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-0.2.2/src/cuneus/core/application.py

@@ -0,0 +1,127 @@
+"""
+cuneus - The wedge stone that locks the arch together.
+
+Lightweight lifespan management for FastAPI applications.
+"""
+
+from __future__ import annotations
+
+from contextlib import AsyncExitStack, asynccontextmanager
+from typing import Any, AsyncIterator, Callable
+
+import click
+import svcs
+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]:
+    """
+    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()
+
+    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
+    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_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}")
+                    state.update(ext_state)
+
+            yield state
+
+    # 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)
+
+    app = FastAPI(lifespan=lifespan, middleware=middleware, **fastapi_kwargs)
+    return app, app_cli

{cuneus-0.2.1 → cuneus-0.2.2}/src/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-0.2.2/src/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)