Add Python SDK beta documentation page#1775
Conversation
Slack-Thread: https://vercel.slack.com/archives/C0AG7R4PU22/p1776354109663229?thread_ts=1776354109.663229&cid=C0AG7R4PU22 Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>
|
🧪 E2E Test Results❌ Some tests failed Summary
❌ Failed Tests▲ Vercel Production (53 failed)astro (5 failed):
example (7 failed):
fastify (3 failed):
hono (3 failed):
nextjs-turbopack (6 failed):
nextjs-webpack (4 failed):
nitro (6 failed):
nuxt (7 failed):
sveltekit (9 failed):
vite (3 failed):
🌍 Community Worlds (98 failed)mongodb (15 failed):
redis (15 failed):
turso (68 failed):
Details by Category❌ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
❌ 🌍 Community Worlds
✅ 📋 Other
❌ Some E2E test jobs failed:
Check the workflow run for details. |
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro Stream Benchmarks (includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro 10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
|
There was a problem hiding this comment.
Pull request overview
Adds a dedicated “Python SDK” page to the docs Getting Started section and surfaces it prominently in the Getting Started framework grid, including a new Python logo icon export.
Changes:
- Added
docs/content/docs/getting-started/python.mdxwith a beta warning and Python concept/code examples. - Updated Getting Started index to include a Python SDK card (with a “Beta” badge) and place it first.
- Added a Python SVG icon export in
frameworks.tsx(and reformatted that file’s string quoting).
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/content/docs/getting-started/python.mdx | New Python SDK page content with beta callout and concept sections. |
| docs/content/docs/getting-started/index.mdx | Adds the Python SDK card + Beta badge to the Getting Started grid. |
| docs/app/[lang]/(home)/components/frameworks.tsx | Exports a new Python SVG icon for use in docs UI. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| <Card href="/docs/getting-started/python"> | ||
| <div className="flex flex-col items-center justify-center gap-2"> | ||
| <Python className="size-16" /> | ||
| <span className="font-medium">Python SDK</span> | ||
| <Badge variant="secondary">Beta</Badge> |
There was a problem hiding this comment.
The Getting Started section appears to be ordered/curated via docs/content/docs/getting-started/meta.json (pages array). That list currently doesn’t include python, so this new page may not show up in the left nav / page ordering even though it’s linked here. Add python to the pages list (and place it first if you want it highlighted first, consistent with this grid).
| --- | ||
| title: Python SDK | ||
| description: Get started with the Vercel Workflow Python SDK for building durable, long-running workflows. | ||
| type: guide | ||
| summary: Set up the Workflow Python SDK in your Python application. | ||
| prerequisites: |
There was a problem hiding this comment.
Frontmatter and placement suggest this is a “Getting Started” setup guide (type: guide, summary: Set up...), but the page content is mostly conceptual and doesn’t include the setup steps pattern used by the other getting-started guides (e.g., <Steps> / installation/configuration). Either add the initial setup section(s) or adjust the frontmatter/type/summary so it matches what the page actually provides.
| import random | ||
| from app.workflow import wf | ||
|
|
||
| @wf.step | ||
| async def generate_draft(*, topic: str): | ||
| return await ai_generate(prompt=f"Write a blog post about {topic}") | ||
|
|
||
| @wf.step | ||
| async def summarize_draft(*, draft: str): | ||
| summary = await ai_summarize(text=draft) | ||
|
|
||
| # Simulate a transient error. The step automatically retries. | ||
| if random.random() < 0.3: | ||
| raise Exception("Transient AI provider error") | ||
|
|
||
| return summary | ||
| ``` | ||
|
|
||
| Each step compiles into an isolated route. While the step executes, the workflow suspends without consuming resources. When the step completes, the workflow resumes automatically where it left off. | ||
|
|
||
| ### Sleep | ||
|
|
||
| Sleep pauses a workflow for a specified duration without consuming compute resources. Use it when you need to wait for hours or days before continuing, such as sending a follow-up email or delaying a reward. | ||
|
|
||
| ```python | ||
| from vercel import workflow | ||
| from app.workflow import wf | ||
|
|
There was a problem hiding this comment.
Several examples import wf from app.workflow / app.workflows.approval, but this is the only doc page using that module path and it’s not established earlier in the guide. For clarity and copy/paste-ability, either show wf = workflow.Workflows() in each snippet, or use a clearly-placeholder module path (e.g., from my_app.workflow import wf) and add a short note that wf is the shared Workflows() instance.
Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>
Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>
Added a new card for the Python getting started guide with a beta badge. Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>
Updated the description for clarity and conciseness. Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>
Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>
Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>
Adds a dedicated Python SDK page to the Getting Started section of the docs, as discussed for the launch.
What changed
/docs/getting-started/python.mdxwith content sourced from vercel.com/docs/workflow/conceptsThe page covers core concepts (Workflow, Step, Sleep, Hook, Skew Protection) with Python code samples and links back to the official Vercel docs.