events-py API Reference

events_py

Event types and helpers for Python services (e.g. Pub/Sub).

Classes

EventEnvelope

Bases: TypedDict

Base event envelope for Pub/Sub or internal events.

All events share this structure. The payload field carries event-specific data as a JSON-serializable dict.

Example

envelope: EventEnvelope = { ... "id": "evt-001", ... "kind": "created", ... "payload": {"name": "adapter-1"}, ... "timestamp": "2026-01-01T00:00:00+00:00", ... }

EventKind

Bases: str, Enum

Supported event kinds for Rune service events.

Defines the three base event types. Rune-specific kinds (e.g. TRAINING_STARTED) will be added in service phases.

Example

EventKind.CREATED.value 'created' EventKind("updated") == EventKind.UPDATED True

Functions

create_event 

create_event(
    kind: EventKind,
    payload: Any,
    event_id: str | None = None,
) -> EventEnvelope

Create an event envelope.

Parameters:

Name Type Description Default
kind EventKind

Event kind (created, updated, deleted).

 required
payload Any

Event payload (must be JSON-serializable).

 required
event_id str | None

Optional ID; if omitted, a UUID is generated.

 None

Returns:

Type Description
EventEnvelope

Event envelope dict.

Raises:

Type Description
ValueError

If kind is not an EventKind member or payload is None.
Example

from events_py import EventKind, create_event ev = create_event(EventKind.CREATED, {"name": "foo"}) ev["kind"] 'created'

Source code in libs/events-py/src/events_py/models.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def create_event(
    kind: EventKind,
    payload: Any,
    event_id: str | None = None,
) -> EventEnvelope:
    """Create an event envelope.

    Args:
        kind: Event kind (created, updated, deleted).
        payload: Event payload (must be JSON-serializable).
        event_id: Optional ID; if omitted, a UUID is generated.

    Returns:
        Event envelope dict.

    Raises:
        ValueError: If kind is not an EventKind member or payload is None.

    Example:
        >>> from events_py import EventKind, create_event
        >>> ev = create_event(EventKind.CREATED, {"name": "foo"})
        >>> ev["kind"]
        'created'
    """
    if not isinstance(kind, EventKind):
        raise ValueError(f"kind must be an EventKind member, got {kind!r}")
    if payload is None:
        raise ValueError("payload must not be None")
    return {
        "id": event_id or str(uuid4()),
        "kind": kind.value,
        "payload": payload,
        "timestamp": datetime.now(timezone.utc).isoformat(),
    }

Modules

models

Event envelope and kind definitions.

Classes
EventKind

Bases: str, Enum

Supported event kinds for Rune service events.

Defines the three base event types. Rune-specific kinds (e.g. TRAINING_STARTED) will be added in service phases.

Example

EventKind.CREATED.value 'created' EventKind("updated") == EventKind.UPDATED True

EventEnvelope

Bases: TypedDict

Base event envelope for Pub/Sub or internal events.

All events share this structure. The payload field carries event-specific data as a JSON-serializable dict.

Example

envelope: EventEnvelope = { ... "id": "evt-001", ... "kind": "created", ... "payload": {"name": "adapter-1"}, ... "timestamp": "2026-01-01T00:00:00+00:00", ... }

Functions
create_event 
create_event(
    kind: EventKind,
    payload: Any,
    event_id: str | None = None,
) -> EventEnvelope

Create an event envelope.

Parameters:

Name Type Description Default
kind EventKind

Event kind (created, updated, deleted).

 required
payload Any

Event payload (must be JSON-serializable).

 required
event_id str | None

Optional ID; if omitted, a UUID is generated.

 None

Returns:

Type Description
EventEnvelope

Event envelope dict.

Raises:

Type Description
ValueError

If kind is not an EventKind member or payload is None.
Example

from events_py import EventKind, create_event ev = create_event(EventKind.CREATED, {"name": "foo"}) ev["kind"] 'created'

Source code in libs/events-py/src/events_py/models.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def create_event(
    kind: EventKind,
    payload: Any,
    event_id: str | None = None,
) -> EventEnvelope:
    """Create an event envelope.

    Args:
        kind: Event kind (created, updated, deleted).
        payload: Event payload (must be JSON-serializable).
        event_id: Optional ID; if omitted, a UUID is generated.

    Returns:
        Event envelope dict.

    Raises:
        ValueError: If kind is not an EventKind member or payload is None.

    Example:
        >>> from events_py import EventKind, create_event
        >>> ev = create_event(EventKind.CREATED, {"name": "foo"})
        >>> ev["kind"]
        'created'
    """
    if not isinstance(kind, EventKind):
        raise ValueError(f"kind must be an EventKind member, got {kind!r}")
    if payload is None:
        raise ValueError("payload must not be None")
    return {
        "id": event_id or str(uuid4()),
        "kind": kind.value,
        "payload": payload,
        "timestamp": datetime.now(timezone.utc).isoformat(),
    }