# markkorput/pyevento architecture

> Architecture diagram of the GitHub repository markkorput/pyevento, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/markkorput/pyevento
- Repository: https://github.com/markkorput/pyevento

## Overview

##### Project type and purpose
- pyevento (the “evento” Python package) is an open-source library that implements the Observer pattern in both synchronous and asynchronous styles.
- Its purpose is to let client code define and fire events, subscribe and unsubscribe handlers easily, and decorate methods to become multi-argument events.

##### File structure
- Top-level module: evento/
- base.py        – core abstractions and shared utilities
- event.py       – the synchronous Event[T] class
- async_event.py – the AsyncEvent[T] class for Python async/await
- decorators.py  – `@event` and `@async_event` decorators (multi-arg support)
- signature.py   – internal machinery for handling arbitrary signatures
- __init__.py    – public API imports and type aliases
- examples/       – sample usage scripts (basic, async, signature)
- tests/          – unit tests per module
- config files    – CI (Travis), linting (mypy), packaging (pyproject.toml, setup.cfg), coverage

##### Key insights from README
- Features:
- Simple subscribe/unsubscribe for single-arg events (generic)
- Async support with awaitable firing
- Decorators for multi-argument events, preserving the original function call
- Usage patterns:
- Client creates Event[T] or AsyncEvent[T]
- Client subscribes handlers (`+=`, `.add`, `.append`)
- Client fires events (`event(...)` or `await event(...)`)
- Client unsubscribes (`-=` or `.remove` or returned cleanup callable)

##### Main components
- Public API layer (evento/__init__.py)
- Core classes:
- Event[T] (sync dispatcher)
- AsyncEvent[T] (async dispatcher)
- Decorator layer:
- `event` decorator (sync multi-arg)
- `async_event` decorator (async multi-arg)
- Subscription mechanism:
- Internal subscriber registry (list of callables)
- /append and remove methods, operator overloads (`__iadd__`, `__isub__`)
- Dispatch mechanism:
- Event.__call__ → iterate subscribers → invoke handlers
- AsyncEvent.__call__/fire → await each subscriber
- Signature handling (signature.py)
- Wraps decorated methods, inspects and forwards args/kwargs

##### Relationships and data flow
- Client code → instantiates Event or AsyncEvent
- Client code ↔ (operator overloads) subscribes/unsubscribes handlers
- Firing an event:
a) Sync: client calls event(data) → Event.__call__ → for each handler: handler(data)
b) Async: client awaits event(data) → AsyncEvent.__call__ → await handler(data) → collect results/return value
- Decorator usage: method definition is replaced by an Event/AsyncEvent instance under the hood, but still calls the original function.

##### Architectural patterns and principles
- Observer pattern (publish–subscribe)
- Decorator pattern (wrapping methods to become events)
- Single responsibility: each module focuses on one aspect (sync vs async vs decoration)
- Generic typing (PEP 484) for type safety

##### Detail
- Generic type parameter T flowing from instantiation down to handler signatures
- Both single-arg flow and multi-arg decorator flow in separate sub-flows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Public API Layer"
        API["Public API\n(evento/__init__.py)"]:::api
    end

    subgraph "Core Dispatch Layer"
        Base["Base Abstractions\n(evento/base.py)"]:::core
        Event["Event[T]\n(evento/event.py)"]:::sync
        AsyncEvent["AsyncEvent[T]\n(evento/async_event.py)"]:::async
        SubscriberRegistry["Subscriber Registry\n(list of callables)"]:::storage
    end

    subgraph "Utility & Decorator Layer"
        Decorators["Decorators\n(evento/decorators.py)"]:::deco
        Signature["Signature Handling\n(evento/signature.py)"]:::util
    end

    %% Relationships
    API -->|"imports"| Event
    API -->|"imports"| AsyncEvent

    Event -->|"inherits / uses"| Base
    AsyncEvent -->|"inherits / uses"| Base

    Event -->|"manages"| SubscriberRegistry
    AsyncEvent -->|"manages"| SubscriberRegistry

    Event -->|"__call__"| SubscriberRegistry
    AsyncEvent -->|"__call__/fire()"| SubscriberRegistry

    SubscriberRegistry -->|"invoke handlers"| Handlers[("Handlers")]

    Decorators -->|"wraps to create"| Event
    Decorators -->|"wraps to create"| AsyncEvent
    Decorators -->|"uses"| Signature
    Signature -->|"inspects args"| Decorators

    %% Click Events
    click API "https://github.com/markkorput/pyevento/blob/master/evento/__init__.py"
    click Base "https://github.com/markkorput/pyevento/blob/master/evento/base.py"
    click Event "https://github.com/markkorput/pyevento/blob/master/evento/event.py"
    click AsyncEvent "https://github.com/markkorput/pyevento/blob/master/evento/async_event.py"
    click Decorators "https://github.com/markkorput/pyevento/blob/master/evento/decorators.py"
    click Signature "https://github.com/markkorput/pyevento/blob/master/evento/signature.py"

    %% Styles
    classDef api fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1;
    classDef core fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20;
    classDef sync fill:#FFF3E0,stroke:#FFB74D,color:#E65100;
    classDef async fill:#F3E5F5,stroke:#BA68C8,color:#4A148C;
    classDef deco fill:#FFEBEE,stroke:#EF5350,color:#B71C1C;
    classDef util fill:#ECEFF1,stroke:#B0BEC5,color:#37474F;
    classDef storage fill:#FFFDE7,stroke:#FDD835,color:#F57F17;
```
