HexCore

A reusable core for Python applications built on hexagonal architecture, DDD, CQRS and background tasks. HexCore ships the abstractions (entities, repositories, unit of work, buses) and the infrastructure every project otherwise rewrites: the SQL session layer, the FastAPI factories, the worker runner, the dynamic cron, identity, and the testing utilities.

The design goal is that the happy path takes zero configuration: create_app() with no arguments gives you a usable app, init_engine() with no arguments gives you a production-correct engine.

🇪🇸 ¿Preferís español? La documentación está completa en los dos idiomas: docs/es/.

# main.py — a complete HexCore app
from hexcore.fastapi import build_lifespan, create_app, SqlEngineStep

app = create_app(
    lifespan=build_lifespan(SqlEngineStep()),
    routers=[users_router, tickets_router],
)

# worker.py — the complete worker, with cron, mutual death and SIGTERM
import hexcore.cqrs as cqrs

await cqrs.run_procrastinate_worker(
    procrastinate_app,
    queues=["default", "reactive"],
    scheduler=cqrs.DynamicScheduler(repo, enqueuer, lock_provider=lock),
    on_startup=[lambda: cqrs.seed_cron_jobs(CRON_JOBS)],
)

📚 Documentation

→ docs/ — 🇬🇧 English · 🇪🇸 español

Installation

pip install hexcore

Requires Python ≥ 3.12. HexCore pulls in no heavy dependencies: everything that is not the core lives in extras, and the modules that need them only import them when you use them.

pip install "hexcore[api,sql,procrastinate]"
pip install "hexcore[darwin-sqlalchemy]"
pip install "hexcore[all]"

The full table, with what each one enables, is in installation · instalación.

import hexcore.cqrs works with no extras at all: name resolution is lazy, so hexcore.cqrs.SqlAlchemyCronJobRepository only requires [sql] at the moment you ask for it.

The four imports

There is one facade module per task. They re-export the public surface without moving anything: the long paths keep resolving to the same object.

import hexcore.fastapi as hx     # create_app, build_lifespan, providers, middlewares, health
import hexcore.cqrs as cqrs      # Command, Query, handlers, decorators, buses, worker, cron
import hexcore.sql as sql        # init_engine, session_scope, uow_scope, Base, query DTOs
import hexcore.darwin as darwin  # IdentityConfig, configure_identity, build_identity_router

The facades expose only the canonical names. The historical I* aliases were removed in 7.0 — see Removed API.

What you get, at a glance

Darwin: the identity module

Registration, email verification, sign-in, sessions with rotating refresh, revocation, audited impersonation, and a plugin system that adds second factor, OAuth, magic links, passkeys and organizations without the core knowing about them.

from hexcore.darwin import (
    IdentityConfig,
    build_identity_router,
    configure_identity,
    identity_startup_steps,
)
from hexcore.fastapi import AppFeatures, SqlEngineStep, build_lifespan, create_app

configure_identity(IdentityConfig())

app = create_app(
    features=AppFeatures(auth_context=True, csrf=True),
    lifespan=build_lifespan(SqlEngineStep(), *identity_startup_steps()),
    routers=[build_identity_router()],
)

⚠️ If you use SQL, the most important thing to read before deploying is the Alembic section: storage · almacenamiento. A plugin missing from your env.py makes alembic revision --autogenerate emit op.drop_table for its tables.

Project templates (CLI)

hexcore init my_project --template hexagonal
hexcore init my_project --template vertical-slice

• hexagonal → src/domain, src/application, src/infrastructure.
• vertical-slice → src/features, src/shared/{domain,application,infrastructure}.

Both generate a root config.py and leave Alembic configured. See CLI · CLI.

Versions and support

Everything before 9.0 is deprecated. Migrate to 9.x. The detail of each series, the silent 2.x bugs and the step-by-step guides are in versions and migration · versiones y migración.

Removed API and its replacement

The v1/v2 aliases were deprecated since 5.0 — two full majors of notice — and were removed in 7.0. The replacement is mechanical: they are renames, not behavior changes.

Passing event_dispatcher= to ServerConfig fails with an error that says what to use, rather than being silently ignored: pydantic discards keyword arguments it does not know, and keeping the default bus without noticing would surface much later as "my events never arrive".

If you are still on 6.x, run your tests with warnings visible to see what you have left to migrate:

python -m pytest -W "default::DeprecationWarning"

Contributing

1. Code of conduct — read the Code of Conduct before interacting.

2. Branches — fork and create a branch (feat/name, fix/name, docs/name).

3. Tests — every fix lands with at least one test that fails before and passes after:

   uv sync --extra all --group dev
   uv run python -m pytest -q
   

   CI fails if any test is skipped: a skip means an extra is missing, and we would be reporting green without having run half the suite.

4. Typecheck — uv run pyright hexcore. The verdict comes from the ratchet, not the exit code: see typing · tipado.

5. Style — PEP8. Comment the why, not the what.

6. Commits — Commitizen: feat:, fix:, docs:, refactor:, and ! for breaking changes. The version bump and the CHANGELOG are automatic on merge to master.

7. PRs — describe the problem, the reproduction, the solution and why that option.

Full detail in CONTRIBUTING.md.

Project skills

There is a set of skills for extending HexCore in VS Code and compatible environments: HexCore Skills repository.

References

• docs/ — the complete documentation, in English and Spanish.
• docs/ARCHITECTURE_TYPING.md — type system and stubs.
• CHANGELOG.md — change history.
• CONTRIBUTING.md — collaboration guidelines.
• SECURITY.md — security policy.