Official Python SDK for Stream
build PyPI version PyPI - Python Version
Check out our:
- β Chat API
- π± Video API
- π Activity Feeds
- Video call creation and management
- Chat session creation and management
- Token generation for user authentication
To install the Stream Client Library, run the following command:
pip install getstream
# or if like us, you fell in love with uv
uv add getstreamIf you want to build audio or video AI integrations, make sure to check Vision-Agents:
pip install getstream[webrtc] # or using uv uv add 'getstream[webrtc]'
To get started, you need to import the Stream class from the library and create a new instance with your API key and secret:
from getstream import Stream client = Stream(api_key="your_api_key", api_secret="your_api_secret")
from getstream.models import UserRequest # sync two users using the update_users method, both users will get insert or updated client.upsert_users( UserRequest( id="tommaso-id", name="tommaso", role="admin", custom={"country": "NL"} ), UserRequest( id="thierry-id", name="thierry", role="admin", custom={"country": "US"} ), ) # Create a JWT token for the user to connect client-side (e.g. browser/mobile app) token = client.create_token("tommaso-id")
To create a video call, use the client.video.call method:
import uuid from getstream.models import ( CallRequest, MemberRequest, ) call = client.video.call("default", uuid.uuid4()) call.get_or_create( data=CallRequest( created_by_id="tommaso-id", members=[ MemberRequest(user_id="thierry-id"), MemberRequest(user_id="tommaso-id"), ], ), )
Many calls return a StreamResponse object, with the specific dataclass for the method call nested inside. You can access this via:
response: StreamResponse[StartClosedCaptionsResponse] = call.start_closed_captions() response.data # Gives the StartClosedCaptionsResponse model
# Video: update settings for a call type # Chat: update settings for a channel type
To work with chat sessions, use the client.chat object and implement the desired chat methods in the Chat class:
chat_instance = client.chat # TODO: implement and call chat-related methods with chat_instance
We use uv to manage dependencies and run tests.
Prerequisites:
- Python 3.9+ (recommended: 3.12.2)
- uv package manager
Setup:
# 1. Clone and enter the repository git clone https://github.com/GetStream/stream-py.git cd stream-py # 2. Create virtual environment and install everything uv venv --python 3.12.2 uv sync --all-extras --dev # 3. Set up pre-commit hooks pre-commit install # 4. Create environment file for API credentials cp .env.example .env # Edit .env with your Stream API credentials
Run all tests:
uv run pytest # Everything uv run pytest -v # Verbose output uv run pytest -x # Stop on first failure
Run specific test suites:
# Main package tests uv run pytest tests/ uv run pytest tests/test_video.py # Specific test file
Test with coverage:
uv run pytest --cov=getstream --cov-report=html
Test configuration:
- Configuration:
pytest.ini - Fixtures:
tests/fixtures.py - Test assets:
tests/assets/(keep files < 256KB)
Testing best practices:
- Write tests as simple Python functions with assert statements
- Use fixtures from
tests/fixtures.pyfor common setup - Place test assets in
tests/assets/directory - Avoid mocks unless specifically required
- Always run tests from the project root directory
CI considerations:
import pytest @pytest.mark.skip_in_ci def test_something(): # This test will be skipped in GitHub Actions ...
Install new dependency:
# Main package uv add "new-package>=1.0.0" # Plugin-specific cd getstream/plugins/stt/my-plugin/ uv add "plugin-specific-dep>=2.0.0" # WebRTC-related (add to webrtc extra) # Edit pyproject.toml [project.optional-dependencies] webrtc section
Run linting and formatting:
uv run ruff check getstream/ tests/ # Check for issues uv run ruff format getstream/ tests/ # Format code uv run pre-commit run --all-files # Run all hooks
Generate code:
./generate_webrtc.sh # Regenerate WebRTC bindingsNote: regenerating code requires access to internal code available only to Stream developers
Test failures:
# Run with verbose output uv run pytest -v -s # Run specific test uv run pytest tests/test_video.py::test_specific_function -v
This project is licensed under the MIT License.
Contributions are welcome! Please read the contributing guidelines to get started.