Skip to content

Commit 6fc76a2

Browse files
Add inline server setup to Python SDK quickstart
Closes QS-002. The previous Python SDK quickstart assumed a running server and used token="your-token" without explaining where either came from, so a first-time pip install user hit a ConnectError on the first run and had to bounce to /docs/2.0/server-setup to recover. The quickstart now splits into two numbered steps: 1. Start a local server — a self-contained docker compose snippet with APP_KEY generation and WORKFLOW_SERVER_AUTH_DRIVER=none, plus a health-check wait loop. Links out to server-setup for production. 2. Run the Python worker — the worker snippet now uses token=None to match the no-auth local dev server, and explains where to swap in a real token. The former "Running Against Docker Compose" section at the bottom duplicated the quickstart; it's now a "Running Against a Shared Server" section with the production/team pattern (base URL + token + namespace). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 9aa541a commit 6fc76a2

File tree

1 file changed

+41
-17
lines changed

1 file changed

+41
-17
lines changed

docs/sdks/python.md

Lines changed: 41 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ The SDK targets the same durable model as the PHP package — instance IDs, run
1111
## Requirements
1212

1313
- Python 3.10 or later
14-
- A running [Durable Workflow server](/docs/2.0/server-setup)
14+
- Docker (for the local server used in this quickstart) or an existing [Durable Workflow server](/docs/2.0/server-setup)
1515

1616
## Installation
1717

@@ -23,7 +23,33 @@ The SDK has a single runtime dependency: [httpx](https://www.python-httpx.org/).
2323

2424
## Quickstart
2525

26-
This example defines a workflow with one activity, starts it against a local server, and waits for the result.
26+
The quickstart has two steps: start a local server, then run the Python worker against it.
27+
28+
### 1. Start a local server
29+
30+
The fastest path is the server's Docker Compose stack, which brings up the server plus its MySQL and Redis dependencies. The snippet below disables authentication for local development — do not use `WORKFLOW_SERVER_AUTH_DRIVER=none` in production.
31+
32+
```bash
33+
git clone https://github.com/durable-workflow/server.git
34+
cd server
35+
36+
# Generate an APP_KEY and disable auth for local dev.
37+
cp .env.example .env
38+
printf '\nAPP_KEY=base64:%s\nWORKFLOW_SERVER_AUTH_DRIVER=none\n' \
39+
"$(head -c 32 /dev/urandom | base64)" >> .env
40+
41+
docker compose up -d
42+
43+
# Wait for the health check to pass.
44+
until curl -sf http://localhost:8080/api/health > /dev/null; do sleep 1; done
45+
echo "Server is ready."
46+
```
47+
48+
For a full walkthrough — auth drivers, database config, production deployment — see the [server setup guide](/docs/2.0/server-setup).
49+
50+
### 2. Run the Python worker
51+
52+
This example defines a workflow with one activity, starts it against the local server, and waits for the result.
2753

2854
```python
2955
import asyncio
@@ -40,7 +66,9 @@ class GreeterWorkflow:
4066
return result
4167

4268
async def main():
43-
async with Client("http://localhost:8080", token="your-token") as client:
69+
# token=None matches WORKFLOW_SERVER_AUTH_DRIVER=none in the server .env.
70+
# If you set a token instead, pass token="your-token" here.
71+
async with Client("http://localhost:8080") as client:
4472
handle = await client.start_workflow(
4573
workflow_type="greeter",
4674
task_queue="default",
@@ -550,22 +578,18 @@ This means Python workflows and activities can interoperate with PHP workers on
550578

551579
Avoid passing Python-specific types (dataclasses, sets, tuples, datetime objects) as workflow or activity inputs unless you explicitly convert them to JSON-compatible structures first.
552580

553-
## Running Against Docker Compose
554-
555-
The fastest way to get started is with the server's Docker Compose stack:
581+
## Running Against a Shared Server
556582

557-
```bash
558-
# Clone and start the server
559-
git clone https://github.com/durable-workflow/server.git
560-
cd server
561-
cp .env.example .env # set APP_KEY and WORKFLOW_SERVER_AUTH_TOKEN
562-
docker compose up -d
583+
The [Quickstart](#quickstart) above shows how to bring up a local server via Docker Compose. In a team environment you usually point the Python worker at an existing server (staging, production, or a shared dev instance):
563584

564-
# Install the Python SDK
565-
pip install durable-workflow
585+
```python
586+
from durable_workflow import Client
566587

567-
# Run your Python worker
568-
python my_worker.py
588+
client = Client(
589+
"https://workflow.example.internal",
590+
token="shared-server-token",
591+
namespace="team-orders",
592+
)
569593
```
570594

571-
The server runs on `http://localhost:8080` by default.
595+
Set the `namespace` argument to whichever tenant namespace the shared server has provisioned for your team. The server operator manages namespace creation — see the [server setup guide](/docs/2.0/server-setup) for details.

0 commit comments

Comments
 (0)