This page guides contributors through setting up a local development environment for the Anthropic Python SDK. It covers dependency installation using uv, development container configuration, and running the Prism mock server for testing.
The SDK development environment is optimized for speed and reproducibility using uv. It supports a wide range of Python versions (3.9 through 3.14) and ensures compatibility with both Pydantic v1 and v2.
Required Tools:
uv) uv.lock3pyright (managed via nodeenv in some environments) requirements-dev.lock79-80Optional Tools:
The repository provides a bootstrap script that handles Python installation, dependency syncing, and lockfile generation.
This script performs the following actions:
uv python install scripts/bootstrap23uv sync --all-extras scripts/bootstrap26requirements-dev.lock for environments not using uv scripts/bootstrap30If you prefer to run commands manually:
Sources: CONTRIBUTING.md15-25
If you cannot use uv, you can use standard pip with the generated lockfile:
Sources: CONTRIBUTING.md31-37 requirements-dev.lock1-147
The repository includes a pre-configured VS Code Dev Container environment. This ensures your environment matches the CI pipeline.
mcr.microsoft.com/vscode/devcontainers/python:0-3.9 (default variant) .devcontainer/Dockerfile1-2uv binaries directly from the official ghcr.io/astral-sh/uv image .devcontainer/Dockerfile6uv sync --all-extras to ensure the environment is ready upon opening .devcontainer/devcontainer.json10The environment is customized with the following settings in .devcontainer/devcontainer.json12-27:
.venv/bin/python .devcontainer/devcontainer.json19-20basic by default .devcontainer/devcontainer.json21ms-python.python extension .devcontainer/devcontainer.json14-16The following diagram bridges the "Natural Language Space" (Developer Workflow) to the "Code Entity Space" (Scripts and Configuration files).
Sources: scripts/bootstrap1-31 CONTRIBUTING.md92-101 bin/publish-pypi1-12
This diagram illustrates how uv manages the environment and how the different lockfiles relate to the installation process.
Sources: scripts/bootstrap22-30 CONTRIBUTING.md7-19 requirements-dev.lock1-3
Most tests in the SDK require a mock server to be running. This prevents the tests from hitting the live Anthropic production API and allows for deterministic testing.
You can start the mock server using the provided helper script:
Sources: CONTRIBUTING.md92-96
This script typically launches a Prism server that validates requests against the Anthropic OpenAPI specification. Logs are directed to .prism.log or .stdy.log .gitignore1-2
Once the environment is set up, verify it by running the linting suite.
The ./scripts/lint script executes several tools in sequence:
To automatically fix formatting issues (using ruff and black standards):
Sources: CONTRIBUTING.md133-137
The local environment setup mirrors the GitHub Actions CI pipeline. The CI workflow .github/workflows/ci.yml uses the same uv sync --all-extras command and execution scripts that developers use locally.
| CI Job | Local Equivalent | File Reference |
|---|---|---|
lint | ./scripts/lint | .github/workflows/ci.yml35 |
test | ./scripts/test | .github/workflows/ci.yml95 |
build | uv build | .github/workflows/ci.yml57 |
publish | bin/publish-pypi | .github/workflows/publish-pypi.yml26 |
Sources: .github/workflows/ci.yml17-96 .github/workflows/publish-pypi.yml1-27 bin/publish-pypi1-12
Refresh this wiki