Python-CQRS 5.0.0 — Planned Release Discussion

[vadikko2]

This discussion outlines the planned breaking changes for python-cqrs 5.0.0. The goal is to make the library more modular, reduce mandatory dependencies, and clarify the project structure. Feedback and suggestions are welcome.

---

Summary

Version 5.0.0 will focus on:

• Optional dependencies — Pydantic and SQLAlchemy will become optional.
• Package reorganization — splitting the codebase into focused packages (bootstrap, mediators, handlers, models, mermaid, mapping, and optionally a dedicated package for SQLAlchemy implementations — see below).
• API adjustments — optional events on handlers, renaming SagaMediator.stream, and moving broker-related code to a dedicated package.

---

Breaking Changes

Optional Dependencies

• Pydantic will be optional. Install explicitly if you use pydantic-based features (e.g. pip install python-cqrs[pydantic]).
• SQLAlchemy will be optional. Under discussion: whether SQLAlchemy-based implementations should live in a separate package (install only if you need them) or remain in the main repo as optional submodules. We welcome feedback on this.

Project Structure & Package Reorganization

The project hierarchy will be reorganized into clearer, thematic packages:

Current location / concept	New package / change
Bootstrap modules	Moved to a dedicated bootstrap package
Mediators	Moved to a separate package and split into thematic files (no longer a single large file)
Handlers	Moved to a dedicated handlers package
Models	Moved to a dedicated models package
Mermaid-related code	Moved to a dedicated mermaid package
Map / mapping modules	Moved to a dedicated mapping package
SQLAlchemy implementations	Under discussion: move to a separate package (e.g. python-cqrs-sqlalchemy) vs. keep as optional modules in the main package. Feedback welcome.

Import paths will change; migration notes and examples will be provided in the release notes.

Message Brokers

• EventProducer and all broker-related code will move to a new message_brokers package. This centralizes everything related to message brokers and keeps the core library focused.

API Changes

• Handlers — events method
  The events method on handlers will become optional. Default behavior will be return (). Handlers that do not produce events no longer need to implement events.

• SagaMediator — method rename
  cqrs.mediator.SagaMediator.stream will be renamed to execute (or another name that better reflects its role). The old name will be removed in 5.0.0.

---

Next Steps

• Finalize the exact package names and import paths.
• Decide on the final name for SagaMediator.stream (e.g. execute).
• Add migration guide and code examples for the new structure and imports.
• Consider deprecation warnings in a 4.x release before 5.0.0, where feasible.
• Open for discussion: Whether SQLAlchemy implementations should be extracted to a separate installable package or remain in the main repository as optional modules. Share your use cases and preferences.

If you have concerns, alternative naming ideas, or migration suggestions, please share them in the comments.