---
orphan: true
---

# EDRI Documentation

[![Python](https://img.shields.io/badge/python-3.12%20|%203.13%20|%203.14%20|%203.15--rc-blue)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green)](https://opensource.org/licenses/MIT)
[![PyPI](https://img.shields.io/badge/pypi-edri-orange)](https://pypi.org/project/edri/)

**EDRI** is a Python framework for building **event-driven, parallel, and distributed applications**. It combines messaging, task execution, and an optional API layer (REST, WebSocket, HTML) into a single coherent system.

Welcome to the EDRI documentation. This is the central entry point for all documentation resources.

---

## Why EDRI?

Most Python frameworks solve one problem well:
- **Celery** handles background tasks but has no API layer or pub/sub.
- **Kafka** streams messages but does not execute tasks.
- **FastAPI** builds APIs but lacks task distribution.

EDRI combines all three: **message routing**, **task execution**, and **API exposure** in one framework.

---

## Quick start

```bash
pip install edri[uvicorn]
```

```python
# main.py
from edri import EDRI
from edri.abstract import ManagerBase, request
from edri.dataclass.event import Event
from edri.dataclass.response import Response, response
from edri.api.dataclass.api_event import api
from http import HTTPMethod


@response
class HelloResponse(Response):
    message: str

@api(url="/hello/{name}", method=HTTPMethod.GET)
class Hello(Event):
    name: str
    response: HelloResponse

class HelloManager(ManagerBase):
    @request
    def greet(self, event: Hello) -> None:
        event.response.message = f"Hello, {event.name}!"

if __name__ == "__main__":
    edri = EDRI()
    edri.add_component(HelloManager(edri.router_queue))
    edri.start_api()
    edri.run()
```

```bash
python main.py &
curl -H "Accept: application/json" http://localhost:8080/hello/World
```

Full getting-started guide: {doc}`/getting_started`

---

## Architecture overview

```mermaid
graph TD
    A[Events] --> B[Router]
    B --> C[Manager]
    C --> D[Worker]
    B --> E[Scheduler]
    B --> F[Key-Value Store]
    B --> G[API]
    B -- Connector --> H[Switch]
    H --> I[Other Router]
```

Events are the universal communication primitive. The **Router** dispatches them by type to subscribed **Managers**. Managers can delegate work to **Workers** (threads or processes), emit new events, or use specialized components like the **Scheduler** (timed events) and **Key-Value Store** (shared state). The **API** layer translates external HTTP/WS requests into events. For distributed deployments, the **Switch** connects routers across machines via TCP/IP.

---

## Installation

```bash
# Core: Router, Managers, Workers, Switch, Scheduler, Store
pip install edri

# HTTP/WebSocket API, with an ASGI server
pip install edri[uvicorn]    # recommended
pip install edri[hypercorn]  # HTTP/3 support
pip install edri[daphne]     # Twisted-based

# API layer without an ASGI server (e.g. behind edri[grpc])
pip install edri[api]

# Development
pip install edri[dev]
```

### Requirements

- Python 3.12+
- POSIX OS (Linux, macOS — macOS has never been tested)

---

## Getting Started

If you're new to EDRI, start here:

* {doc}`/getting_started` — installation, minimal example, next steps
* {doc}`/architecture` — component model, process architecture, data flow
* {doc}`/testing` — unit and integration testing guide

---

## Core Concepts

* {doc}`/event` — defining events, responses, field types, lifecycle
* {doc}`/response` — response status, directives, HTTP status mapping
* {doc}`/router` — dispatching, subscriptions, caching, health checks
* {doc}`/manager` — event handlers, workers, lifecycle, caching
* {doc}`/worker` — thread vs process, communication, `event_send`

---

## API Layer

* {doc}`/api` — REST, WebSocket, HTML, content negotiation
* {doc}`/api_event` — `@api(...)` decorator, URL patterns, input extraction
* {doc}`/api_content_negotiation` — `Accept` header handling, response wrapping, `Vary`
* {doc}`/api_download` — Path vs SharedMemoryPipe, HTTP Range
* {doc}`/html` — Jinja2 templates, `{% url %}`
* {doc}`/static_files` — serving CSS, JS, and images from `EDRI_ASSETS_PATH`
* {doc}`/websocket` — connection, commands, subscription protocol
* {doc}`/validation` — `inject(...)`, built-in validators, custom validators
* {doc}`/uploads` — file upload lifecycle, temporary files, workers, cleanup responsibility
* {doc}`/middleware` — pipeline, auth patterns, transport-agnostic design
* {doc}`/broker` — client management, WebSocket subscription trie, middleware execution

---

## Distribution

* {doc}`/connector` — Router ↔ Switch bridge, demands, resilience
* {doc}`/switch` — TCP/IP hub, message protocol, connection lifecycle

---

## Specialized Components

* {doc}`/specialized_managers` — timed events, shared state
* {doc}`/watcher` — hot-reload for development
* {doc}`/json_encoder` — custom JSON serialization
* {doc}`/utility` — Storage, Queue, NormalizedDefaultDict

---

## Operations

* [Changelog](https://edri.olsanovi.cz/changelog/) — notable changes,
  compatibility notes, and release history
* {doc}`/env` — all configuration variables
* {doc}`/deployment` — production setup, Docker, Nginx, systemd, Kubernetes
* {doc}`/troubleshooting` — common problems, diagnostics, gotchas
* {doc}`/versioned_documentation` — how the `/vX.Y.Z/`, `/stable/` and version switcher work

---

## Examples

| Example | Area | File |
|---------|------|------|
| REST CRUD with validation | REST | {doc}`/examples/rest/crud` |
| HTML form Post/Redirect/Get | HTML | {doc}`/examples/html/form_post_redirect` |
| CPU-bound WorkerProcess | Worker | {doc}`/examples/worker/cpu_bound` |
| Streaming ZIP via SharedMemoryPipe | Worker | {doc}`/examples/worker/shared_memory_pipe` |
| Periodic refresh + Store | Scheduler | {doc}`/examples/scheduler/periodic_refresh` |
| WebSocket ticket pattern | WebSocket | {doc}`/examples/websocket/upload` |
| Bearer token authentication | Middleware | {doc}`/examples/middleware/auth` |

---

## Quick comparison with other frameworks

| Feature | EDRI | Celery | Kafka | FastAPI |
|---------|------|--------|-------|---------|
| Task execution | ✅ Built-in | ✅ Workers | ❌ Messaging only | ❌ |
| API layer | ✅ REST/WS/HTML | ❌ | ❌ | ✅ REST/WS |
| Pub/Sub | ✅ Static routing | ❌ | ✅ Dynamic | ⚠️ WS only |
| Middleware | ✅ Full pipeline | ❌ | ❌ | ✅ DI |
| Distributed | ✅ Via Switch | ✅ Brokers | ✅ Clusters | ❌ |
| Parallelism | ✅ Threads + processes | ✅ Workers | ⚠️ Consumers | ⚠️ Async |

---

## License

MIT License.

## Author

Marek Olšan ([marek@olsanovi.cz](mailto:marek@olsanovi.cz))