[CHA-2585] feat: add migration guide from stream-chat-python#220
[CHA-2585] feat: add migration guide from stream-chat-python#220
Conversation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdds a new "Migrating from stream-chat?" section to the README and a seven-page Python migration guide (setup/auth, users, channels, messages & reactions, moderation, devices) with before/after examples and explicit API/type mapping notes. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR adds a comprehensive migration guide for developers moving from the stream-chat Python SDK to the getstream SDK. The guide covers the key API differences, provides side-by-side code examples for all major use cases, and is linked from the main README.md.
Changes:
- Added a new
docs/migration-from-stream-chat-python/directory with a top-level README and six topic-specific migration guides (setup/auth, users, channels, messages/reactions, moderation, and devices). - Updated the root
README.mdto include a "Migrating from stream-chat?" section pointing to the new guide.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
README.md |
Adds a brief "Migrating from stream-chat?" section with a link to the new guide. |
docs/migration-from-stream-chat-python/README.md |
Overview: key differences table, quick before/after example, and a guide index table. |
docs/migration-from-stream-chat-python/01-setup-and-auth.md |
Installation, client init, async client, token creation, and env vars. |
docs/migration-from-stream-chat-python/02-users.md |
Upsert, custom fields, query, partial update, deactivate, and delete users. |
docs/migration-from-stream-chat-python/03-channels.md |
Create, query, manage members, update, partial update, and delete channels. |
docs/migration-from-stream-chat-python/04-messages-and-reactions.md |
Send, update, delete messages, thread replies, and reaction CRUD. |
docs/migration-from-stream-chat-python/05-moderation.md |
Add/demote moderators, ban, unban, shadow ban, mute, and unmute. |
docs/migration-from-stream-chat-python/06-devices.md |
Add (APN/Firebase/VoIP), list, and delete push devices. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Called on `client.chat` sub-client instead of the channel object | ||
| - Uses `ReactionRequest` instead of a plain dict | ||
| - `count` field renamed to `score` | ||
| - `user_id` is not needed at the server level; use `enforce_unique` to replace existing reactions |
There was a problem hiding this comment.
The explanation at line 254 is misleading: it conflates two unrelated concepts. user_id being omitted from send_reaction() (it's a top-level parameter on ReactionRequest when needed) and enforce_unique=False being passed are independent. enforce_unique controls whether a user can send multiple reactions of the same type — it does not replace or substitute for user_id. The note should clarify that the user_id can be passed inside ReactionRequest(user_id=...) if needed, and separately explain that enforce_unique controls reaction deduplication behavior.
| **Key changes:** | ||
| - Called on `client.moderation` sub-client | ||
| - `target_id` renamed to `target_user_id` | ||
| - Requires `unbanned_by_id` |
There was a problem hiding this comment.
The "Key changes" note says "Requires unbanned_by_id", but looking at the actual client.moderation.unban() method signature, unbanned_by_id is an optional parameter (Optional[str] = None), not a required one. This note could mislead users into thinking a call without unbanned_by_id will fail.
| **After (getstream):** | ||
|
|
||
| ```python | ||
| from getstream import Stream | ||
| from getstream.models import ChannelInput, ChannelMemberRequest | ||
|
|
||
| client = Stream(api_key="your-api-key", api_secret="your-api-secret") | ||
| channel = client.chat.channel("messaging") | ||
| response = channel.get_or_create( | ||
| data=ChannelInput( | ||
| created_by_id="user-1", | ||
| members=[ | ||
| ChannelMemberRequest(user_id="user-1"), | ||
| ChannelMemberRequest(user_id="user-2"), | ||
| ], | ||
| ) | ||
| ) |
There was a problem hiding this comment.
The "Create a Distinct Channel (by Members)" example has two code bugs:
-
client.chat.channel("messaging")is called without anidargument, but theChatClient.channel(call_type, id)method requiresid: str(no default value). This will raise aTypeError. -
Even if the channel is created with
id=None, the subsequentchannel.get_or_create()call internally delegates toget_or_create_channel(type=..., id=None, ...), which constructs the URL as/api/v2/chat/channels/messaging/None/query— not the correct distinct-channel endpoint.
For a distinct channel (no predetermined ID, members-based identity), the correct API is client.chat.get_or_create_distinct_channel(type="messaging", data=ChannelInput(...)), which uses the endpoint /api/v2/chat/channels/{type}/query.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/migration-from-stream-chat-python/05-moderation.md`:
- Around line 139-142: The docs currently state that unbanned_by_id is required
for client.moderation.unban(), but the implementation declares unbanned_by_id as
optional; update the migration note to stop marking unbanned_by_id as required —
instead state it is optional (or omit it), and adjust the bullet list for
client.moderation and the target_user_id rename to reflect that unbanned_by_id
is not mandatory when calling client.moderation.unban().
In `@docs/migration-from-stream-chat-python/README.md`:
- Around line 5-9: The README currently asserts that "`stream-chat` will enter
maintenance mode (critical fixes only)" and other product-lifecycle claims
without citing official Stream sources; remove or replace these unsupported
lifecycle statements (both the occurrence at the top and the one reported at
line 64) by either linking to an official Stream announcement/README/PyPI
release notes that explicitly states this status or by deleting the
maintenance-mode phrasing and replacing it with a neutral, verifiable statement
such as "`getstream` is the actively developed SDK; check Stream's official docs
or the stream-chat-python repo for current support status" to avoid making
unverified predictions about `stream-chat`.
In `@README.md`:
- Around line 37-39: Update the Markdown link in README.md that currently points
to the relative docs path `docs/migration-from-stream-chat-python/README.md` so
it uses the absolute GitHub URL (for example
`https://github.com/GetStream/stream-py/blob/main/docs/migration-from-stream-chat-python/README.md`);
specifically replace the link target in the "Migration Guide" markdown link in
the "Migrating from stream-chat?" section so the README long description on PyPI
resolves correctly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 5a7424ad-ced8-4605-816f-0455ed5812b7
📒 Files selected for processing (8)
README.mddocs/migration-from-stream-chat-python/01-setup-and-auth.mddocs/migration-from-stream-chat-python/02-users.mddocs/migration-from-stream-chat-python/03-channels.mddocs/migration-from-stream-chat-python/04-messages-and-reactions.mddocs/migration-from-stream-chat-python/05-moderation.mddocs/migration-from-stream-chat-python/06-devices.mddocs/migration-from-stream-chat-python/README.md
| - `getstream` is the actively developed, long-term-supported SDK | ||
| - Covers Chat, Video, Moderation, and Feeds in a single package | ||
| - Strongly typed models generated from the official OpenAPI spec | ||
| - `stream-chat` will enter maintenance mode (critical fixes only) | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Has Stream officially announced that the stream-chat Python SDK is entering maintenance mode / critical-fixes-only support, and that existing integrations will continue working? Please provide the official announcement or documentation page.
💡 Result:
I couldn’t find any official Stream announcement or documentation stating that the stream-chat Python SDK has entered “maintenance mode / critical-fixes-only” while guaranteeing existing integrations will continue working.
What Stream does publish (officially) indicates the opposite:
- Stream still presents Python as a supported server-side Chat SDK in the Chat docs and continues to document installing/using it via
pip install stream-chat. [1] - The official
GetStream/stream-chat-pythonrepository README does not mention maintenance mode / critical-fixes-only support. [2] - The
stream-chatpackage on PyPI shows ongoing releases (e.g., versions released in 2025), which is inconsistent with a “critical-fixes-only” freeze. [3]
Official pages checked (no maintenance-mode statement found):
- Stream Chat Python docs (Backend): [1]
stream-chat-pythonGitHub README: [2]- PyPI release history for
stream-chat: [3]
Sources
[1] (getstream.io)
[2] (github.com)
[3] (pypi.org)
Citations:
- 1: https://getstream.io/chat/docs/python/
- 2: https://github.com/GetStream/stream-chat-python/blob/master/README.md
- 3: https://pypi.org/project/stream-chat/3.5.0/?utm_source=openai
Remove or replace unsupported product-lifecycle claims with official sources.
The statements that stream-chat "will enter maintenance mode (critical fixes only)" and related support claims lack official Stream documentation or announcements. In fact, official sources contradict this:
- Stream's Chat docs still list Python as a supported server-side SDK
- The official
stream-chat-pythonrepository README contains no maintenance-mode notice - PyPI shows active releases through 2025, inconsistent with a critical-fixes-only stance
Either link to official Stream announcements backing these claims, or remove the unsupported lifecycle predictions to avoid misleading users about the SDK's future.
Also applies to: line 64
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/migration-from-stream-chat-python/README.md` around lines 5 - 9, The
README currently asserts that "`stream-chat` will enter maintenance mode
(critical fixes only)" and other product-lifecycle claims without citing
official Stream sources; remove or replace these unsupported lifecycle
statements (both the occurrence at the top and the one reported at line 64) by
either linking to an official Stream announcement/README/PyPI release notes that
explicitly states this status or by deleting the maintenance-mode phrasing and
replacing it with a neutral, verifiable statement such as "`getstream` is the
actively developed SDK; check Stream's official docs or the stream-chat-python
repo for current support status" to avoid making unverified predictions about
`stream-chat`.
| ## Migrating from stream-chat? | ||
|
|
||
| If you are currently using [`stream-chat`](https://github.com/GetStream/stream-chat-python), we have a detailed migration guide with side-by-side code examples for common Chat use cases. See the [Migration Guide](docs/migration-from-stream-chat-python/README.md). |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -e
fd '^(pyproject\.toml|setup\.cfg|setup\.py)$' -x sh -c '
echo "== {} ==";
rg -n -C2 "readme|long_description|long_description_content_type" "{}" || true
'Repository: GetStream/stream-py
Length of output: 214
Switch the migration guide link to an absolute GitHub URL.
README.md is configured as the package long description in pyproject.toml, which means it displays on PyPI. The relative link docs/migration-from-stream-chat-python/README.md will be broken for users viewing the docs on PyPI, since the docs directory is not included in the distributed package. Use an absolute GitHub URL instead: https://github.com/GetStream/stream-py/blob/main/docs/migration-from-stream-chat-python/README.md or similar.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 37 - 39, Update the Markdown link in README.md that
currently points to the relative docs path
`docs/migration-from-stream-chat-python/README.md` so it uses the absolute
GitHub URL (for example
`https://github.com/GetStream/stream-py/blob/main/docs/migration-from-stream-chat-python/README.md`);
specifically replace the link target in the "Migration Guide" markdown link in
the "Migrating from stream-chat?" section so the README long description on PyPI
resolves correctly.
Note
Low Risk
Documentation-only change adding migration guidance; no runtime or API behavior is modified.
Overview
Adds a new migration guide for users moving from
stream-chattogetstream. The README now includes a dedicated “Migrating from stream-chat?” section pointing to the new docs.The new
docs/migration-from-stream-chat-python/pages provide side-by-side code examples and method/parameter/model mappings for setup/auth, users, channels, messages/reactions, moderation, and devices (highlighting the shift toclient.chat/client.moderationsub-clients and typed request/response models).Written by Cursor Bugbot for commit 221d9f1. This will update automatically on new commits. Configure here.
Summary by CodeRabbit