Metadata-Version: 2.4
Name: capsize-commons
Version: 0.1.2
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`.
