Installation

This SDK is the server half of your integration. Your users read and write feeds from your app with a client SDK, and anything that needs a connected user or a live WebSocket belongs there: the state layer, device push registration, and client-side error handling. See the client-side overview for what lives there. Token signing stays on this side, because it needs your API secret.

pip install getstream

GitHub repository: https://github.com/GetStream/stream-py. Feel free to submit bug reports and feature requests.

The package is tested against these environments:

Python 3.7+
Python 3.8+
Python 3.9+
Python 3.10+
Python 3.11+
Python 3.12+

To create a client, you'll need your API key and secret. Both of them can be found in your Stream Dashboard.

You can optionally configure request timeouts and the HTTP connection pool. The default request timeout is 30 seconds.

import stream

# Create client with default settings (30s request timeout)
client = stream.connect('api_key', 'api_secret')

# Or create client with a custom request timeout (in seconds)
client = stream.connect('api_key', 'api_secret', request_timeout=30.0)

# Get the feeds client
feeds_client = client.feeds

# Your feeds operations here...

Alternative initialization

You can also initialize the client using environment variables:

import os
import stream

# Set environment variables
os.environ['STREAM_API_KEY'] = 'your_api_key'
os.environ['STREAM_API_SECRET'] = 'your_api_secret'

# Initialize client from environment
client = stream.connect_from_env()

# Get the feeds client
feeds_client = client.feeds

Connection pool and timeouts

The shared defaults and tuning options are documented on Connection pooling; this section covers the Python specifics.

The SDK keeps a pooled, keep-alive HTTP client (httpx). Tune it with constructor arguments:

Argument	Default	Description
`request_timeout` (alias `timeout`)	`30.0`	Per-request timeout in seconds.
`max_conns_per_host`	`5`	Maximum concurrent connections per host.
`idle_timeout`	`55.0`	Idle connection lifetime in seconds.
`connect_timeout`	`10.0`	TCP + TLS handshake timeout in seconds.

client = stream.connect(
    'api_key', 'api_secret',
    request_timeout=30.0,
    max_conns_per_host=10,
    idle_timeout=55.0,
    connect_timeout=10.0,
)

Each knob can also be set via an environment variable: STREAM_REQUEST_TIMEOUT (or STREAM_TIMEOUT), STREAM_MAX_CONNS_PER_HOST, STREAM_IDLE_TIMEOUT, and STREAM_CONNECT_TIMEOUT.

To supply your own HTTP client, pass http_client (an httpx.Client) or a custom transport. When http_client is set, the pool arguments above are not applied.

Quick Start

Architecture & Benchmark