capsize-commons 0.1.0__tar.gz

capsize_commons-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: capsize-commons
+Version: 0.1.0
+Summary: Selectively installable common building blocks shared across Capsize projects: structured logging, FastAPI auth/health, SQLAlchemy conventions, HTTP retry, and case conversion.
+Author-email: Capsize LLC <contact@capsizegames.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Capsize-Games/capsize-commons
+Project-URL: Issues, https://github.com/Capsize-Games/capsize-commons/issues
+Keywords: capsize,commons,logging,fastapi,sqlalchemy,utilities
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: config
+Requires-Dist: pydantic>=2.7; extra == "config"
+Requires-Dist: pydantic-settings>=2.3; extra == "config"
+Provides-Extra: db
+Requires-Dist: sqlalchemy>=2.0.30; extra == "db"
+Provides-Extra: web
+Requires-Dist: fastapi>=0.115; extra == "web"
+Provides-Extra: http
+Requires-Dist: httpx>=0.27; extra == "http"
+Provides-Extra: all
+Requires-Dist: pydantic>=2.7; extra == "all"
+Requires-Dist: pydantic-settings>=2.3; extra == "all"
+Requires-Dist: sqlalchemy>=2.0.30; extra == "all"
+Requires-Dist: fastapi>=0.115; extra == "all"
+Requires-Dist: httpx>=0.27; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pydantic>=2.7; extra == "dev"
+Requires-Dist: pydantic-settings>=2.3; extra == "dev"
+Requires-Dist: sqlalchemy>=2.0.30; extra == "dev"
+Requires-Dist: fastapi>=0.115; extra == "dev"
+
+# capsize-commons (Python)
+
+The Python distribution of [`capsize-commons`](../README.md). It has **no
+required dependencies**; each sub-package is pulled in through an extra and
+imports its third-party dependency lazily, so importing one module never drags
+in another module's stack.
+
+## Install
+
+```bash
+uv add "capsize-commons[logging]"        # anything is optional
+uv add "capsize-commons[web,db,config]"  # or pick several
+uv add "capsize-commons[all]"            # or everything
+```
+
+| Extra | Enables | Third-party |
+|---|---|---|
+| `config` | `capsize_commons.config` | `pydantic`, `pydantic-settings` |
+| `db` | `capsize_commons.db` | `sqlalchemy` |
+| `web` | `capsize_commons.web` | `fastapi` |
+| `http` | `capsize_commons.http` | none (stdlib only) |
+| `all` | every sub-package | above |
+
+`capsize_commons.text` and `capsize_commons.logging` are stdlib-only and ship
+with the base install.
+
+## Modules
+
+```python
+# Structured JSON logs matching §14
+from capsize_commons.logging import configure_logging
+configure_logging(json_mode=True, logger_name="myapp")
+
+# Env-backed settings, cached per class
+from capsize_commons.config import CapsizeSettings, get_settings
+class Settings(CapsizeSettings):
+    model_config = CapsizeSettings.model_config | {"env_prefix": "MYAPP_"}
+    database_url: str = "sqlite:///./app.db"
+
+# FastAPI auth + health
+from capsize_commons.web import make_api_key_dependency, install_health_routes
+
+# SQLAlchemy engine, sessions and the standard model mixin
+from capsize_commons.db import make_engine, make_session_factory, TimestampedBase
+
+# HTTP retry with backoff
+from capsize_commons.http import Backoff, retry_async
+
+# Naming (§3.1)
+from capsize_commons.text import slugify, to_snake_case
+```
+
+## Development
+
+```bash
+cd python
+uv sync --all-extras
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run mypy src
+```
+
+Or from the repository root: `just test`, `just lint`, `just typecheck`.

capsize_commons-0.1.0/README.md

@@ -0,0 +1,63 @@
+# capsize-commons (Python)
+
+The Python distribution of [`capsize-commons`](../README.md). It has **no
+required dependencies**; each sub-package is pulled in through an extra and
+imports its third-party dependency lazily, so importing one module never drags
+in another module's stack.
+
+## Install
+
+```bash
+uv add "capsize-commons[logging]"        # anything is optional
+uv add "capsize-commons[web,db,config]"  # or pick several
+uv add "capsize-commons[all]"            # or everything
+```
+
+| Extra | Enables | Third-party |
+|---|---|---|
+| `config` | `capsize_commons.config` | `pydantic`, `pydantic-settings` |
+| `db` | `capsize_commons.db` | `sqlalchemy` |
+| `web` | `capsize_commons.web` | `fastapi` |
+| `http` | `capsize_commons.http` | none (stdlib only) |
+| `all` | every sub-package | above |
+
+`capsize_commons.text` and `capsize_commons.logging` are stdlib-only and ship
+with the base install.
+
+## Modules
+
+```python
+# Structured JSON logs matching §14
+from capsize_commons.logging import configure_logging
+configure_logging(json_mode=True, logger_name="myapp")
+
+# Env-backed settings, cached per class
+from capsize_commons.config import CapsizeSettings, get_settings
+class Settings(CapsizeSettings):
+    model_config = CapsizeSettings.model_config | {"env_prefix": "MYAPP_"}
+    database_url: str = "sqlite:///./app.db"
+
+# FastAPI auth + health
+from capsize_commons.web import make_api_key_dependency, install_health_routes
+
+# SQLAlchemy engine, sessions and the standard model mixin
+from capsize_commons.db import make_engine, make_session_factory, TimestampedBase
+
+# HTTP retry with backoff
+from capsize_commons.http import Backoff, retry_async
+
+# Naming (§3.1)
+from capsize_commons.text import slugify, to_snake_case
+```
+
+## Development
+
+```bash
+cd python
+uv sync --all-extras
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run mypy src
+```
+
+Or from the repository root: `just test`, `just lint`, `just typecheck`.

capsize_commons-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "capsize-commons"
+version = "0.1.0"
+description = "Selectively installable common building blocks shared across Capsize projects: structured logging, FastAPI auth/health, SQLAlchemy conventions, HTTP retry, and case conversion."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Capsize LLC", email = "contact@capsizegames.com" },
+]
+keywords = [
+    "capsize",
+    "commons",
+    "logging",
+    "fastapi",
+    "sqlalchemy",
+    "utilities",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+# The base distribution is deliberately dependency-free: every module that
+# needs a third-party package imports it lazily and is pulled in by an extra.
+dependencies = []
+
+[project.optional-dependencies]
+config = ["pydantic>=2.7", "pydantic-settings>=2.3"]
+db = ["sqlalchemy>=2.0.30"]
+web = ["fastapi>=0.115"]
+http = ["httpx>=0.27"]
+all = [
+    "pydantic>=2.7",
+    "pydantic-settings>=2.3",
+    "sqlalchemy>=2.0.30",
+    "fastapi>=0.115",
+    "httpx>=0.27",
+]
+dev = [
+    "pytest>=8.2",
+    "pytest-asyncio>=0.23",
+    "httpx>=0.27",
+    "ruff>=0.5",
+    "mypy>=1.10",
+    "pydantic>=2.7",
+    "pydantic-settings>=2.3",
+    "sqlalchemy>=2.0.30",
+    "fastapi>=0.115",
+]
+
+[project.urls]
+Homepage = "https://github.com/Capsize-Games/capsize-commons"
+Issues = "https://github.com/Capsize-Games/capsize-commons/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# The package is mypy --strict clean, so the marker is a claim it can keep.
+[tool.setuptools.package-data]
+capsize_commons = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

capsize_commons-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

capsize_commons-0.1.0/src/capsize_commons/__init__.py

@@ -0,0 +1,37 @@
+"""Generic, selectively-installable building blocks shared across Capsize.
+
+What this package deliberately does **not** do, because each one is what makes
+in-repo copies hard to consolidate:
+
+* **No application logic.** If a helper knows a domain noun, it belongs in the
+  project, not here.
+* **No required dependencies.** The base install is stdlib-only. Anything that
+  needs a third-party package lives in a sub-package behind an extra and
+  imports it lazily.
+* **No import-time side effects.** Importing a module never reads the
+  environment, opens a connection, or configures logging. You call
+  :func:`capsize_commons.logging.configure_logging` when you want it.
+* **No global mutable state** beyond explicitly cached, resettable settings.
+
+The sub-packages:
+
+``capsize_commons.logging``
+    Structured JSON logging with the §14 field set, reversible by design.
+``capsize_commons.config``
+    A ``pydantic-settings`` base plus a per-class cached accessor.
+``capsize_commons.db``
+    SQLAlchemy engine/session factories and the §6 model conventions
+    (time-ordered UUID keys, UTC timestamps).
+``capsize_commons.web``
+    FastAPI API-key auth and the ``/health`` + ``/ready`` routes.
+``capsize_commons.http``
+    Retry with exponential backoff, sync and async.
+``capsize_commons.text``
+    Case conversion for the fleet's naming rules (§3.1).
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

capsize_commons-0.1.0/src/capsize_commons/config/__init__.py

@@ -0,0 +1,14 @@
+"""Environment-backed settings conventions (§7).
+
+Requires the ``config`` extra (``pydantic`` + ``pydantic-settings``).
+"""
+
+from __future__ import annotations
+
+from capsize_commons.config.base import (
+    CapsizeSettings,
+    clear_settings_cache,
+    get_settings,
+)
+
+__all__ = ["CapsizeSettings", "clear_settings_cache", "get_settings"]

capsize_commons-0.1.0/src/capsize_commons/config/base.py

@@ -0,0 +1,46 @@
+"""A shared ``pydantic-settings`` base and a per-class cached accessor.
+
+Every FastAPI service in the fleet re-declared ``class Settings(BaseSettings)``
+plus a ``@lru_cache get_settings()``. The base here fixes the common
+conventions (``.env`` loading, unknown keys ignored) and the factory caches one
+instance per settings class, so tests can clear it in one call.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from typing import TypeVar
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+__all__ = ["CapsizeSettings", "clear_settings_cache", "get_settings"]
+
+_T = TypeVar("_T", bound=BaseSettings)
+
+
+class CapsizeSettings(BaseSettings):
+    """Base class for Capsize runtime settings.
+
+    Subclasses override ``model_config`` to set their own ``env_prefix``
+    (``CAPSIZE_`` by default). Real ``.env`` files stay gitignored; ship an
+    ``.env.example`` alongside them (§7).
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="CAPSIZE_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        case_sensitive=False,
+    )
+
+
+@cache
+def get_settings(settings_cls: type[_T]) -> _T:
+    """Return the process-wide, cached instance of ``settings_cls``."""
+    return settings_cls()
+
+
+def clear_settings_cache() -> None:
+    """Drop every cached settings instance (used by tests)."""
+    get_settings.cache_clear()

capsize_commons-0.1.0/src/capsize_commons/db/__init__.py

@@ -0,0 +1,25 @@
+"""SQLAlchemy engine, session and model conventions (§6).
+
+Requires the ``db`` extra (``sqlalchemy``).
+"""
+
+from __future__ import annotations
+
+from capsize_commons.db.base import (
+    Base,
+    TimestampedBase,
+    UtcDateTime,
+    utcnow,
+    uuid7,
+)
+from capsize_commons.db.engine import make_engine, make_session_factory
+
+__all__ = [
+    "Base",
+    "TimestampedBase",
+    "UtcDateTime",
+    "make_engine",
+    "make_session_factory",
+    "utcnow",
+    "uuid7",
+]

capsize_commons-0.1.0/src/capsize_commons/db/base.py

@@ -0,0 +1,95 @@
+"""SQLAlchemy model conventions from CAPSIZE_PROJECT_STANDARDS.md §6.
+
+Two things every model re-implemented, now shared:
+
+* :class:`UtcDateTime` — SQLite has no native timezone-aware storage, so the
+  stock ``DateTime`` reads back naive even when written aware. This reattaches
+  UTC on the way out and rejects naive values on the way in.
+* :class:`TimestampedBase` — the mandated ``id`` + ``created_at`` +
+  ``updated_at`` columns, with a time-ordered UUIDv7 primary key.
+"""
+
+from __future__ import annotations
+
+import datetime
+import os
+import time
+import uuid
+
+from sqlalchemy import DateTime, Uuid
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy.types import TypeDecorator
+
+__all__ = ["Base", "TimestampedBase", "UtcDateTime", "uuid7"]
+
+
+def uuid7() -> uuid.UUID:
+    """Return a time-ordered UUIDv7 (§6 primary-key preference).
+
+    Layout: 48-bit Unix milliseconds, 4-bit version, 12-bit ``rand_a``,
+    2-bit variant, 62-bit ``rand_b``.
+    """
+    milliseconds = int(time.time() * 1000) & ((1 << 48) - 1)
+    random_bits = int.from_bytes(os.urandom(10), "big") >> 6  # 74 random bits
+    rand_a = random_bits >> 62
+    rand_b = random_bits & ((1 << 62) - 1)
+    value = (
+        (milliseconds << 80)
+        | (0x7 << 76)
+        | (rand_a << 64)
+        | (0x2 << 62)
+        | rand_b
+    )
+    return uuid.UUID(int=value)
+
+
+def utcnow() -> datetime.datetime:
+    """Return the current time as a timezone-aware UTC ``datetime``."""
+    return datetime.datetime.now(datetime.UTC)
+
+
+class UtcDateTime(TypeDecorator[datetime.datetime]):
+    """A ``DateTime`` that round-trips as timezone-aware UTC through SQLite."""
+
+    impl = DateTime(timezone=True)
+    cache_ok = True
+
+    def process_bind_param(
+        self, value: datetime.datetime | None, dialect: object
+    ) -> datetime.datetime | None:
+        """Require and normalize an aware value on the way into storage."""
+        if value is None:
+            return None
+        if value.tzinfo is None:
+            raise ValueError("UtcDateTime requires a timezone-aware value")
+        return value.astimezone(datetime.UTC)
+
+    def process_result_value(
+        self, value: datetime.datetime | None, dialect: object
+    ) -> datetime.datetime | None:
+        """Reattach UTC to a value SQLite returned as naive."""
+        if value is None:
+            return None
+        if value.tzinfo is None:
+            return value.replace(tzinfo=datetime.UTC)
+        return value.astimezone(datetime.UTC)
+
+
+class Base(DeclarativeBase):
+    """Declarative base for every Capsize SQLAlchemy model."""
+
+
+class TimestampedBase(Base):
+    """Abstract base adding the standard ``id`` and UTC timestamps (§6)."""
+
+    __abstract__ = True
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        Uuid, primary_key=True, default=uuid7
+    )
+    created_at: Mapped[datetime.datetime] = mapped_column(
+        UtcDateTime, default=utcnow
+    )
+    updated_at: Mapped[datetime.datetime] = mapped_column(
+        UtcDateTime, default=utcnow, onupdate=utcnow
+    )

capsize_commons-0.1.0/src/capsize_commons/db/engine.py

@@ -0,0 +1,60 @@
+"""SQLAlchemy engine and session factories.
+
+Consolidates the per-project ``make_engine`` / ``make_session_factory`` pair.
+The SQLite branch is the part every copy got subtly wrong or left out: it
+disables the thread check (so a single file-backed database can be shared) and
+turns on ``PRAGMA foreign_keys`` (which SQLite leaves off by default, so every
+``ON DELETE CASCADE`` in a project silently did nothing).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import Engine, create_engine, event
+from sqlalchemy.orm import Session, sessionmaker
+
+__all__ = ["make_engine", "make_session_factory"]
+
+
+def make_engine(
+    database_url: str,
+    *,
+    echo: bool = False,
+    pool_pre_ping: bool = True,
+    **engine_kwargs: Any,
+) -> Engine:
+    """Create an :class:`Engine`, applying SQLite-safe defaults.
+
+    ``pool_pre_ping`` defaults to ``True`` so a pooled connection that a
+    database or proxy has since dropped is detected and replaced (standards
+    §6: pooling must be explicit, never unbounded).
+    """
+    connect_args: dict[str, Any] = {}
+    if database_url.startswith("sqlite"):
+        connect_args["check_same_thread"] = False
+    engine = create_engine(
+        database_url,
+        echo=echo,
+        pool_pre_ping=pool_pre_ping,
+        connect_args=connect_args,
+        **engine_kwargs,
+    )
+    if database_url.startswith("sqlite"):
+        _enable_sqlite_foreign_keys(engine)
+    return engine
+
+
+def _enable_sqlite_foreign_keys(engine: Engine) -> None:
+    """Turn on foreign-key enforcement for every SQLite connection."""
+
+    @event.listens_for(engine, "connect")
+    def _on_connect(dbapi_connection: Any, _record: Any) -> None:
+        cursor = dbapi_connection.cursor()
+        cursor.execute("PRAGMA foreign_keys=ON")
+        cursor.close()
+
+
+def make_session_factory(engine: Engine) -> sessionmaker[Session]:
+    """Return a session factory with the fleet's standard flags."""
+    return sessionmaker(bind=engine, autoflush=False, expire_on_commit=False)

capsize_commons-0.1.0/src/capsize_commons/http/__init__.py

@@ -0,0 +1,10 @@
+"""HTTP helpers: retry with exponential backoff.
+
+Stdlib-only: part of the base install.
+"""
+
+from __future__ import annotations
+
+from capsize_commons.http.retry import Backoff, retry_async, retry_sync
+
+__all__ = ["Backoff", "retry_async", "retry_sync"]

capsize_commons-0.1.0/src/capsize_commons/http/retry.py

@@ -0,0 +1,97 @@
+"""Retry helpers with exponential backoff and jitter.
+
+Stdlib-only. Callers supply the operation as a zero-argument callable and the
+sleep function, which is what makes these testable without real delays and
+usable from both sync and async code.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TypeVar
+
+__all__ = ["Backoff", "retry_async", "retry_sync"]
+
+_T = TypeVar("_T")
+
+
+@dataclass(frozen=True)
+class Backoff:
+    """Retry tuning: attempt count and the delay curve between attempts."""
+
+    attempts: int = 3
+    base_delay: float = 0.1
+    max_delay: float = 5.0
+    factor: float = 2.0
+    jitter: bool = True
+    retry_on: tuple[type[BaseException], ...] = (Exception,)
+
+    def delay_for(self, attempt: int, rng: random.Random) -> float:
+        """Return the delay to wait before retrying zero-based ``attempt``.
+
+        With ``jitter`` enabled the delay is drawn uniformly from
+        ``[0, raw]``, which spreads out retries from many clients instead of
+        letting them all return at the same instant.
+        """
+        raw = min(self.base_delay * (self.factor**attempt), self.max_delay)
+        if self.jitter:
+            return rng.uniform(0.0, raw)
+        return raw
+
+
+def retry_sync(
+    func: Callable[[], _T],
+    *,
+    backoff: Backoff | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    rng: random.Random | None = None,
+) -> _T:
+    """Call ``func`` until it returns, retrying the configured exceptions.
+
+    Re-raises the final exception once attempts are exhausted.
+    """
+    config = backoff or Backoff()
+    generator = rng or random.Random()
+    last_error: BaseException | None = None
+    for attempt in range(config.attempts):
+        try:
+            return func()
+        except config.retry_on as error:
+            last_error = error
+            if attempt == config.attempts - 1:
+                break
+            sleep(config.delay_for(attempt, generator))
+    if last_error is None:  # pragma: no cover - only when attempts < 1
+        raise ValueError("Backoff.attempts must be at least 1")
+    raise last_error
+
+
+async def retry_async(
+    func: Callable[[], Awaitable[_T]],
+    *,
+    backoff: Backoff | None = None,
+    sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+    rng: random.Random | None = None,
+) -> _T:
+    """Await ``func`` until it returns, retrying the configured exceptions.
+
+    Re-raises the final exception once attempts are exhausted.
+    """
+    config = backoff or Backoff()
+    generator = rng or random.Random()
+    last_error: BaseException | None = None
+    for attempt in range(config.attempts):
+        try:
+            return await func()
+        except config.retry_on as error:
+            last_error = error
+            if attempt == config.attempts - 1:
+                break
+            await sleep(config.delay_for(attempt, generator))
+    if last_error is None:  # pragma: no cover - only when attempts < 1
+        raise ValueError("Backoff.attempts must be at least 1")
+    raise last_error

capsize_commons-0.1.0/src/capsize_commons/logging/__init__.py

@@ -0,0 +1,24 @@
+"""Structured JSON logging that matches CAPSIZE_PROJECT_STANDARDS.md §14.
+
+Stdlib-only: part of the base install.
+"""
+
+from __future__ import annotations
+
+from capsize_commons.logging.json_formatter import JsonFormatter
+from capsize_commons.logging.setup import (
+    DEFAULT_LEVEL,
+    DEFAULT_LOGGER_NAME,
+    configure_logging,
+    logging_enabled,
+    reset_logging,
+)
+
+__all__ = [
+    "DEFAULT_LEVEL",
+    "DEFAULT_LOGGER_NAME",
+    "JsonFormatter",
+    "configure_logging",
+    "logging_enabled",
+    "reset_logging",
+]