core-framework 1.2.0

Core framework package (import as core_framework)

Core framework

Reusable backend core published as the Python distribution core-framework (pyproject.toml). Import the implementation as core_framework (see Core framework migration, Package API, and CHANGELOG for version history).

Repository: github.com/NepNepFFXIV/core-framework

License: MIT — see LICENSE.

Install

Pin core-framework from Git (use a tag or commit for reproducible builds):

uv add "core-framework @ git+https://github.com/NepNepFFXIV/core-framework.git@v1.2.0"

pip install "core-framework @ git+https://github.com/NepNepFFXIV/core-framework.git@v1.2.0"

After it resolves, load Settings, call init_app(settings) from core_framework.main in your app factory, and apply bundled core schema from the host project root with uv run cf-alembic (see Host integration and Package API).

To hack on this repo: clone it, run uv sync (or pip install -e .), keep a local config.toml, run uv run cf-alembic, then make run or serve core_framework.asgi:app.

Host integration

Hosts depend on core-framework, own config and the DB, and import core_framework. Details: Core framework migration.

1. Dependency — Pin core-framework (path, Git tag, or index) and lock deploys (uv.lock, etc.).
2. Settings — Use Settings from core_framework.core.settings. Default loading uses config.toml and environment variables; env wins over TOML for the same field (see Architecture decisions). Subclass only if you need extra host-only fields; otherwise Settings() / model_validate is enough. Subclasses may need model_config tweaks (e.g. toml_file) if paths differ.
3. App — Call init_app(settings) from core_framework.main inside the host’s own main.py (or app factory). Importing core_framework.main has no side effects; only init_app(settings) runs the bootstrap. Do not import core_framework.asgi — that module exists so fastapi dev / uvicorn can serve the library’s own default-settings app standalone, and it eagerly loads core-framework’s own config.toml at import time. Do not mount router alone without the same bootstrap — see Package API.
4. Database — Apply core schema from the host root (where config.toml loads): uv run cf-alembic. Host-only tables: host migrations; order with core (Database and Alembic).
5. Worker — WorkerSettings class in core_framework.worker.main (run with arq core_framework.worker.main.WorkerSettings). Bootstrap (configure_application_dependencies, pool connects, init_cashews_backend) runs in on_startup, not at import time. ARQ exposes ctx["redis"] for enqueue in cron handlers; CoreRuntime.redis_queue is a separate connected pool for runtime parity with the API — see Architecture — ARQ and CoreRuntime queue clients.
6. API surface — Only Package API imports are stable; see CHANGELOG.
7. Upgrading / new Settings fields — When you bump core-framework, read CHANGELOG for that release (and any required migration notes). New Settings keys are announced there: required keys must be added to the host’s config.toml / env before deploy; optional keys list defaults. Version bumps follow SemVer in pyproject.toml so hosts can judge impact.

Testing in host projects

Use the core-framework[testing] optional extra in the host’s dev or test dependency group so pytest gets testcontainers, pytest-xdist, asgi-lifespan, and a compatible pytest. The package registers a pytest plugin automatically; you do not need pytest_plugins = (...) for core_framework.testing.

1. Add the extra (example with uv): in pyproject.toml, e.g. core-framework = { path = "…", extras = ["testing"] } or core-framework[testing] in [dependency-groups].dev.
2. In the host’s root tests/conftest.py, implement pytest_core_framework_config() returning TestConfig from core_framework.testing — pass settings_loader and app_factory (usually your load_default_settings and init_app). Optionally set alembic_root, firebase_project_id, include_arq_fixtures, etc.
3. In the same conftest.py, define a session-scoped anyio_backend fixture that returns "asyncio" (required so session-scoped async fixtures work with anyio’s pytest integration).

Minimal shape (adjust paths and flags to your host):

from pathlib import Path

import pytest

from core_framework.testing import TestConfig
from my_host.settings import load_default_settings
from my_host.main import init_app


def pytest_core_framework_config() -> TestConfig:
    return TestConfig(
        settings_loader=load_default_settings,
        app_factory=init_app,
        # alembic_root=Path(__file__).resolve().parent.parent / "alembic",
        # firebase_project_id="test",
        # include_arq_fixtures=False,
    )


@pytest.fixture(scope="session")
def anyio_backend() -> str:
    return "asyncio"

Stable API and fixture list: Package API — Testing. Design notes (xdist, Firebase hybrid, risks): Testing plugin design.

Commands

• make run — run the standalone core app locally.
• make alembic — run bundled core migrations via cf-alembic.
• make ruff — lint and format.
• make ty — type check.
• make vulture — scan for unused code.
• make test — run tests with the Firebase auth emulator.

Adding Domains

For a new core domain with its own schema name, use .cursor/skills/add-domain/SKILL.md. The initial scaffold creates settings, an empty Alembic tree, domain class shells, and bootstrap wiring; migration revisions and ALEMBIC_DOMAINS are added later with real DDL.

TODO

• ETag
• py-spy
• Stale-while-revalidate
• Backpressure - uvicorn settings https://uvicorn.dev/settings/
• Backpressure - route level with semaphore
• https://github.com/rennf93/fastapi-guard
• https://github.com/TypeError/secure
• Outbox pattern