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

zeke · 2025-10-01T05:12:29Z

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

linear · 2025-10-01T05:12:32Z

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.

UPGRADING.md

aron · 2025-10-01T13:49:55Z

UPGRADING.md

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


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

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?

UPGRADING.md

zeke · 2025-10-01T16:41:18Z

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.

…memory

zeke · 2025-10-01T17:00:55Z

Thanks for the close inspection, @aron 💛

This is ready for another look.

UPGRADING.md

…=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.

zeke · 2025-10-10T20:28:38Z

I'm gonna ship this. We can iterate.

zeke requested a review from a team as a code owner October 1, 2025 05:12

docs: remove unnecessary implementation detail about Prefer headers

675922a

zeke requested review from aron, dgellow and ethulia October 1, 2025 05:19

aron reviewed Oct 1, 2025

View reviewed changes

zeke added 2 commits October 1, 2025 09:38

docs: clarify "resource methods" terminology in migration guide

c0d4a38

docs: add section links to migration checklist

e979d1b