Streams ClientPython SDK
Bases: BaseRestClient
The streams client publishes to and reads from durable topics. Unlike runs.subscribe_to_stream, topics are stored, independent of any run, and readers can resume from a cursor.
Methods:
| Name | Description |
|---|---|
aio_reset | Make subscribe calls without a cursor start after cursor, or the topic's latest message. Readers already iterating, and any call with a cursor, are unaffected. |
aio_topic_metadata | Describe a topic's retained messages. Raises a NOT_FOUND gRPC error for a topic nothing was published to. |
publish | Publish a message to a topic, returning once it is stored. A client's messages to a topic are delivered in the order publish was called. Publishes to a topic share requests: everything queued while one is in flight goes out in the next, and batch_timeout holds a message up to that long for more to join it. Cancelling a publish before its request goes out drops the message; once the request is sent, it may still be stored. |
reset | Make subscribe calls without a cursor start after cursor, or the topic's latest message. Readers already iterating, and any call with a cursor, are unaffected. |
subscribe | Yield a topic's messages after cursor, or from the oldest retained (or, once the topic is reset, after the reset). If the connection drops, it resubscribes from the last message yielded, so nothing is skipped or repeated. Ends when the server hangs up an idle subscription or the caller stops iterating; raises on errors a retry can't fix, such as an expired cursor. |
topic_metadata | Describe a topic's retained messages. Raises a NOT_FOUND gRPC error for a topic nothing was published to. |
Functions
aio_reset
Make subscribe calls without a cursor start after cursor, or the topic's latest message. Readers already iterating, and any call with a cursor, are unaffected.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
topic | str | The topic to reset. | required |
namespace | str | The topic's namespace; the empty namespace by default. | '' |
cursor | str | None | A cursor read off one of the topic's events to reset to, instead of its latest message. | None |
Returns:
| Type | Description |
|---|---|
None | None |
aio_topic_metadata
Describe a topic's retained messages. Raises a NOT_FOUND gRPC error for a topic nothing was published to.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
topic | str | The topic to describe. | required |
namespace | str | The topic's namespace; the empty namespace by default. | '' |
Returns:
| Type | Description |
|---|---|
StreamTopicMetadata | The topic's metadata. |
publish
Publish a message to a topic, returning once it is stored. A client's messages to a topic are delivered in the order publish was called. Publishes to a topic share requests: everything queued while one is in flight goes out in the next, and batch_timeout holds a message up to that long for more to join it. Cancelling a publish before its request goes out drops the message; once the request is sent, it may still be stored.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
topic | str | The topic to publish to. | required |
message | bytes | str | The message payload. A string is encoded as UTF-8. | required |
namespace | str | The topic's namespace; the empty namespace by default. | '' |
batch_timeout | timedelta | None | How long the message may wait for later publishes to the same topic to share its request, bounding the latency batching adds. By default, it is sent as soon as no other request to the topic is in flight. | None |
Returns:
| Type | Description |
|---|---|
None | None |
Raises:
| Type | Description |
|---|---|
ValueError | The payload is empty or over 64 MiB, or batch_timeout is negative. |
reset
Make subscribe calls without a cursor start after cursor, or the topic's latest message. Readers already iterating, and any call with a cursor, are unaffected.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
topic | str | The topic to reset. | required |
namespace | str | The topic's namespace; the empty namespace by default. | '' |
cursor | str | None | A cursor read off one of the topic's events to reset to, instead of its latest message. | None |
Returns:
| Type | Description |
|---|---|
None | None |
subscribe
Yield a topic's messages after cursor, or from the oldest retained (or, once the topic is reset, after the reset). If the connection drops, it resubscribes from the last message yielded, so nothing is skipped or repeated. Ends when the server hangs up an idle subscription or the caller stops iterating; raises on errors a retry can't fix, such as an expired cursor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
topic | str | The topic to read from. | required |
namespace | str | The topic's namespace; the empty namespace by default. | '' |
cursor | str | None | A cursor read off a previous event, to resume right after it. | None |
Returns:
| Type | Description |
|---|---|
AsyncGenerator[StreamEvent, None] | An async iterator of the topic's events. |
Raises:
| Type | Description |
|---|---|
Exception | An error a resubscribe can't fix, such as an expired cursor (OUT_OF_RANGE) or a tenant without durable streams (PERMISSION_DENIED). |
topic_metadata
Describe a topic's retained messages. Raises a NOT_FOUND gRPC error for a topic nothing was published to.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
topic | str | The topic to describe. | required |
namespace | str | The topic's namespace; the empty namespace by default. | '' |
Returns:
| Type | Description |
|---|---|
StreamTopicMetadata | The topic's metadata. |
Last updated on October 29, 2026