# Events (/sdks/python/reference/events)



Publish events with `publish_event` and consume them through `subscribe_to_events`, supplying `EventsSubscription` plus an `AsyncCancellationToken` for shutdown.

## publish\_event [#publish_event]

```python
await client.publish_event(message: EventMessage) -> None
```

**EventMessage fields:**

| Field      | Type             | Required      | Description    |
| ---------- | ---------------- | ------------- | -------------- |
| `channel`  | `str`            | Yes           | Target channel |
| `body`     | `bytes`          | Conditional\* | Payload        |
| `metadata` | `str`            | Conditional\* | Text metadata  |
| `tags`     | `dict[str, str]` | No            | Key/value tags |

\*At least one of `body` or `metadata` must be set.

**Returns:** `None` — raises on failure.

**Throws:** `KubeMQError` — validation or transport errors.

## subscribe\_to\_events [#subscribe_to_events]

`subscribe_to_events` is an async generator — iterate it with `async for`:

```python
async for event in client.subscribe_to_events(
    subscription=EventsSubscription(...),
    cancellation_token=token,
):
    process(event)
```

**EventsSubscription fields:**

| Field                       | Type       | Required | Description      |
| --------------------------- | ---------- | -------- | ---------------- |
| `channel`                   | `str`      | Yes      | Channel name     |
| `group`                     | `str`      | No       | Consumer group   |
| `on_receive_event_callback` | `Callable` | Yes      | Delivery handler |
| `on_error_callback`         | `Callable` | Yes      | Error handler    |

## Quick Usage [#quick-usage]

```python title="events.py"
await client.publish_event(
    EventMessage(channel="events.demo", body=b"hello")
)
```

## See Also [#see-also]

* [Events Examples](/sdks/python/how-to/events/)
* [Events pattern](/learn/events/getting-started)
* [Python SDK Getting Started](/sdks/python)