Skip to content

Commit 0e4c353

Browse files
author
Вадим Козыревский
committed
Update Documentation
1 parent 214425a commit 0e4c353

9 files changed

Lines changed: 693 additions & 189 deletions

File tree

‎docs/index.md‎

Lines changed: 84 additions & 189 deletions
Original file line numberDiff line numberDiff line change
@@ -22,72 +22,107 @@
2222

2323
---
2424

25+
## Core Features
26+
27+
<div class="grid cards" markdown>
28+
29+
- :material-rocket-launch: **Bootstrap**
30+
31+
Quick project setup and configuration with automatic DI container setup.
32+
33+
[:octicons-arrow-right-24: Get Started](bootstrap/index.md)
34+
35+
- :material-code-tags: **Request Handlers**
36+
37+
Handle commands and queries with full type safety and async support.
38+
39+
[:octicons-arrow-right-24: Learn More](request_handler.md)
40+
41+
- :material-sync: **Saga Pattern**
42+
43+
Orchestrated Saga for distributed transactions with automatic compensation.
44+
45+
[:octicons-arrow-right-24: Explore](saga/index.md)
46+
47+
- :material-bell-ring: **Event Handling**
48+
49+
Process domain events with parallel processing and runtime execution.
50+
51+
[:octicons-arrow-right-24: Discover](event_handler/index.md)
52+
53+
- :material-database-outline: **Transaction Outbox**
54+
55+
Guaranteed event delivery with at-least-once semantics.
56+
57+
[:octicons-arrow-right-24: Read More](outbox/index.md)
58+
59+
- :material-link-variant: **Chain of Responsibility**
60+
61+
Sequential request processing with flexible handler chaining.
62+
63+
[:octicons-arrow-right-24: See Details](chain_of_responsibility/index.md)
64+
65+
- :material-play-circle: **Streaming**
66+
67+
Incremental processing with real-time progress updates via SSE.
68+
69+
[:octicons-arrow-right-24: Learn More](stream_handling/index.md)
70+
71+
- :material-puzzle: **Integrations**
72+
73+
FastAPI, FastStream, Kafka, and Protobuf integrations out of the box.
74+
75+
[:octicons-arrow-right-24: View Integrations](fastapi.md)
76+
77+
</div>
78+
79+
---
80+
2581
## What is it?
2682

27-
**Python CQRS** is a framework for implementing the CQRS (Command Query Responsibility Segregation) pattern in Python
28-
applications. It helps separate read and write operations, improving scalability, performance, and code maintainability.
83+
**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.
2984

30-
### Key Benefits
85+
**Key Highlights:**
3186

32-
| Feature | Description |
33-
|---------|-------------|
34-
| 🚀 **Performance** | Separation of commands and queries, parallel event processing |
35-
| 🔒 **Reliability** | Transaction Outbox for guaranteed event delivery |
36-
| 🎯 **Type Safety** | Full Pydantic v2 support with runtime validation |
37-
| 🔌 **Integrations** | FastAPI, FastStream, Kafka out of the box |
38-
| ⚡ **Simplicity** | Bootstrap for quick setup and configuration |
39-
| 📡 **Streaming** | Real-time progress updates with StreamingRequestHandler |
40-
| 🔗 **Flexibility** | Chain of Responsibility pattern support |
41-
| 📦 **Protobuf** | Protocol Buffers events serialization support |
42-
| 🔄 **Saga Pattern** | Orchestrated Saga for distributed transactions with automatic compensation |
43-
| 📊 **Mermaid Diagrams** | Built-in generation of Sequence and Class diagrams for Chain of Responsibility and Saga patterns |
87+
- :material-rocket-launch: **Performance** — Separation of commands and queries, parallel event processing
88+
- :material-shield-check: **Reliability** — Transaction Outbox for guaranteed event delivery
89+
- :material-check-circle: **Type Safety** — Full Pydantic v2 support with runtime validation
90+
- :material-puzzle: **Ready Integrations** — FastAPI, FastStream, Kafka out of the box
91+
- :material-lightning-bolt: **Simple Setup** — Bootstrap for quick configuration
4492

4593
---
4694

4795
## Quick Start
4896

49-
### Installation
50-
5197
```bash
5298
pip install python-cqrs
5399
```
54100

55-
### Basic Example
56-
57101
```python
58102
import di
59103
import cqrs
60104
from cqrs.requests import bootstrap
61105

62-
# 1. Define commands, queries, and events
106+
# Define command, response and handler
63107
class CreateUserCommand(cqrs.Request):
64108
email: str
65109
name: str
66110

67111
class CreateUserResponse(cqrs.Response):
68112
user_id: str
69113

70-
# 2. Create handlers
71114
class CreateUserHandler(cqrs.RequestHandler[CreateUserCommand, CreateUserResponse]):
72-
def __init__(self):
73-
self._events: list[cqrs.events.Event] = []
74-
75-
@property
76-
def events(self) -> list[cqrs.events.Event]:
77-
return self._events
78-
79115
async def handle(self, request: CreateUserCommand) -> CreateUserResponse:
116+
# Your business logic here
80117
user_id = f"user_{request.email}"
81-
self._events.append(UserCreatedEvent(user_id=user_id, ...))
82118
return CreateUserResponse(user_id=user_id)
83119

84-
# 3. Bootstrap mediator
120+
# Bootstrap and use
85121
mediator = bootstrap.bootstrap(
86122
di_container=di.Container(),
87123
commands_mapper=lambda m: m.bind(CreateUserCommand, CreateUserHandler),
88124
)
89125

90-
# 4. Use mediator
91126
result = await mediator.send(CreateUserCommand(email="user@example.com", name="John"))
92127
```
93128

@@ -97,175 +132,35 @@ See [Bootstrap](bootstrap/index.md) for detailed setup instructions.
97132

98133
## Architecture
99134

100-
The `python-cqrs` framework follows a clear architectural pattern:
101-
102-
<div class="architecture-diagram">
103-
<div class="arch-row">
104-
<div class="arch-section">
105-
<h4>Request</h4>
106-
<p>Commands & Queries</p>
107-
</div>
108-
<div class="arch-arrow">→</div>
109-
<div class="arch-section">
110-
<h4>RequestHandler</h4>
111-
<p>Execute business logic</p>
112-
</div>
113-
</div>
114-
<div class="arch-row">
115-
<div class="arch-arrow arch-event-arrow">→</div>
116-
<div class="arch-section">
117-
<h4>Event</h4>
118-
<p>Notify about changes</p>
119-
</div>
120-
<div class="arch-arrow">→</div>
121-
<div class="arch-section">
122-
<h4>EventHandler</h4>
123-
<p>Process side effects</p>
124-
</div>
125-
</div>
126-
</div>
127-
128-
**Flow:**
135+
**Request** → **RequestHandler** → **Event** → **EventHandler**
129136

130-
1. **Commands/Queries** are sent to the mediator
131-
2. **Request Handlers** execute business logic and may emit events
132-
3. **Events** are automatically dispatched to event handlers
133-
4. **Event Handlers** process side effects (notifications, read model updates, etc.)
137+
Commands and queries flow through handlers, which execute business logic and emit events. Events are automatically dispatched to event handlers for side effects processing.
134138

135139
---
136140

137-
## Key Features
138-
139-
### 🎯 CQRS Pattern
140-
141-
| Aspect | Description |
142-
|--------|-------------|
143-
| **Separation** | Clear separation of commands and queries |
144-
| **Scaling** | Independent scaling of read/write models |
145-
| **Optimization** | Optimization for specific use cases |
146-
| **Handlers** | Async handlers with full type safety |
147-
148-
### 📦 Transaction Outbox
149-
150-
| Feature | Benefit |
151-
|---------|---------|
152-
| **Guaranteed Delivery** | At-least-once semantics |
153-
| **Broker Support** | Kafka support via aiokafka |
154-
| **Failure Handling** | Automatic failure handling |
155-
| **Event Types** | Support for Notification and ECST events |
156-
157-
### 🔌 Ready Integrations
158-
159-
| Integration | Description |
160-
|-------------|-------------|
161-
| **FastAPI** | HTTP API endpoints and SSE streaming support |
162-
| **FastStream** | Kafka and RabbitMQ event processing |
163-
| **Kafka** | Native support via aiokafka |
164-
| **Pydantic v2** | Full data validation support |
165-
| **Protobuf** | Protocol Buffers events serialization |
166-
167-
### ⚙️ Bootstrap
168-
169-
| Feature | Description |
170-
|---------|-------------|
171-
| **DI Container** | Automatic DI container setup |
172-
| **Mapping** | Command, query, and event mapping |
173-
| **Configurations** | Ready configurations for popular frameworks |
174-
| **Multiple DI** | Works with `di` and `dependency-injector` libraries |
175-
176-
### 📡 Streaming Requests
177-
178-
| Feature | Use Case |
179-
|---------|----------|
180-
| **Incremental Processing** | `StreamingRequestHandler` for incremental processing |
181-
| **Progress Updates** | Real-time progress updates via `StreamingRequestMediator` |
182-
| **Large Batches** | Perfect for large batches and file processing |
183-
| **SSE Integration** | Server-Sent Events integration with FastAPI |
184-
185-
### 🔗 Chain of Responsibility
186-
187-
| Feature | Description |
188-
|---------|-------------|
189-
| **Sequential Processing** | `CORRequestHandler` for sequential request processing |
190-
| **Fallback Support** | Multiple handlers per request with fallback support |
191-
| **Flexible Chaining** | Flexible handler chaining |
192-
193-
### 🔄 Saga Pattern
194-
195-
| Feature | Description |
196-
|---------|-------------|
197-
| **Distributed Transactions** | Orchestrated Saga pattern for managing distributed transactions |
198-
| **Automatic Compensation** | Automatic rollback of completed steps on failure |
199-
| **Recovery Mechanism** | Resume interrupted sagas from persistent storage |
200-
| **Eventual Consistency** | Ensures eventual consistency across distributed systems |
201-
| **Storage Support** | Memory and SQLAlchemy storage implementations |
202-
203-
### ⚡ Parallel Event Processing
204-
205-
| Feature | Benefit |
206-
|---------|---------|
207-
| **Concurrency Limits** | Configurable concurrency limits for event handlers |
208-
| **Parallel Processing** | Parallel processing of domain events |
209-
| **Performance** | Improved performance for independent event handlers |
210-
211-
### 📊 Mermaid Diagram Generation
212-
213-
| Feature | Description |
214-
|---------|-------------|
215-
| **Chain of Responsibility** | Generate Sequence and Class diagrams for handler chains |
216-
| **Saga Pattern** | Generate Sequence and Class diagrams for saga execution flows |
217-
| **Documentation** | Perfect for documentation, visualization, and understanding component structure |
218-
| **Multiple Formats** | Sequence diagrams for execution flow, Class diagrams for type structure |
219-
220-
See [Mermaid Diagrams](mermaid/index.md) for detailed documentation.
221-
222-
## Documentation
223-
224-
### Core Concepts
225-
226-
Start here to understand the fundamentals:
227-
228-
| # | Topic | Description |
229-
|---|-------|-------------|
230-
| 1 | [**Bootstrap**](bootstrap/index.md) | Quick project setup and configuration |
231-
| 2 | [**Dependency Injection**](di.md) | Managing dependencies with DI containers |
232-
| 3 | [**Request Handlers**](request_handler.md) | Working with commands and queries |
233-
| 4 | [**Stream Handling**](stream_handling/index.md) | Incremental processing with streaming |
234-
| 5 | [**Chain of Responsibility**](chain_of_responsibility/index.md) | Sequential request processing |
235-
| 6 | [**Saga Pattern**](saga/index.md) | Distributed transactions with automatic compensation and recovery |
236-
| 7 | [**Event Handling**](event_handler/index.md) | Processing domain events |
237-
| 8 | [**Transaction Outbox**](outbox/index.md) | Reliable event delivery pattern |
238-
239-
!!! tip "Learning Path"
240-
Follow the numbered sequence for the best learning experience. Each concept builds on the previous one.
241-
242-
### Integrations
141+
## Installation
243142

244-
Learn how to integrate with popular frameworks:
143+
```bash
144+
pip install python-cqrs
145+
```
245146

246-
| Integration | Description | Use Case |
247-
|-------------|-------------|----------|
248-
| [**FastAPI**](fastapi.md) | HTTP API endpoints and SSE streaming | Web applications |
249-
| [**FastStream**](faststream.md) | Kafka and RabbitMQ event processing | Event-driven systems |
250-
| [**Event Producing**](event_producing.md) | Publishing events to message brokers | Microservices communication |
251-
| [**Protobuf**](protobuf.md) | Protocol Buffers serialization | High-performance scenarios |
147+
!!! info "Requirements"
148+
Python 3.8+ • Pydantic v2
252149

253150
---
254151

255-
## Installation
256-
257-
Choose the installation method that best fits your workflow:
152+
## Documentation
258153

259-
| Method | Command | Use Case |
260-
|--------|---------|----------|
261-
| **PyPI** | `pip install python-cqrs` | Standard installation |
262-
| **GitHub** | `pip install git+https://github.com/vadikko2/python-cqrs` | Latest development version |
263-
| **uv** | `uv add python-cqrs` | Modern Python package manager |
154+
Explore the comprehensive documentation to learn more about each feature:
264155

265-
!!! info "Requirements"
266-
- Python 3.8+
267-
- Pydantic v2
268-
- For integrations: FastAPI, FastStream, etc. (see specific integration docs)
156+
- **[Bootstrap](bootstrap/index.md)** — Quick project setup and configuration
157+
- **[Request Handlers](request_handler.md)** — Working with commands and queries
158+
- **[Saga Pattern](saga/index.md)** — Distributed transactions with automatic compensation
159+
- **[Event Handling](event_handler/index.md)** — Processing domain events
160+
- **[Transaction Outbox](outbox/index.md)** — Reliable event delivery
161+
- **[Stream Handling](stream_handling/index.md)** — Incremental processing with streaming
162+
- **[Chain of Responsibility](chain_of_responsibility/index.md)** — Sequential request processing
163+
- **[Integrations](fastapi.md)** — FastAPI, FastStream, Kafka, Protobuf
269164

270165
---
271166

‎docs/javascripts/navigation.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,10 @@
8383
{ title: 'Saga Storage', url: 'saga/storage/', path: 'saga/storage' },
8484
{ title: 'Saga Recovery', url: 'saga/recovery/', path: 'saga/recovery' },
8585
{ title: 'Saga Compensation', url: 'saga/compensation/', path: 'saga/compensation' },
86+
{ title: 'Saga Fallback Pattern', url: 'saga/fallback/', path: 'saga/fallback/index' },
87+
{ title: 'Saga Fallback Mechanics', url: 'saga/fallback/mechanics/', path: 'saga/fallback/mechanics' },
88+
{ title: 'Saga Fallback Circuit Breaker', url: 'saga/fallback/circuit_breaker/', path: 'saga/fallback/circuit_breaker' },
89+
{ title: 'Saga Fallback Examples', url: 'saga/fallback/examples/', path: 'saga/fallback/examples' },
8690
{ title: 'Saga Examples', url: 'saga/examples/', path: 'saga/examples' },
8791
// Event Handler
8892
{ title: 'Events Handling', url: 'event_handler/', path: 'event_handler/index' },

0 commit comments

Comments
 (0)