Python CQRS
Event-Driven Architecture Framework for Distributed Systems
Documentation for python-cqrs 5.6
You are viewing 5.6 docs (dataclass defaults, optional Pydantic/SQLAlchemy, optional SQLModel storage since 5.1, Request[Result] and one-argument handlers since 5.2, new package layout, SagaMediator.execute). The quick start omits di_container. That call works on 5.6.0. On 5.5.0, bootstrap still requires di_container.
Migrating from 4.x? Follow the 4→5 migration guide. Use the version selector for frozen 4.0 docs.
Core Features¶
-
Bootstrap
Quick project setup and configuration with automatic DI container setup.
-
Request Handlers
Handle commands and queries with full type safety and async support.
-
Saga Pattern
Orchestrated Saga for distributed transactions with automatic compensation.
-
Event Handling
Process domain events with parallel processing and runtime execution.
-
Transaction Outbox
Guaranteed event delivery with at-least-once semantics.
-
Chain of Responsibility
Sequential request processing with flexible handler chaining.
-
Streaming
Incremental processing with real-time progress updates via SSE.
-
Integrations
FastAPI and FastStream integrations out of the box.
-
Testing
Run the real mediators and read what they handled, published, and stored.
-
Mermaid Diagrams
Visualize architecture patterns and flows with interactive Mermaid diagrams.
What is it?¶
Python CQRS is a framework for implementing the CQRS (Command Query Responsibility Segregation) pattern in Python applications. It helps separate read and write operations, improving scalability, performance, and code maintainability.
Key Highlights:
- Performance — Separation of commands and queries, parallel event processing
- Reliability — Transaction Outbox for guaranteed event delivery, Saga with compensation support and eventual consistency
- Flexible Types — Easy integration with any type: Pydantic, dataclasses, msgspec, attrs, TypedDict and more
- Ready Integrations — FastAPI and FastStream out of the box
- Simple Setup — Bootstrap for quick configuration
- Proven Patterns — CQRS, Saga, Outbox and more to keep services decoupled and maintainable
Project status¶
Installation¶
Install Python CQRS using pip or uv:
Using pip:
Using uv:
Requirements
Python 3.10+ (tested on 3.10–3.15)
Quick Start¶
import cqrs
from cqrs.bootstrap import requests as bootstrap
class CreateUserResponse(cqrs.Response):
user_id: str
class CreateUserCommand(cqrs.Request[CreateUserResponse]):
email: str
name: str
class CreateUserHandler(cqrs.RequestHandler[CreateUserCommand]):
async def handle(self, request: CreateUserCommand):
user_id = f"user_{request.email}"
return CreateUserResponse(user_id=user_id)
mediator = bootstrap.bootstrap(
commands_mapper=lambda m: m.bind(CreateUserCommand, CreateUserHandler),
)
result = await mediator.send(CreateUserCommand(email="user@example.com", name="John"))
result is CreateUserResponse. Do not add -> CreateUserResponse on handle. Legacy (still supported): RequestHandler[CreateUserCommand, CreateUserResponse] still works and is not the form to copy. This handler takes no constructor arguments, so no container is passed. A handler that needs a port is constructed with that port and registered under its type: container.register(CreateUserHandler, CreateUserHandler(port)). SimpleContainer does not pass a registered port into the constructor. Optional containers (python-cqrs[di], python-cqrs[dependency-injector], python-cqrs[dishka]) build the handler themselves. Rules for agents: For agents.
See Bootstrap for detailed setup instructions.