Python

Python is fully supported.

The Stainless Python SDK generator creates idiomatic, type-safe Python client libraries from your OpenAPI specification.

Example repositories:

• openai/openai-python
• anthropics/anthropic-sdk-python
• Metronome-Industries/metronome-python
• browserbase/stagehand-python
• ComposioHQ/composio-base-py

Configuration

To generate a Python SDK, add the python target to your Stainless configuration file:

targets:
  python:
    package_name: my_company_client
    edition: python.2025-11-20

Common configuration options

targets:
  python:
    # package_name is used for imports (e.g., "import my_company_client")
    package_name: my_company_client

    # project_name is the PyPI distribution name (e.g., "pip install my-company-client")
    # If not specified, defaults to package_name
    project_name: my-company-client

    # Specify the edition
    edition: python.2025-11-20

    # Specify the package manager (default: uv)
    package_manager: uv  # or: rye

    # Configure publishing
    publish:
      pypi: true

For a complete list of configuration options, see the Python target reference.

Editions

Editions allow Stainless to make improvements to SDKs that aren’t backwards-compatible. You can explicitly opt in to new editions when you’re ready. See the SDK and config editions reference for more information.

python.2025-11-20

• Changed default package manager from Rye to uv
• To revert to Rye, set options.use_uv: false

python.2025-10-08

• Initial edition for Python (used by default if no edition is specified)

Publishing to PyPI

Package your Python SDK for distribution on PyPI, making it easy for users to install with pip install.

Before publishing, you need to link a production repository where Stainless will push your SDK code.

Trusted Publishing (OIDC) [Recommended]

Trusted publishing uses OpenID Connect (OIDC) to authenticate with PyPI without requiring long-lived API tokens. This is the recommended approach for security.

(Option 1): Configure a new PyPI project

1. Navigate to the publishing settings in your PyPI account, and scroll down to the Add a new pending publisher section.

2. Enter the PyPI project name for your SDK. This should match the targets.python.package_name value in your Stainless config.

3. Enter the Owner and the Repository name to match the GitHub repository’s location.

4. Enter publish-pypi.yml as the Workflow name.

5. [Recommended] If you utilize a specific GitHub Actions environment for releases, enter the Environment name. This will make it so only release workflows running in that environment can publish.

   The release environment is set in your Stainless config like so:

   codeflow:
     release_environment: <environment-name>
     # ...

6. Click Add.

(Option 2): Configure an existing PyPI project

1. Navigate to your project settings at pypi.org/manage/project/<package-name>/settings/publishing, and find the Add a new publisher section.

2. Enter the Owner and the Repository name to match the GitHub repository’s location.

3. Enter publish-pypi.yml as the Workflow name.

4. [Recommended] If you utilize a specific GitHub Actions environment for releases, enter the Environment name. This will make it so only release workflows running in that environment can publish.

   The release environment is set in your Stainless config like so:

   codeflow:
     release_environment: <environment-name>
     # ...

5. Click Add.

Update your Stainless config

Update the Stainless config to specify OIDC authentication and save.

targets:
  python:
    package_name: <package-name>
    publish:
      pypi:
        auth_method: oidc

Troubleshooting

Trusted publishing is only supported with the uv package manager. If you’re using rye you may get a No access token found error.

Ensure your config is on the python.2025-11-20 edition or higher:

targets:
  python:
    edition: python.2025-11-20

API Tokens

Use API tokens to authenticate with PyPI. Note that these tokens may need to be rotated periodically for security.

Get an API token

1. Log in or sign up at PyPI.

2. Select your profile picture on the top right to open a dropdown.

3. Navigate to Access settings > API tokens > Add API token. You may have to verify your email address and set up 2FA if you haven’t already done so.

   Note: If you haven’t created a PyPI package yet, you can create an API token scoped to your whole account, or you can create an empty PyPI package to use as a starting point.

Add the token to your production repo

1. In your production repo, navigate to Secrets and variables > Actions > New repository secret. The URL should look like https://github.com/<org>/<repo>/settings/secrets/actions/new.
2. Add a new secret named PYPI_TOKEN with your API token.

Choose a package name and update your Stainless config

1. Choose an available package name. Suggested names are:

   • <company-name>
   • <company-name>-client

   You can check whether the name is available by testing the link at https://pypi.org/project/<package-name>.

2. Update the Stainless config with your package name and save.

   targets:
     python:
       package_name: <package-name>
       publish:
         pypi: true