Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

docs: add migration guide for upgrading from v1 to v2 #76

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

Conversation

@zeke
Copy link
Member

@zeke zeke commented Oct 1, 2025 •
edited
Loading

This PR adds UPGRADING.md, a guide for users upgrading from the v1 SDK to v2.

The guide documents all user-facing differences between the SDKs, with code samples showing old and new usage patterns.

Companion release notes: https://www.notion.so/replicate/Python-SDK-2-0-Stainless-release-notes-27d279e7ce4b808cab5bd3554598308b?source=copy_link

Key differences covered

  • Client initialization: Replicate() vs Client(), bearer_token vs api_token
  • Prediction methods: resource methods instead of instance methods (wait(), cancel(), reload())
  • Async support: AsyncReplicate client instead of async_* methods
  • Error handling: granular exception types for each HTTP status code
  • Pagination: built-in auto-pagination with has_next_page() and get_next_page()
  • Models API: keyword arguments required throughout
  • New features: models listing, better type safety, HTTP client customization
  • Removed features: instance methods, positional arguments

Testing locally

gh repo clone replicate/replicate-python-stainless
cd replicate-python-stainless
gh pr checkout 75
cat UPGRADING.md

Prompts

Implement https://linear.app/replicate/issue/DP-684/write-a-migration-guide-for-users-upgrading-from-v1-to-v2
read comments from the linear ticket and make those changes too

Fixes https://linear.app/replicate/issue/DP-684 

This PR adds UPGRADING.md, a comprehensive migration guide for users
upgrading from the v1 Replicate Python SDK to v2.
The guide covers:
- Client initialization changes (Replicate vs Client, bearer_token vs api_token)
- Prediction lifecycle changes (resource methods vs instance methods)
- Async support differences (AsyncReplicate client vs async_ methods)
- Error handling improvements (granular exception types)
- Pagination enhancements (auto-pagination)
- Models and versions API changes (keyword arguments)
- File handling differences
- New features in v2 (models listing, better types, HTTP customization)
- Removed features (instance methods, positional arguments)
- Migration strategy recommendations
Addresses DP-684
@zeke zeke requested a review from a team as a code owner October 1, 2025 05:12
Copy link

linear bot commented Oct 1, 2025

DP-684 Write a migration guide for users upgrading from v1 to v2

The v2 Replicate Python SDK has some differences from the v1 SDK.

Let's write a migration guide that's useful for both humans and agents. It should enumerate all the user-facing differences between the old and new clients, with code samples of the old usage and new usage patterns, along with summaries of the differences and lists of steps required to migrate from each old usage to each new usage.

Implementation details

The old codebase is defined in the replicate-python directory. It has a README.md with details about client usage and it has some tests that can be used for reference.

The new codebase is defined in the replicate-python-stainless directory. It also has a README and extensive tests.

Add the new migration guide as UPGRADING.md

Writing style

Do not use excessive headings in the document. No smaller than H3.

Do not use bold for emphasis.

Use sentence case for headings, not title case.

@zeke zeke requested review from aron, dgellow and ethulia October 1, 2025 05:19
Comment on lines +390 to +407
# Get model (keyword arguments required)
model = replicate.models.get(
model_owner="owner",
model_name="name"
)

# Get version (no shorthand via model object)
version = replicate.models.versions.get(
model_owner="owner",
model_name="name",
version_id="version_id"
)

# List versions
versions = replicate.models.versions.list(
model_owner="owner",
model_name="name"
)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bit of a shame. Is there no sugar we can add here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could definitely add sugar.

In fact I opened a ticket about it: https://linear.app/replicate/issue/DP-656/add-backward-compatibility-for-modelsgetownername-syntax

It's just a question of whether we want to or not. And if we do, should we document it? Or would the sugar be there just for the sake of minimizing breakage of existing code?

This comment was marked as duplicate.

zeke

This comment was marked as duplicate.

Copy link
Member Author

zeke commented Oct 1, 2025

Sorry for the thrashing comment spam here. Trying to get Claude to properly address and respond to inline PR review comments one at a time.

zeke

This comment was marked as duplicate.

zeke

This comment was marked as duplicate.

zeke

This comment was marked as duplicate.

zeke

This comment was marked as duplicate.

zeke

This comment was marked as duplicate.

@zeke zeke requested a review from aron October 1, 2025 16:59
Copy link
Member Author

zeke commented Oct 1, 2025

Thanks for the close inspection, @aron 💛

This is ready for another look.

@zeke zeke force-pushed the dp-684-write-a-migration-guide-for-users-upgrading-from-v1-to-v2 branch from 8fec3d4 to f1dc6b0 Compare October 1, 2025 17:33
@zeke zeke requested a review from bfirsh October 1, 2025 20:33
@stainless-app stainless-app bot force-pushed the next branch 2 times, most recently from ea6fa72 to 26638e7 Compare October 10, 2025 16:38
zeke added 5 commits October 10, 2025 11:40 
...=True
Update migration guide to reflect that replicate.use() with streaming=True
is the preferred approach for streaming in v2. Mention that replicate.stream()
still works but is deprecated, without showing a code example.
Copy link
Member Author

zeke commented Oct 10, 2025

I'm gonna ship this. We can iterate.

@zeke zeke merged commit 5f57722 into next Oct 10, 2025
6 checks passed
@zeke zeke deleted the dp-684-write-a-migration-guide-for-users-upgrading-from-v1-to-v2 branch October 10, 2025 20:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@dgellow dgellow dgellow left review comments

@ethulia ethulia ethulia left review comments

@aron aron Awaiting requested review from aron

@bfirsh bfirsh Awaiting requested review from bfirsh

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

AltStyle によって変換されたページ (->オリジナル) /