cuneus 0.2.1__tar.gz

cuneus-0.2.1/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.coverage
+
+# Virtual environments
+.venv
+
+# Settings
+.env*
+
+# Node
+node_modules
+.tanstack/

cuneus-0.2.1/.python-version

@@ -0,0 +1 @@
+3.14

cuneus-0.2.1/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: cuneus
+Version: 0.2.1
+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-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>=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.py
+from fastapi import FastAPI
+from cuneus import build_lifespan, Settings
+from cuneus.middleware.logging import LoggingMiddleware
+
+from myapp.extensions import DatabaseExtension
+
+settings = Settings()
+lifespan = build_lifespan(
+    settings,
+    DatabaseExtension(settings),
+)
+
+app = FastAPI(lifespan=lifespan, title="My App", version="1.0.0")
+
+# Add middleware directly to FastAPI
+app.add_middleware(LoggingMiddleware)
+```
+
+That's it. Extensions handle their lifecycle, FastAPI handles the rest.
+
+## 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()
+```
+
+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
+
+### `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_lifespan()`, does what you need
+- **No magic** — middleware added directly to FastAPI, not hidden
+- **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.1/README.md

@@ -0,0 +1,183 @@
+# 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.py
+from fastapi import FastAPI
+from cuneus import build_lifespan, Settings
+from cuneus.middleware.logging import LoggingMiddleware
+
+from myapp.extensions import DatabaseExtension
+
+settings = Settings()
+lifespan = build_lifespan(
+    settings,
+    DatabaseExtension(settings),
+)
+
+app = FastAPI(lifespan=lifespan, title="My App", version="1.0.0")
+
+# Add middleware directly to FastAPI
+app.add_middleware(LoggingMiddleware)
+```
+
+That's it. Extensions handle their lifecycle, FastAPI handles the rest.
+
+## 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()
+```
+
+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
+
+### `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_lifespan()`, does what you need
+- **No magic** — middleware added directly to FastAPI, not hidden
+- **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.1/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "cuneus"
+version = "0.2.1"
+description = "ASGI application wrapper"
+readme = "README.md"
+authors = [{ name = "Robert Myers", email = "robert@julython.org" }]
+requires-python = ">=3.10"
+
+dependencies = [
+    "fastapi>=0.109.0",
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    "click>=8.0",
+    "uvicorn[standard]>=0.27.0",
+    # Core dependencies we build on
+    "svcs>=24.1.0",
+    "structlog>=24.1.0",
+]
+
+[project.optional-dependencies]
+database = ["sqlalchemy[asyncio]>=2.0", "asyncpg>=0.29.0", "alembic>=1.13.0"]
+redis = ["redis>=5.0"]
+all = ["cuneus[database,redis]"]
+dev = [
+    "cuneus[all]",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=4.0",
+    "httpx>=0.27",
+    "asgi-lifespan>=2.1.0",
+    "ruff>=0.3",
+    "mypy>=1.8",
+]
+
+[project.scripts]
+cuneus = "cuneus.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/rmyers/cuneus"
+Documentation = "https://github.com/rmyers/cuneus#readme"
+Repository = "https://github.com/rmyers/cuneus"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cuneus"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "ASYNC"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["src/cuneus"]
+branch = true

cuneus-0.2.1/src/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 cuneus.core.application import (
+    BaseExtension,
+    Extension,
+    Settings,
+    build_lifespan,
+    get_settings,
+    load_pyproject_config,
+)
+from cuneus.core.execptions import (
+    AppException,
+    BadRequest,
+    Unauthorized,
+    Forbidden,
+    NotFound,
+    Conflict,
+    RateLimited,
+    ServiceUnavailable,
+    DatabaseError,
+    RedisError,
+    ExternalServiceError,
+    ExceptionExtension,
+)
+
+__version__ = "0.2.1"
+__all__ = [
+    # Core
+    "BaseExtension",
+    "Extension",
+    "Settings",
+    "build_lifespan",
+    "get_settings",
+    "load_pyproject_config",
+    # Exceptions
+    "AppException",
+    "BadRequest",
+    "Unauthorized",
+    "Forbidden",
+    "NotFound",
+    "Conflict",
+    "RateLimited",
+    "ServiceUnavailable",
+    "DatabaseError",
+    "RedisError",
+    "ExternalServiceError",
+    "ExceptionExtension",
+]