getstream/stream-py

Official Python API Client for Stream Chat and Video

Official Python SDK for Stream

Features

• Video call creation and management
• Chat session creation and management
• Token generation for user authentication

Installation

To install the Stream Client Library, run the following command:

pip install getstream

Usage

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")

Users and Authentication

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")

Video API - Calls

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"),
        ],
    ),
)

App configuration

# Video: update settings for a call type

# Chat: update settings for a channel type

Chat API - Channels

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

Development

We use poetry to manage dependencies and run tests. It's a package manager for Python that allows you to declare the libraries your project depends on and manage them. To install the development dependencies, run the following command:

poetry install
pre-commit install

To activate the virtual environment, run the following command:

poetry shell

To run tests, create a .env using the .env.example and adjust it to have valid API credentials

poetry run pytest tests/ getstream/

Before pushing changes make sure to have git hooks installed correctly, so that you get linting done locally pre-commit install

You can also run the code formatting yourself if needed:

poetry run ruff format getstream/ tests/

Writing new tests

pytest is used to run tests and to inject fixtures, simple tests can be written as simple python functions making assert calls. Make sure to have a look at the available test fixtures under tests/fixtures.py

Generate code from spec

To regenerate the Python source from OpenAPI, just run the ./generate.sh script from this repo.

Note

Code generation currently relies on tooling that is not publicly available, only Stream devs can regenerate SDK source code from the OpenAPI spec.

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please read the contributing guidelines to get started.

stream-py's Issues

Request for feedback on the python client

Hi there. I am the author of the openapi-generator python client which has now moved to https://github.com/openapi-json-schema-tools/openapi-json-schema-generator
Your repo uses this client.
I want to make sure that I understand what is important to the end users of the python client. If you have some time can you provide some feedback on what features you value in the generator, any pain points and what you would like improved?
If you could provide your feedback here it would help with future improvements. Thank you!

httpx getting a unknown header when try creating user for calls

I'm using getstream SDK for voice & video call implementation. I've implemented all according to your documentation, but still in the client.upsert_users method with a single user getting an error from handle_request(). I've downgraded my httpx version to support the SDK too.

this is the code snippet that I'm trying

client = Stream(api_key=self._initialise_secrets().get("stream_api_key"), api_secret=self._initialise_secrets().get("stream_api_secret_key"))
        self.logger.info(f'Creating user {effective_user_id} with payload {user_payload}')
        custom_payload = user_payload.get('custom')
        name = user_payload.get('name')
        image = user_payload.get('image')
        users = {}
        user = UserRequest(
            id=effective_user_id, 
            role="user", 
            custom=custom_payload, 
            name=name,
            image=image,
        )
        users[user.id] = user
        client.upsert_users(users=users)

This is the error I'm getting atm

client.upsert_users(users=users)
   File "/opt/python/getstream/sync/stream.py", line 88, in upsert_users
   return self._users.upsert_users(users=users)
   File "/opt/python/getstream/users/sync/client.py", line 38, in upsert_users
   chat_response = self.post(
   File "/opt/python/getstream/sync/base.py", line 114, in post
   response = self.client.post(
   File "/opt/python/httpx/_client.py", line 1109, in post
   return self.request(
   File "/opt/python/httpx/_client.py", line 787, in request
   return self.send(
   File "/opt/python/httpx/_client.py", line 878, in send
   response = self._send_handling_auth(
   File "/opt/python/httpx/_client.py", line 908, in _send_handling_auth
   response = self._send_handling_redirects(
   File "/opt/python/httpx/_client.py", line 947, in _send_handling_redirects
   response = self._send_single_request(request, timeout)
   File "/opt/python/httpx/_client.py", line 983, in _send_single_request
   (status_code, headers, stream, extensions) = transport.handle_request(
   TypeError: handle_request() got an unexpected keyword argument 'headers'