Skip to content
Python CQRS

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.

    Read More

  • Request Handlers

    Handle commands and queries with full type safety and async support.

    Read More

  • Saga Pattern

    Orchestrated Saga for distributed transactions with automatic compensation.

    Read More

  • Event Handling

    Process domain events with parallel processing and runtime execution.

    Read More

  • Transaction Outbox

    Guaranteed event delivery with at-least-once semantics.

    Read More

  • Chain of Responsibility

    Sequential request processing with flexible handler chaining.

    Read More

  • Streaming

    Incremental processing with real-time progress updates via SSE.

    Read More

  • Integrations

    FastAPI and FastStream integrations out of the box.

    Read More

  • Testing

    Run the real mediators and read what they handled, published, and stored.

    Read More

  • Mermaid Diagrams

    Visualize architecture patterns and flows with interactive Mermaid diagrams.

    Read More


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

Group Badges
Python version & PyPI Python Versions PyPI
Downloads Total downloads Downloads per month
Quality & CI Coverage CodSpeed
Documentation & community Documentation Ask DeepWiki

Installation

Install Python CQRS using pip or uv:

Using pip:

pip install python-cqrs

Using uv:

uv pip install python-cqrs

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.