core-framework 2.2.0

Core framework package (import as core_framework)

Core framework

Install from PyPI as core-framework, import core_framework. MIT — LICENSE. Repository, PyPI.

Install

uv add core-framework

Local development

Use Python 3.14. Install uv and Docker.

docker compose -f docker-compose.dev.yaml up -d
uv sync --locked --all-extras --dev
uv run cf-alembic
make run

Firebase: copy firebase_config.example.json to firebase_config.json at the repo root and replace with your Firebase project’s service account JSON from the console.

For make test, use the Firebase CLI (Auth emulator). Stop DB/Redis: docker compose -f docker-compose.dev.yaml down.

Hosts

In your host app, load Settings or a Settings subclass from core_framework.core.settings, pass it to init_app from core_framework.main, then wire host-specific dependencies, exception handlers, and routers.

from core_framework.main import init_app
from fastapi import FastAPI

from myapp.settings import HostSettings, load_default_settings


def build_app(settings: HostSettings | None = None) -> FastAPI:
    resolved = settings if settings is not None else load_default_settings()
    app = init_app(resolved)

    from myapp.bootstrap import configure_dependencies
    from myapp.exception_handlers import setup_exception_handlers

    configure_dependencies(runtime=app.state.core_runtime)
    setup_exception_handlers(app)

    from myapp.api.router import router

    app.include_router(router)
    return app

From the host repository root, run uv run cf-alembic. See core-framework-migration.

Host pytest

In your host repository, add the core-framework[testing] extra to dev or test dependencies. In tests/conftest.py, register pytest_core_framework_config (returns TestConfig) and a session-scoped anyio_backend fixture that returns "asyncio".

import pytest

from core_framework.testing import TestConfig

from myapp.settings import load_default_settings


def pytest_core_framework_config() -> TestConfig:
    from myapp.main import build_app

    return TestConfig(
        settings_loader=load_default_settings,
        app_factory=build_app,
    )


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

See Package API — Testing and testing plugin design.