cuneus 0.2.8__tar.gz → 0.2.10__tar.gz

{cuneus-0.2.8 → cuneus-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cuneus
-Version: 0.2.8
+Version: 0.2.10
 Summary: ASGI application wrapper
 Project-URL: Homepage, https://github.com/rmyers/cuneus
 Project-URL: Documentation, https://github.com/rmyers/cuneus#readme
@@ -24,11 +24,15 @@ 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: aiosqlite[dev]>=0.22.1; 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: opentelemetry-api; extra == 'dev'
+Requires-Dist: opentelemetry-instrumentation; extra == 'dev'
+Requires-Dist: opentelemetry-sdk; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest-mock; extra == 'dev'

cuneus-0.2.10/examples/my_app/main.py

@@ -0,0 +1,6 @@
+from cuneus import build_app
+
+
+app, cli, lifespan = build_app()
+
+__all__ = ["app", "cli", "lifespan"]

cuneus-0.2.10/examples/pyproject.toml

@@ -0,0 +1,7 @@
+[project]
+name = "test-project"
+version = "0.0.1"
+
+[tool.cuneus]
+app_module = "my_app.main:app"
+cli_module = "my_app.main:cli"

{cuneus-0.2.8 → cuneus-0.2.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cuneus"
-version = "0.2.8"
+version = "0.2.10"
 description = "ASGI application wrapper"
 readme = "README.md"
 authors = [{ name = "Robert Myers", email = "robert@julython.org" }]
@@ -18,20 +18,24 @@ dependencies = [
 ]
 
 [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 = [
+    "asgi-lifespan>=2.1.0",
+    "aiosqlite[dev]>=0.22.1",
     "cuneus[all]",
+    "opentelemetry-sdk",
+    "opentelemetry-api",
+    "opentelemetry-instrumentation",
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
     "pytest-cov>=4.0",
     "pytest-mock",
     "httpx>=0.27",
-    "asgi-lifespan>=2.1.0",
     "ruff>=0.3",
     "mypy>=1.8",
 ]
+database = ["sqlalchemy[asyncio]>=2.0", "asyncpg>=0.29.0", "alembic>=1.13.0"]
+redis = ["redis>=5.0"]
+all = ["cuneus[database,redis]"]
 
 [project.scripts]
 cuneus = "cuneus.cli:main"

cuneus-0.2.10/src/cuneus/cli.py

@@ -0,0 +1,51 @@
+"""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-0.2.8 → cuneus-0.2.10}/src/cuneus/core/application.py

@@ -19,8 +19,9 @@ from starlette.middleware import Middleware
 from .settings import Settings
 from .exceptions import ExceptionExtension
 from .logging import LoggingExtension
-from .extensions import Extension, HasCLI, HasExceptionHandler, HasMiddleware
+from .extensions import Extension, HasCLI, HasExceptionHandler, HasMiddleware, HasRoutes
 from ..ext.health import HealthExtension
+from ..ext.server import ServerExtension
 
 logger = structlog.stdlib.get_logger("cuneus")
 
@@ -30,6 +31,7 @@ DEFAULTS = (
     LoggingExtension,
     HealthExtension,
     ExceptionExtension,
+    ServerExtension,
 )
 
 
@@ -39,9 +41,7 @@ class ExtensionConflictError(Exception):
     pass
 
 
-def _instantiate_extension(
-    ext: ExtensionInput, settings: Settings | None = None
-) -> Extension:
+def _instantiate_extension(ext: ExtensionInput, settings: Settings | None = None) -> Extension:
     if isinstance(ext, type) or callable(ext):
         try:
             return ext(settings=settings)
@@ -56,7 +56,7 @@ def build_app(
     settings: Settings | None = None,
     include_defaults: bool = True,
     **fastapi_kwargs: Any,
-) -> tuple[FastAPI, click.Group]:
+) -> tuple[FastAPI, click.Group, svcs.fastapi.lifespan]:
     """
     Build a FastAPI with extensions preconfigured.
 
@@ -93,17 +93,9 @@ def build_app(
 
     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 def lifespan(app: FastAPI, registry: svcs.Registry) -> AsyncIterator[dict[str, Any]]:
         async with AsyncExitStack() as stack:
             state: dict[str, Any] = {}
 
@@ -121,6 +113,7 @@ def build_app(
 
     # Parse extensions for middleware and cli commands
     middleware: list[Middleware] = []
+    app_cli = click.Group()
 
     for ext in all_extensions:
         ext_name = ext.__class__.__name__
@@ -139,5 +132,8 @@ def build_app(
         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
+    return app, app_cli, lifespan

{cuneus-0.2.8 → cuneus-0.2.10}/src/cuneus/core/exceptions.py

@@ -160,9 +160,7 @@ class ExceptionExtension(BaseExtension):
         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:
+    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:
@@ -180,9 +178,7 @@ class ExceptionExtension(BaseExtension):
             headers=headers,
         )
 
-    def _handle_unexpected_exception(
-        self, request: Request, exc: Exception
-    ) -> JSONResponse:
+    def _handle_unexpected_exception(self, request: Request, exc: Exception) -> JSONResponse:
         log.exception("unexpected_error", exc_info=exc)
         response: dict[str, Any] = {
             "error": {

{cuneus-0.2.8 → cuneus-0.2.10}/src/cuneus/core/extensions.py

@@ -67,6 +67,13 @@ class HasExceptionHandler(Protocol):
     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.

{cuneus-0.2.8 → cuneus-0.2.10}/src/cuneus/core/logging.py

@@ -43,7 +43,7 @@ def configure_structlog(settings: Settings | None = None) -> None:
         term_width = shutil.get_terminal_size().columns
         pad_event = term_width - 36
         renderer: structlog.types.Processor = structlog.dev.ConsoleRenderer(
-            colors=True, pad_event=pad_event
+            colors=True, pad_event_to=pad_event
         )
 
     # Configure structlog

{cuneus-0.2.8 → cuneus-0.2.10}/src/cuneus/core/settings.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-import logging
+import pathlib
+import sys
 from pydantic_settings import (
     BaseSettings,
     PydanticBaseSettingsSource,
@@ -8,8 +9,6 @@ from pydantic_settings import (
     SettingsConfigDict,
 )
 
-logger = logging.getLogger(__name__)
-
 DEFAULT_TOOL_NAME = "cuneus"
 
 
@@ -40,7 +39,6 @@ class CuneusBaseSettings(BaseSettings):
 
 
 class Settings(CuneusBaseSettings):
-
     model_config = SettingsConfigDict(
         env_file=".env",
         env_file_encoding="utf-8",
@@ -64,3 +62,21 @@ class Settings(CuneusBaseSettings):
     # 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-0.2.10/src/cuneus/dependencies.py

@@ -0,0 +1,79 @@
+# cuneus/core/dependencies.py
+from __future__ import annotations
+
+import importlib
+import logging
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Dependency:
+    """A required dependency with install hint."""
+
+    import_name: str
+    package_name: str | None = None  # pip package name if different from import
+
+    @property
+    def pip_name(self) -> str:
+        return self.package_name or self.import_name
+
+
+class MissingDependencyError(ImportError):
+    """Raised when required dependencies are not installed."""
+
+    def __init__(self, extension: str, missing: list[Dependency]):
+        self.extension = extension
+        self.missing = missing
+        packages = " ".join(d.pip_name for d in missing)
+        super().__init__(
+            f"{extension} requires additional dependencies. Install with: uv add {packages}"
+        )
+
+
+def check_dependencies(extension: str, *deps: Dependency) -> None:
+    """
+    Check that dependencies are installed, raise helpful error if not.
+
+    Usage:
+        from cuneus.core.dependencies import check_dependencies, Dependency
+
+        check_dependencies(
+            "DatabaseExtension",
+            Dependency("sqlalchemy"),
+            Dependency("asyncpg"),
+        )
+    """
+    missing = []
+    for dep in deps:
+        try:
+            importlib.import_module(dep.import_name)
+        except ImportError:
+            missing.append(dep)
+
+    if missing:
+        raise MissingDependencyError(extension, missing)
+
+
+def warn_missing(extension: str, *deps: Dependency) -> list[Dependency]:
+    """
+    Check dependencies but only warn, don't raise. Returns list of missing.
+
+    Useful for optional features within an extension.
+    """
+    missing = []
+    for dep in deps:
+        try:
+            importlib.import_module(dep.import_name)
+        except ImportError:
+            missing.append(dep)
+
+    if missing:
+        packages = " ".join(d.pip_name for d in missing)
+        logger.warning(
+            f"{extension}: optional dependencies not installed. "
+            f"Some features disabled. Install with: uv add {packages}"
+        )
+
+    return missing

cuneus-0.2.10/src/cuneus/ext/database.py

@@ -0,0 +1,278 @@
+# cuneus/ext/database.py
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, AsyncIterator
+
+import click
+import svcs
+from fastapi import FastAPI
+from pydantic import Field, SecretStr, computed_field
+from pydantic_settings import SettingsConfigDict
+from structlog.stdlib import get_logger
+
+from ..core.extensions import BaseExtension, HasCLI
+from ..core.settings import CuneusBaseSettings, DEFAULT_TOOL_NAME
+from ..dependencies import Dependency, check_dependencies
+
+check_dependencies(
+    "cuneus.ext.database",
+    Dependency("sqlalchemy"),
+)
+
+from sqlalchemy import URL, make_url, text
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+logger = get_logger(__name__)
+
+
+class DatabaseSettings(CuneusBaseSettings):
+    """Database configuration."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="DATABASE_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        pyproject_toml_depth=2,
+        pyproject_toml_table_header=("tool", DEFAULT_TOOL_NAME, "database"),
+    )
+
+    # Option 1: Full URL (takes precedence if set)
+    url: str | None = None
+
+    # Option 2: Individual parts
+    driver: str = "postgresql+asyncpg"
+    host: str = "localhost"
+    port: int = 5432
+    name: str = "app"
+    username: str | None = None
+    password: SecretStr | None = None
+
+    # Pool settings
+    pool_size: int = 5
+    pool_max_overflow: int = 10
+    pool_recycle: int = 3600
+    echo: bool = False
+
+    # Alembic
+    alembic_config: Path = Path("alembic.ini")
+
+    @computed_field
+    @property
+    def url_parsed(self) -> URL:
+        """Get SQLAlchemy URL, either from url string or constructed from parts."""
+        if self.url:
+            return make_url(self.url)
+
+        needs_opts = "sqlite" not in self.driver
+        password_value = self.password.get_secret_value() if self.password else None
+        password = password_value if needs_opts else None
+
+        return URL.create(
+            drivername=self.driver,
+            username=self.username if needs_opts else None,
+            password=password,
+            host=self.host if needs_opts else None,
+            port=self.port if needs_opts else None,
+            database=self.name,
+        )
+
+    @computed_field
+    @property
+    def url_redacted(self) -> str:
+        """URL safe for logging (password hidden)."""
+        return self.url_parsed.render_as_string(hide_password=True)
+
+
+class DatabaseExtension(BaseExtension, HasCLI):
+    """
+    Database extension providing AsyncSession via svcs.
+
+    Registers:
+        - AsyncEngine: The SQLAlchemy async engine
+        - async_sessionmaker: Factory for creating sessions
+        - AsyncSession: Request-scoped session (via factory)
+
+    CLI Commands:
+        - db upgrade [revision]: Run migrations
+        - db downgrade [revision]: Rollback migrations
+        - db revision -m "message": Create new migration
+        - db current: Show current revision
+        - db history: Show migration history
+        - db check: Check database connectivity
+
+    Configuration (env or pyproject.toml [tool.cuneus.database]):
+        DATABASE_URL: Connection string
+        DATABASE_POOL_SIZE: Connection pool size (default: 5)
+        DATABASE_POOL_MAX_OVERFLOW: Max overflow connections (default: 10)
+        DATABASE_POOL_RECYCLE: Connection recycle time in seconds (default: 3600)
+        DATABASE_ECHO: Echo SQL statements (default: false)
+        DATABASE_ALEMBIC_CONFIG: Path to alembic.ini (default: alembic.ini)
+    """
+
+    _session_factory: async_sessionmaker[AsyncSession]
+    _engine: AsyncEngine
+
+    def __init__(self, settings: DatabaseSettings | None = None):
+        self.settings = settings or DatabaseSettings()
+
+    @asynccontextmanager
+    async def register(
+        self, registry: svcs.Registry, app: FastAPI
+    ) -> AsyncIterator[dict[str, Any]]:
+        self._engine = create_async_engine(
+            self.settings.url_parsed,
+            # pool_size=self.settings.pool_size,
+            # max_overflow=self.settings.pool_max_overflow,
+            pool_recycle=self.settings.pool_recycle,
+            echo=self.settings.echo,
+        )
+
+        self._session_factory = async_sessionmaker(
+            self._engine,
+            class_=AsyncSession,
+            expire_on_commit=False,
+        )
+
+        registry.register_value(AsyncEngine, self._engine, ping=self._check)
+        registry.register_value(async_sessionmaker, self._session_factory)
+
+        @asynccontextmanager
+        async def session_factory() -> AsyncIterator[AsyncSession]:
+            async with self._session_factory() as session:
+                try:
+                    yield session
+                    await session.commit()
+                except Exception:
+                    await session.rollback()
+                    raise
+
+        registry.register_factory(AsyncSession, session_factory)
+
+        logger.info("Database started", extra={"url": self.settings.url_redacted})
+
+        try:
+            yield {
+                "db_engine": self._engine,
+                "db_session_factory": self._session_factory,
+            }
+        finally:
+            await self._engine.dispose()
+            logger.info("Database shutdown")
+
+    async def _check(self):
+        engine = create_async_engine(self.settings.url_parsed)
+        try:
+            async with engine.connect() as conn:
+                await conn.execute(text("SELECT 1"))
+        finally:
+            await engine.dispose()
+
+    def register_cli(self, cli_group: click.Group) -> None:
+        settings = self.settings
+
+        @cli_group.group()
+        def db():
+            """Database management commands."""
+            pass
+
+        @db.command()
+        @click.argument("revision", default="head")
+        def upgrade(revision: str):
+            """Upgrade database to revision (default: head)."""
+            _run_alembic_cmd("upgrade", settings.alembic_config, revision=revision)
+
+        @db.command()
+        @click.argument("revision", default="-1")
+        def downgrade(revision: str):
+            """Downgrade database to revision (default: -1)."""
+            _run_alembic_cmd("downgrade", settings.alembic_config, revision=revision)
+
+        @db.command()
+        @click.option("-m", "--message", required=True, help="Migration message")
+        @click.option("--autogenerate/--no-autogenerate", default=True)
+        def revision(message: str, autogenerate: bool):
+            """Create a new migration revision."""
+            _run_alembic_cmd(
+                "revision",
+                settings.alembic_config,
+                message=message,
+                autogenerate=autogenerate,
+            )
+
+        @db.command()
+        def current():
+            """Show current database revision."""
+            _run_alembic_cmd("current", settings.alembic_config)
+
+        @db.command()
+        def history():
+            """Show migration history."""
+            _run_alembic_cmd("history", settings.alembic_config)
+
+        @db.command()
+        @click.argument("template", default="async")
+        def init():
+            """
+            Create a new alembic setup by default this will use the async template
+            """
+
+        @db.command()
+        @click.pass_context
+        def check(ctx: click.Context):
+            """Check database connectivity."""
+            import asyncio
+
+            async def _check():
+                engine = create_async_engine(settings.url_parsed)
+                try:
+                    async with engine.connect() as conn:
+                        await conn.execute(text("SELECT 1"))
+                    click.echo("✓ Database connection OK")
+                except Exception as e:
+                    print(e)
+                    click.echo(f"✗ Database connection failed: {e}", err=True)
+                    ctx.exit(1)
+                finally:
+                    await engine.dispose()
+
+            asyncio.run(_check())
+
+
+def _run_alembic_cmd(
+    cmd: str,
+    config_path: Path,
+    revision: str | None = None,
+    message: str | None = None,
+    autogenerate: bool = False,
+) -> None:
+    """Run an alembic command."""
+    from alembic import command
+    from alembic.config import Config
+
+    if not config_path.exists():
+        raise click.ClickException(f"Alembic config not found: {config_path}")
+
+    cfg = Config(str(config_path))
+
+    match cmd:
+        case "upgrade":
+            command.upgrade(cfg, revision or "head")
+        case "downgrade":
+            command.downgrade(cfg, revision or "-1")
+        case "revision":
+            command.revision(cfg, message=message, autogenerate=autogenerate)
+        case "current":
+            command.current(cfg)
+        case "history":
+            command.history(cfg)
+        case _:
+            raise click.ClickException(f"Unknown command: {cmd}")