EDRI Documentation¶

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¶

pip install edri[uvicorn]

# 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()

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

Full getting-started guide: Getting Started

Architecture overview¶

        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¶

# 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:

Getting Started — installation, minimal example, next steps
Architecture Overview — component model, process architecture, data flow
Testing — unit and integration testing guide

Core Concepts¶

Event — defining events, responses, field types, lifecycle
Response — response status, directives, HTTP status mapping
Router — dispatching, subscriptions, caching, health checks
Manager — event handlers, workers, lifecycle, caching
Worker — thread vs process, communication, event_send

API Layer¶

API — REST, WebSocket, HTML, content negotiation
API Event — @api(...) decorator, URL patterns, input extraction
Content Negotiation — Accept header handling, response wrapping, Vary
Downloading files — Path vs SharedMemoryPipe, HTTP Range
HTML API — Jinja2 templates, {% url %}
Static files — serving CSS, JS, and images from EDRI_ASSETS_PATH
WebSocket — connection, commands, subscription protocol
Validation & Injection — inject(...), built-in validators, custom validators
Uploads — file upload lifecycle, temporary files, workers, cleanup responsibility
Middleware — pipeline, auth patterns, transport-agnostic design
Broker — client management, WebSocket subscription trie, middleware execution

Distribution¶

Connector — Router ↔ Switch bridge, demands, resilience
Switch — TCP/IP hub, message protocol, connection lifecycle

Specialized Components¶

Specialized managers — timed events, shared state
Watcher (Hot Reload) — hot-reload for development
JSON encoding — custom JSON serialization
Utility — Storage, Queue, NormalizedDefaultDict

Operations¶

Changelog — notable changes, compatibility notes, and release history
Environment Variables — all configuration variables
Deployment — production setup, Docker, Nginx, systemd, Kubernetes
Troubleshooting — common problems, diagnostics, gotchas
Versioned documentation — how the /vX.Y.Z/, /stable/ and version switcher work

Examples¶

Example	Area	File
REST CRUD with validation	REST	REST CRUD with validation
HTML form Post/Redirect/Get	HTML	HTML form: GET the form, POST it, redirect on success
CPU-bound WorkerProcess	Worker	Offloading CPU-bound work to a WorkerProcess
Streaming ZIP via SharedMemoryPipe	Worker	SharedMemoryPipe: streaming a ZIP of a folder
Periodic refresh + Store	Scheduler	Periodic refresh into the Key-Value Store
WebSocket ticket pattern	WebSocket	Asynchronous File Processing with WebSocket Feedback (Ticket Pattern)
Bearer token authentication	Middleware	Middleware: Token authentication end-to-end

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)