Migration guide: 4.x → 5.0

This page covers breaking changes in python-cqrs 5.0. Discussion: GitHub #57.

Support policy

Line	What you get
4.x (pip install "python-cqrs>=4,<5")	Bug fixes / security (~12 months after 5.0)
5.x	Features + breaking changes

Docs: use the version selector for 4.0 vs this 5.0 site.

Optional extras

Pydantic and SQLAlchemy are no longer core dependencies.

pip install python-cqrs                      # dataclasses defaults
pip install "python-cqrs[pydantic]"          # Pydantic* types
pip install "python-cqrs[sqlalchemy]"        # Outbox / Saga SQLAlchemy storage
pip install "python-cqrs[pydantic,sqlalchemy]"  # ≈ previous default stack

Default aliases Request, Response, Event, DomainEvent, NotificationEvent point at DC* dataclasses. Use PydanticRequest / PydanticEvent / … from cqrs.models.pydantic when you need validation.

Import path table (hard break — no shims)

4.x	5.0
cqrs.requests.bootstrap	cqrs.bootstrap.requests
cqrs.events.bootstrap	cqrs.bootstrap.events
cqrs.saga.bootstrap	cqrs.bootstrap.saga
cqrs.mediator	cqrs.mediators (.request, .event, .streaming, .saga)
cqrs.requests.request_handler	cqrs.handlers.request
cqrs.requests.cor_request_handler	cqrs.handlers.cor
cqrs.events.event_handler	cqrs.handlers.event
cqrs.saga.step	cqrs.handlers.saga
cqrs.requests.request / cqrs.response / cqrs.events.event	cqrs.models.request / .response / .event
Pydantic classes	cqrs.models.pydantic
cqrs.requests.map / cqrs.events.map / cqrs.outbox.map	cqrs.mapping.requests / .events / .outbox
cqrs.requests.mermaid / cqrs.saga.mermaid	cqrs.mermaid.cor / .saga
cqrs.producer.EventProducer	cqrs.message_brokers.producer.EventProducer

Root import cqrs still re-exports the stable public surface (mediators, handlers, DC models, maps, mermaid, EventProducer).

SagaMediator.stream → execute

# 4.x
async for step in mediator.stream(context, saga_id=saga_id):
    ...

# 5.0
async for step in mediator.execute(context, saga_id=saga_id):
    ...

StreamingRequestMediator.stream is unchanged.

Optional events on handlers

Empty events / default () behavior from 4.15 remains; you do not need to declare an empty events property.

Checklist

1. Pin or upgrade: "python-cqrs>=5" vs "python-cqrs>=4,<5".
2. Install extras you still need (pydantic, sqlalchemy, kafka, …).
3. Switch defaults to DC* or import Pydantic* explicitly.
4. Rewrite imports using the table above.
5. Rename SagaMediator.stream → execute.
6. Re-run tests / type check.