Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Indroic/HexCore/llms.txt

Use this file to discover all available pages before exploring further.

HexCore is published on PyPI as hexcore and requires Python 3.12 or later. The core package ships with Pydantic v2, Typer, and croniter — everything needed to define entities, run the CQRS buses in memory, and use the CLI. All database drivers, API frameworks, and message-queue clients are optional extras so that your production image only carries what it actually needs.

​
Core install

pip install hexcore
The core package alone gives you:
  • BaseEntity, DomainEvent, and all domain primitives
  • Command, Query, AbstractCommandHandler, AbstractQueryHandler
  • HandlerRegistry, InMemoryCommandBus, InMemoryQueryBus, InMemoryEventBus
  • IBaseRepository, IUnitOfWork, BaseDomainService
  • The hexcore CLI for project scaffolding

​
Optional extras

Install only the integrations relevant to your stack. Mix and match by combining extras with a comma-separated list, for example hexcore[api,sql,redis].

​
hexcore[api] — FastAPI

pip install "hexcore[api]"
Installs fastapi ≥ 0.116.1. Provides API utility helpers and enables dependency-injection patterns for injecting buses and handlers into FastAPI routes.

​
hexcore[redis] — Redis

pip install "hexcore[redis]"
Installs redis ≥ 6.4.0 (async-capable). Enables the RedisEventBus for cross-process pub/sub, the RedisLockProvider for distributed cron-job locking, and the Redis cache backend.

​
hexcore[mongo] — MongoDB

pip install "hexcore[mongo]"
Installs beanie ≥ 2.0.0 (async ODM). Enables BeanieODMCommonImplementationsRepo for MongoDB-backed repositories and init_beanie_documents() for auto-document discovery.

​
hexcore[sql] — SQLAlchemy / PostgreSQL / SQLite

pip install "hexcore[sql]"
Installs sqlalchemy ≥ 2.0.43, alembic ≥ 1.16.5, asyncpg ≥ 0.30.0, and aiosqlite ≥ 0.21.0. Enables BaseSQLAlchemyRepository, async session management, and Alembic migrations.

​
hexcore[rabbitmq] — RabbitMQ

pip install "hexcore[rabbitmq]"
Installs aio-pika ≥ 9.4.0 and pika ≥ 1.3.2. Enables the RabbitMQ event bus and worker implementations for distributing domain events over AMQP.

​
hexcore[procrastinate] — Procrastinate task queue

pip install "hexcore[procrastinate]"
Installs procrastinate ≥ 3.0.0. Enables the Procrastinate enqueuer adapter for background command/handler routing, and the PostgresLockProvider for distributed scheduling.

​
hexcore[celery] — Celery task queue

pip install "hexcore[celery]"
Installs celery ≥ 5.4.0. Enables the CeleryEnqueuer adapter and register_hexcore_celery_tasks() helper for auto-registering CQRS tasks on the Celery worker.

​
hexcore[all] — Everything

pip install "hexcore[all]"
Installs every optional dependency at once. Useful for local development and CI pipelines where you want the full feature set without remembering which extras to include.

​
Installing multiple extras

# API + PostgreSQL + Redis
pip install "hexcore[api,sql,redis]"

# API + MongoDB + Celery
pip install "hexcore[api,mongo,celery]"

​
Python version requirements

PythonSupported
3.12✅
3.13✅
< 3.12❌
HexCore uses features from Python 3.12 such as improved type-parameter syntax and updated datetime semantics. Attempting to install on Python 3.11 or earlier will produce a resolver error.

​
Environment variable configuration

HexCore’s LazyConfig resolves which config.py module to load at startup. Override the defaults using environment variables so that different environments (dev, staging, production) can each point to a different configuration module. 
# Load a single config module (highest priority)
export HEXCORE_CONFIG_MODULE="myapp.config"

# Load multiple config modules (comma-separated, evaluated left-to-right)
export HEXCORE_CONFIG_MODULES="myapp.config,myapp.config_overrides"
The full resolution order used by LazyConfig is:
  1. HEXCORE_CONFIG_MODULE environment variable
  2. HEXCORE_CONFIG_MODULES environment variable (comma-separated list)
  3. Modules registered via LazyConfig.set_config_modules(...)
  4. Default config module at the project root
A minimal config.py looks like this: 
from hexcore.config import ServerConfig

config = ServerConfig(
    repository_discovery_paths={
        "myapp.features.users.infrastructure.repositories",
        "myapp.features.orders.infrastructure.repositories",
    }
)
Since v2, if repository_discovery_paths is empty the Unit of Work raises an explicit error rather than silently discovering no repositories. This prevents hard-to-debug runtime failures in production.

​
Verifying the install

Run the HexCore CLI to confirm the package is installed and accessible: 
hexcore --help
To scaffold a new project immediately: 
# Hexagonal layout: src/domain, src/application, src/infrastructure
hexcore init my_project --template hexagonal

# Vertical-slice layout: src/features, src/shared/{domain,application,infrastructure}
hexcore init my_project --template vertical-slice

Build docs developers (and LLMs) love

Get started for freeTalk to us