Metadata-Version: 2.4
Name: edri
Version: 2026.8.2rc3
Summary: Event Driven Routing Infrastructure
Author-email: Marek Olšan <marek@olsanovi.cz>
License: MIT
Project-URL: Documentation, https://edri.olsanovi.cz
Keywords: event-driven,routing,distributed,parallel,multiprocessing,asyncio,api,framework,websocket
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typeguard>=4.0
Requires-Dist: requests>=2.0
Requires-Dist: validators>=0.22.0
Requires-Dist: typing_extensions>=4.0
Requires-Dist: multipart>=1.0
Requires-Dist: jinja2>=3.1
Requires-Dist: watchdog>=6
Requires-Dist: websockets>=14
Requires-Dist: posix-ipc>=1.2.0
Requires-Dist: markdown>=3.0
Requires-Dist: pytz>=2024.1
Provides-Extra: uvicorn
Requires-Dist: uvicorn[standard]>=0.32.0; extra == "uvicorn"
Requires-Dist: wsproto>=1.0.0; extra == "uvicorn"
Provides-Extra: hypercorn
Requires-Dist: hypercorn[h3]>=0.17.0; extra == "hypercorn"
Requires-Dist: uvloop>=0.20.0; extra == "hypercorn"
Provides-Extra: daphne
Requires-Dist: daphne>=4.2.2; extra == "daphne"
Requires-Dist: twisted[http2,tls,websocket]>=24.0.0; extra == "daphne"
Requires-Dist: service-identity>=18.1.0; extra == "daphne"
Requires-Dist: idna>=2.5; extra == "daphne"
Provides-Extra: sqlalchemy
Requires-Dist: sqlalchemy>=2.0; extra == "sqlalchemy"
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai-slim[openai]>=0.0.1; extra == "pydantic-ai"
Provides-Extra: dev
Requires-Dist: edri[uvicorn]; extra == "dev"
Requires-Dist: edri[hypercorn]; extra == "dev"
Requires-Dist: edri[sqlalchemy]; extra == "dev"
Requires-Dist: edri[pydantic-ai]; extra == "dev"
Requires-Dist: sphinx>=8.0.0; extra == "dev"
Requires-Dist: myst-parser>=4.0.0; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints>=3.1.0; extra == "dev"
Requires-Dist: furo>=2024.1.29; extra == "dev"
Requires-Dist: sphinxcontrib-mermaid>=2.0.0; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pydantic-ai-slim[openai]>=0.0.1; extra == "dev"
Dynamic: license-file

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

[![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/)

---

## 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: [Getting Started](https://edri.olsanovi.cz/stable/getting_started.html)

---

## Architecture overview

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
pip install edri

# With ASGI server
pip install edri[uvicorn]    # recommended
pip install edri[hypercorn]  # HTTP/3 support
pip install edri[daphne]     # Twisted-based

# 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](https://edri.olsanovi.cz/stable/getting_started.html) — installation, minimal example, next steps
* [Architecture](https://edri.olsanovi.cz/stable/architecture.html) — component model, process architecture, data flow
* [Testing](https://edri.olsanovi.cz/stable/testing.html) — unit and integration testing guide

---

## Core Concepts

* [Event](https://edri.olsanovi.cz/stable/event.html) — defining events, responses, field types, lifecycle
* [Response](https://edri.olsanovi.cz/stable/response.html) — response status, directives, HTTP status mapping
* [Router](https://edri.olsanovi.cz/stable/router.html) — dispatching, subscriptions, caching, health checks
* [Manager](https://edri.olsanovi.cz/stable/manager.html) — event handlers, workers, lifecycle, caching
* [Worker](https://edri.olsanovi.cz/stable/worker.html) — thread vs process, communication, `event_send`

---

## API Layer

* [API](https://edri.olsanovi.cz/stable/api.html) — REST, WebSocket, HTML, content negotiation
* [API Event](https://edri.olsanovi.cz/stable/api_event.html) — `@api(...)` decorator, URL patterns, input extraction
* [Content Negotiation](https://edri.olsanovi.cz/stable/api_content_negotiation.html) — `Accept` header handling, response wrapping, `Vary`
* [Download](https://edri.olsanovi.cz/stable/api_download.html) — Path vs SharedMemoryPipe, HTTP Range
* [HTML](https://edri.olsanovi.cz/stable/html.html) — Jinja2 templates, `{% url %}`, static files
* [WebSocket](https://edri.olsanovi.cz/stable/websocket.html) — connection, commands, subscription protocol
* [Validation](https://edri.olsanovi.cz/stable/validation.html) — `inject(...)`, built-in validators, custom validators
* [Uploads](https://edri.olsanovi.cz/stable/uploads.html) — file upload lifecycle, temporary files, workers, cleanup responsibility
* [Middleware](https://edri.olsanovi.cz/stable/middleware.html) — pipeline, auth patterns, transport-agnostic design
* [Broker](https://edri.olsanovi.cz/stable/broker.html) — client management, WebSocket subscription trie, middleware execution

---

## Distribution

* [Connector](https://edri.olsanovi.cz/stable/connector.html) — Router ↔ Switch bridge, demands, resilience
* [Switch](https://edri.olsanovi.cz/stable/switch.html) — TCP/IP hub, message protocol, connection lifecycle

---

## Specialized Components

* [Specialized Managers](https://edri.olsanovi.cz/stable/specialized_managers.html) — timed events, shared state
* [Watcher](https://edri.olsanovi.cz/stable/watcher.html) — hot-reload for development
* [JSON Encoder](https://edri.olsanovi.cz/stable/json_encoder.html) — custom JSON serialization
* [Utility](https://edri.olsanovi.cz/stable/utility.html) — Storage, Queue, NormalizedDefaultDict

---

## Operations

* [Environment](https://edri.olsanovi.cz/stable/env.html) — all configuration variables
* [Deployment](https://edri.olsanovi.cz/stable/deployment.html) — production setup, Docker, Nginx, systemd, Kubernetes
* [Troubleshooting](https://edri.olsanovi.cz/stable/troubleshooting.html) — common problems, diagnostics, gotchas
* [Versioned Documentation](https://edri.olsanovi.cz/stable/versioned_documentation.html) — how the `/vX.Y.Z/`, `/stable/` and version switcher work

---

## Examples

| Example | Area | Documentation |
|---------|------|---------------|
| REST CRUD with validation | REST | [REST CRUD](https://edri.olsanovi.cz/stable/examples/rest/crud.html) |
| HTML form Post/Redirect/Get | HTML | [HTML Form](https://edri.olsanovi.cz/stable/examples/html/form_post_redirect.html) |
| CPU-bound WorkerProcess | Worker | [CPU Bound](https://edri.olsanovi.cz/stable/examples/worker/cpu_bound.html) |
| Streaming ZIP via SharedMemoryPipe | Worker | [SharedMemoryPipe](https://edri.olsanovi.cz/stable/examples/worker/shared_memory_pipe.html) |
| Periodic refresh + Store | Scheduler | [Periodic Refresh](https://edri.olsanovi.cz/stable/examples/scheduler/periodic_refresh.html) |
| WebSocket ticket pattern | WebSocket | [WebSocket Upload](https://edri.olsanovi.cz/stable/examples/websocket/upload.html) |
| Bearer token authentication | Middleware | [Auth Middleware](https://edri.olsanovi.cz/stable/examples/middleware/auth.html) |

---

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