capsize-commons 0.1.0__py3-none-any.whl

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/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/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/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/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/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/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/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/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",
+]

capsize_commons/logging/json_formatter.py

@@ -0,0 +1,55 @@
+"""The §14 JSON log shape, in one place.
+
+Standards §14 requires structured JSON on stdout with at least ``timestamp``,
+``level``, ``logger`` and ``message``. This module has no dependency beyond the
+standard library and no import-time side effects.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from typing import Any
+
+__all__ = ["JsonFormatter"]
+
+#: Optional correlation fields copied onto the record when present.
+_IDENTIFIER_FIELDS = ("service", "request_id", "trace_id", "span_id", "event")
+
+
+class JsonFormatter(logging.Formatter):
+    """Render a log record as one compact JSON object on a single line."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Return ``record`` serialized as a JSON line."""
+        return json.dumps(
+            self.build_payload(record), default=str, ensure_ascii=False
+        )
+
+    def build_payload(self, record: logging.LogRecord) -> dict[str, Any]:
+        """Return the standards-shaped mapping for ``record``.
+
+        The base fields are always present; correlation fields are added only
+        when the caller supplied them via ``extra=``. An optional ``fields``
+        mapping is nested under ``"fields"`` rather than spread into the
+        payload, so a field can never overwrite a base field.
+        """
+        created = datetime.fromtimestamp(record.created, UTC)
+        payload: dict[str, Any] = {
+            "timestamp": created.isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        for name in _IDENTIFIER_FIELDS:
+            value = getattr(record, name, None)
+            if value is not None:
+                payload[name] = value
+        fields = getattr(record, "fields", None)
+        if isinstance(fields, Mapping):
+            payload["fields"] = dict(fields)
+        if record.exc_info is not None:
+            payload["exception"] = self.formatException(record.exc_info)
+        return payload

capsize_commons/logging/setup.py

@@ -0,0 +1,122 @@
+"""Opt-in, reversible structured logging.
+
+Nothing here runs at import time and no entry point *must* call it, so a
+library consumer's default logging behaviour is untouched. Call
+:func:`configure_logging` to attach one handler to a named logger (never the
+root logger) and :func:`reset_logging` to restore the exact prior state — which
+is what makes this safe to use in tests.
+
+``SPIKEFORGE_LOG_JSON`` / ``SPIKEFORGE_LOG_LEVEL`` and their copies across the
+fleet become one implementation with a configurable prefix; the default prefix
+here is ``CAPSIZE``.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Final, TextIO
+
+from capsize_commons.logging.json_formatter import JsonFormatter
+
+__all__ = [
+    "DEFAULT_LEVEL",
+    "DEFAULT_LOGGER_NAME",
+    "configure_logging",
+    "logging_enabled",
+    "reset_logging",
+]
+
+#: Logger structured logging attaches to when no name is given.
+DEFAULT_LOGGER_NAME: Final = "capsize"
+#: Level used when neither the argument nor the environment supplies one.
+DEFAULT_LEVEL: Final = "INFO"
+#: Human-readable format used when JSON output is not requested.
+HUMAN_FORMAT: Final = "%(asctime)s %(levelname)s %(name)s %(message)s"
+
+_FALSEY: Final = ("", "0", "false", "no", "off")
+
+# logger name -> (installed handler, previous level, previous propagate)
+_installed: dict[str, tuple[logging.Handler, int, bool]] = {}
+
+
+def _truthy(value: str | None) -> bool:
+    """Return ``True`` when an environment flag is set to a truthy value."""
+    return value is not None and value.strip().lower() not in _FALSEY
+
+
+def _env_names(prefix: str) -> tuple[str, str]:
+    """Return the ``(json_var, level_var)`` names for ``prefix``."""
+    return f"{prefix}_LOG_JSON", f"{prefix}_LOG_LEVEL"
+
+
+def logging_enabled(prefix: str = "CAPSIZE") -> bool:
+    """Return ``True`` when the environment asks for logging to be set up."""
+    json_var, level_var = _env_names(prefix)
+    return _truthy(os.environ.get(json_var)) or bool(os.environ.get(level_var))
+
+
+def _resolve_level(name: str | None, level_var: str) -> int:
+    """Resolve a level from the argument, the environment, or the default."""
+    resolved = name or os.environ.get(level_var) or DEFAULT_LEVEL
+    candidate = getattr(logging, str(resolved).upper(), None)
+    return candidate if isinstance(candidate, int) else logging.INFO
+
+
+def _resolve_json(json_mode: bool | None, json_var: str) -> bool:
+    """Resolve the JSON decision from the argument or the environment."""
+    if json_mode is not None:
+        return json_mode
+    return _truthy(os.environ.get(json_var))
+
+
+def _build_handler(use_json: bool, stream: TextIO | None) -> logging.Handler:
+    """Return a stream handler carrying the JSON or human formatter."""
+    handler = logging.StreamHandler(stream)
+    formatter: logging.Formatter = (
+        JsonFormatter() if use_json else logging.Formatter(HUMAN_FORMAT)
+    )
+    handler.setFormatter(formatter)
+    return handler
+
+
+def configure_logging(
+    level: str | None = None,
+    json_mode: bool | None = None,
+    *,
+    force: bool = False,
+    stream: TextIO | None = None,
+    logger_name: str = DEFAULT_LOGGER_NAME,
+    env_prefix: str = "CAPSIZE",
+) -> logging.Handler | None:
+    """Attach the opt-in handler, or return ``None`` when logging is disabled.
+
+    ``level`` / ``json_mode`` override ``<prefix>_LOG_LEVEL`` /
+    ``<prefix>_LOG_JSON``. ``force`` configures even when no environment
+    variable is set, and ``stream`` redirects output (used by tests). Repeating
+    the call is safe: any previously installed handler is removed first.
+    """
+    json_var, level_var = _env_names(env_prefix)
+    if not force and not logging_enabled(env_prefix):
+        return None
+    reset_logging(logger_name)
+    logger = logging.getLogger(logger_name)
+    handler = _build_handler(_resolve_json(json_mode, json_var), stream)
+    _installed[logger_name] = (handler, logger.level, logger.propagate)
+    logger.addHandler(handler)
+    logger.setLevel(_resolve_level(level, level_var))
+    logger.propagate = False
+    return handler
+
+
+def reset_logging(logger_name: str = DEFAULT_LOGGER_NAME) -> None:
+    """Remove the installed handler and restore the previous logger state."""
+    saved: Any = _installed.pop(logger_name, None)
+    if saved is None:
+        return
+    handler, level, propagate = saved
+    logger = logging.getLogger(logger_name)
+    logger.removeHandler(handler)
+    handler.close()
+    logger.setLevel(level)
+    logger.propagate = propagate

capsize_commons/py.typed

@@ -0,0 +1 @@
+# Marker file: this package ships inline type information (PEP 561).

capsize_commons/sentinel.py

@@ -0,0 +1,35 @@
+"""A single shared ``UNSET`` sentinel.
+
+Projects keep re-declaring ``_UNSET = object()`` so that ``None`` can be a
+legitimate value distinct from "not supplied". This gives that sentinel one
+identity across the fleet.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+__all__ = ["UNSET", "is_unset"]
+
+
+class _Unset:
+    """The type of :data:`UNSET`. Instantiate only through the singleton."""
+
+    __slots__ = ()
+
+    def __bool__(self) -> bool:
+        """Return ``False`` so ``if not value`` reads as "nothing given"."""
+        return False
+
+    def __repr__(self) -> str:
+        """Return a stable, unambiguous spelling."""
+        return "UNSET"
+
+
+#: Sentinel for "no value was supplied", distinct from ``None``.
+UNSET: Final[_Unset] = _Unset()
+
+
+def is_unset(value: object) -> bool:
+    """Return ``True`` when ``value`` is the shared :data:`UNSET` sentinel."""
+    return value is UNSET

capsize_commons/text/__init__.py

@@ -0,0 +1,12 @@
+"""Text and naming helpers that implement the fleet's casing rules (§3.1)."""
+
+from __future__ import annotations
+
+from capsize_commons.text.case import (
+    slugify,
+    to_kebab_case,
+    to_pascal_case,
+    to_snake_case,
+)
+
+__all__ = ["slugify", "to_kebab_case", "to_pascal_case", "to_snake_case"]

capsize_commons/text/case.py

@@ -0,0 +1,62 @@
+"""Case conversion for repository, file and symbol naming (§3.1).
+
+Repos and files are ``kebab-case``, Python symbols ``snake_case`` and classes
+``PascalCase``. Every project was writing a slightly different ``slugify``;
+this is the one they share.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+__all__ = ["slugify", "to_kebab_case", "to_pascal_case", "to_snake_case"]
+
+#: Split on any run of characters that are not alphanumerics.
+_SEPARATORS = re.compile(r"[^0-9A-Za-z]+")
+#: Split camelCase / PascalCase / HTTPServer at the correct boundaries.
+_CAMEL_BOUNDARY = re.compile(
+    r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])"
+)
+
+
+def _to_ascii(text: str) -> str:
+    """Fold accents to their closest ASCII spelling."""
+    decomposed = unicodedata.normalize("NFKD", text)
+    return decomposed.encode("ascii", "ignore").decode("ascii")
+
+
+def _words(value: str) -> list[str]:
+    """Split ``value`` into its alphanumeric words, accents folded."""
+    spaced = _CAMEL_BOUNDARY.sub(" ", _to_ascii(value).strip())
+    return [word for word in _SEPARATORS.split(spaced) if word]
+
+
+def slugify(
+    value: str, *, separator: str = "-", lowercase: bool = True
+) -> str:
+    """Join the words of ``value`` with ``separator``.
+
+    >>> slugify("Capsize Persona!")\
+    # doctest: +SKIP
+    'capsize-persona'
+    """
+    words = _words(value)
+    if lowercase:
+        words = [word.lower() for word in words]
+    return separator.join(words)
+
+
+def to_kebab_case(value: str) -> str:
+    """Return ``value`` as ``kebab-case`` (the repo/file convention)."""
+    return slugify(value, separator="-")
+
+
+def to_snake_case(value: str) -> str:
+    """Return ``value`` as ``snake_case`` (the Python symbol convention)."""
+    return slugify(value, separator="_")
+
+
+def to_pascal_case(value: str) -> str:
+    """Return ``value`` as ``PascalCase`` (the class convention)."""
+    return "".join(word.capitalize() for word in _words(value))

capsize_commons/web/__init__.py

@@ -0,0 +1,16 @@
+"""FastAPI integration helpers: API-key auth (§13) and health routes (§14).
+
+Requires the ``web`` extra (``fastapi``).
+"""
+
+from __future__ import annotations
+
+from capsize_commons.web.auth import check_api_key, make_api_key_dependency
+from capsize_commons.web.health import health_router, install_health_routes
+
+__all__ = [
+    "check_api_key",
+    "health_router",
+    "install_health_routes",
+    "make_api_key_dependency",
+]

capsize_commons/web/auth.py

@@ -0,0 +1,55 @@
+"""Shared-secret API-key authentication for service-to-service calls (§13).
+
+``capsize-social`` and ``capsize-persona`` carried byte-identical copies of
+``require_api_key``. This generalizes that function into a dependency factory
+whose expected key is read lazily, so it can pull from settings or a secret
+store without this module knowing which.
+
+The security-relevant behaviours are preserved deliberately:
+
+* an **empty** expected key rejects every request (fail closed — a service
+  started without configuration must not be wide open);
+* comparison uses :func:`secrets.compare_digest`, so a wrong key cannot be
+  recovered by timing.
+"""
+
+from __future__ import annotations
+
+import secrets
+from collections.abc import Callable
+
+from fastapi import Header, HTTPException, status
+
+__all__ = ["check_api_key", "make_api_key_dependency"]
+
+
+def check_api_key(provided: str, expected: str) -> bool:
+    """Return ``True`` when ``provided`` matches a non-empty ``expected``."""
+    if not expected:
+        return False
+    return secrets.compare_digest(provided, expected)
+
+
+def make_api_key_dependency(
+    expected_key: Callable[[], str],
+    *,
+    header_name: str = "X-API-Key",
+) -> Callable[..., None]:
+    """Build a FastAPI dependency enforcing the shared API key.
+
+    ``expected_key`` is called per request so the value can come from mutable
+    or reloadable configuration. Raises ``401`` on any mismatch.
+    """
+
+    def require_api_key(
+        x_api_key: str = Header(default="", alias=header_name),
+    ) -> None:
+        """Reject the request unless the presented key matches."""
+        if not check_api_key(x_api_key, expected_key()):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid or missing API key",
+                headers={"WWW-Authenticate": "ApiKey"},
+            )
+
+    return require_api_key

capsize_commons/web/health.py

@@ -0,0 +1,55 @@
+"""Liveness and readiness routes (§14).
+
+Every service in the fleet hand-rolled ``GET /health``. This adds the
+``GET /ready`` counterpart §14 also requires, with an optional readiness
+predicate so a service can report "up but not able to serve" (for example,
+still loading a model or warming a pool) as ``503``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from enum import Enum
+
+from fastapi import APIRouter, FastAPI, HTTPException, status
+
+__all__ = ["health_router", "install_health_routes"]
+
+
+def health_router(
+    *,
+    ready_check: Callable[[], bool] | None = None,
+    tags: Sequence[str | Enum] | None = None,
+) -> APIRouter:
+    """Return a router exposing ``/health`` and ``/ready``.
+
+    When ``ready_check`` is given and returns ``False``, ``/ready`` responds
+    ``503`` so an orchestrator stops routing traffic to the instance.
+    """
+    router = APIRouter(tags=None if tags is None else list(tags))
+
+    @router.get("/health")
+    def health() -> dict[str, str]:
+        """Report liveness (the process is running)."""
+        return {"status": "ok"}
+
+    @router.get("/ready")
+    def ready() -> dict[str, str]:
+        """Report readiness, consulting ``ready_check`` when supplied."""
+        if ready_check is not None and not ready_check():
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail="Not ready",
+            )
+        return {"status": "ready"}
+
+    return router
+
+
+def install_health_routes(
+    app: FastAPI,
+    *,
+    ready_check: Callable[[], bool] | None = None,
+) -> None:
+    """Include the health router on ``app`` at the root path."""
+    app.include_router(health_router(ready_check=ready_check))

capsize_commons-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,22 @@
+capsize_commons/__init__.py,sha256=J1k5q_S1QgNGtxfiZXZWxKuZG82FaPitjhF5SrNnqJY,1445
+capsize_commons/py.typed,sha256=3CM6tLfKmfP9zl61YavKQobU_0-it54Wf_P7oI9ttmU,69
+capsize_commons/sentinel.py,sha256=I5KGycT5eKbe4i6a6df4l-nMy3i9CsYMBc12ek40amI,912
+capsize_commons/config/__init__.py,sha256=Zu3-qyoNQzkHZvK1Yqs2LjPe_-p_-xVDXv7lUgcNs18,342
+capsize_commons/config/base.py,sha256=QgU979ZMEzQcJoXIO8CdRm6W4sPYLYo8D5ayphZaYJo,1403
+capsize_commons/db/__init__.py,sha256=XfgYul2kZQkErfNZDVrgtft0Y4qpXcDiChGmgNkbloM,471
+capsize_commons/db/base.py,sha256=BhqeNm1NuYnDSON49beZfWoIdBWQh7zu9xOJ5bAND1o,3048
+capsize_commons/db/engine.py,sha256=arjNsgv66Zsoa0TjxnLuq4y7Lx_VdN-bRb-UQ1QMiaU,2025
+capsize_commons/http/__init__.py,sha256=o844E7yAK8AB2DP1nCDUIwDaIbV9DDHGYgtPyZjGckc,254
+capsize_commons/http/retry.py,sha256=ebFflmmJG0Eo2Mu8y0bVMhDgnlmk9u68Va7sBNXz_qw,3142
+capsize_commons/logging/__init__.py,sha256=u-zdZdiywOdoxz3Js_pBW-0piOUFyyx65IyE-bvE0_A,527
+capsize_commons/logging/json_formatter.py,sha256=wWZ_YpcvlFEpF5sBZj55kfiD7MRwqH0LeIzhlxhXKhk,2076
+capsize_commons/logging/setup.py,sha256=yonyQbuixG1iiProW4PxYzJecleJCOGtZCT8KUHjU0Y,4508
+capsize_commons/text/__init__.py,sha256=BLJXo0BlUXFWrWlsD96n-AN7czcJKSyTYKAFCl3yn6s,304
+capsize_commons/text/case.py,sha256=BhB1H14oReg2RPUghsPgHAPT-_AcFtDqkNj7--HGLVc,1951
+capsize_commons/web/__init__.py,sha256=FGhpwkbttKQbQWKVezOZCxnkNPvZL6fCN4crJavAREw,431
+capsize_commons/web/auth.py,sha256=kqkLB_fswz1BWrJyHjqVkJR5ti9DOIxA39rtA5HH8nc,1900
+capsize_commons/web/health.py,sha256=CidKxOIKGemmzJH9trz7WTp_m1AlUDnOm1gNo4DdKNQ,1756
+capsize_commons-0.1.0.dist-info/METADATA,sha256=Sp0nX1iZPlUUEgwzmrGNItzet6w0ATj2cNHASEhBA5g,3734
+capsize_commons-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+capsize_commons-0.1.0.dist-info/top_level.txt,sha256=h-Tcw-VCV-tS5L7Rni6ekVupGFyuCtpvHaZqDe2YQE8,16
+capsize_commons-0.1.0.dist-info/RECORD,,

capsize_commons-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

capsize_commons-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+capsize_commons