Publish Python SDKs manually

This guide covers publishing Python SDKs manually. For information on automating Python SDK publishing, see Publish Python SDKs automatically.

To share your generated Python SDK with the community, you can publish it to PyPI. This enables other developers to easily install it using the pip command. Follow the steps below to publish your SDK to PyPI.

Prerequisites

To publish your SDK to PyPI, you need the following:

• PyPI account (create at pypi.org).
• Twine installed: pip install twine

Configure pyproject.toml

Ensure your SDK’s pyproject.toml is properly configured:

1
[build-system]
2
requires = ["setuptools>=61.0", "wheel"]
3
build-backend = "setuptools.build_meta"
4
5
[project]
6
name = "your-sdk"
7
version = "1.0.0"
8
description = "SDK for Your API"
9
readme = "README.md"
10
requires-python = ">=3.9"
11
license = {text = "MIT"}
12
authors = [
13
    {name = "Your Name", email = "your@email.com"}
14
]
15
keywords = ["api", "sdk", "your-api"]
16
classifiers = [
17
    "Development Status :: 5 - Production/Stable",
18
    "Intended Audience :: Developers",
19
    "License :: OSI Approved :: MIT License",
20
    "Programming Language :: Python :: 3",
21
    "Programming Language :: Python :: 3.9",
22
    "Programming Language :: Python :: 3.10",
23
    "Programming Language :: Python :: 3.11",
24
]
25
26
dependencies = [
27
    "requests>=2.31.0",
28
    "pydantic>=2.0.0",
29
]
30
31
[project.optional-dependencies]
32
dev = [
33
    "pytest>=7.0.0",
34
    "black>=23.0.0",
35
    "mypy>=1.0.0",
36
]
37
38
[project.urls]
39
Homepage = "https://github.com/your-org/your-sdk"
40
Documentation = "https://your-sdk.readthedocs.io"
41
Repository = "https://github.com/your-org/your-sdk"
42
"Bug Tracker" = "https://github.com/your-org/your-sdk/issues"
43
44
[tool.setuptools]
45
packages = ["your_sdk"]
46
package-dir = {"" = "src"}

Publish your Python SDK to PyPI

To publish your SDK to PyPI, do the following:

1. Create PyPI account and API token:

   • Register at pypi.org.
   • Go to Account Settings > API tokens.
   • Create a token with a scope of the entire account or specific project.

2. Configure the credentials. You can use Twine’s recommended method of storing credentials in ~/.pypirc:

   1
   [distutils]
   2
   index-servers =
   3
       pypi
   4
   5
   [pypi]
   6
   username = __token__
   7
   password = pypi-YOUR_API_TOKEN_HERE

3. Build distribution packages:

   $
   # Install build tools
   $
   pip install build twine
   $
   $
   # Build
   $
   python -m build

   This creates dist/ directory with:

   • your-sdk-1.0.0.tar.gz (source distribution)
   • your_sdk-1.0.0-py3-none-any.whl (wheel distribution)

4. Check the package:

   $
   twine check dist/*

5. Test on TestPyPI first (recommended):

   $
   # Upload to TestPyPI
   $
   twine upload --repository testpypi dist/*
   $
   $
   # Install from TestPyPI to test
   $
   pip install --index-url https://test.pypi.org/simple/ your-sdk

6. Publish to PyPI:

   $
   twine upload dist/*

7. Verify publication:

   $
   pip install your-sdk
   $
   # Or visit: https://pypi.org/project/your-sdk/

Publish updates

1. Update the version in pyproject.toml:

   1
   version = "1.0.1"

   Alternatively, if using dynamic versioning, you can set up your pyproject.toml to read the version from your SDK package:

   1
   [project]
   2
   dynamic = ["version"]
   3
   4
   [tool.setuptools.dynamic]
   5
   version = {attr = "your_sdk.__version__"}

2. Clean and rebuild:

   $
   rm -rf dist/
   $
   python -m build
   $
   twine upload dist/*

Best practices for publishing Python SDKs

Use the following best practices when publishing your Python SDK to PyPI:

• Use semantic versioning (MAJOR.MINOR.PATCH).
• Test on TestPyPI before publishing to PyPI.
• Include a comprehensive README.md with examples.
• Add a LICENSE file.
• Use type hints for better IDE support.
• Include a py.typed file for PEP 561 compliance.
• Tag releases in Git: git tag v1.0.0 && git push --tags.
• Set up GitHub Actions for automated testing and publishing.

The following is an example GitHub Actions workflow (.github/workflows/publish.yml).

1
name: Publish Python Package
2
3
on:
4
  release:
5
    types: [published]
6
7
jobs:
8
  publish:
9
    runs-on: ubuntu-latest
10
    steps:
11
      - uses: actions/checkout@v4
12
      - uses: actions/setup-python@v5
13
        with:
14
          python-version: '3.9'
15
      - name: Install dependencies
16
        run: |
17
          pip install build twine
18
      - name: Build package
19
        run: python -m build
20
      - name: Publish to PyPI
21
        env:
22
          TWINE_USERNAME: __token__
23
          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
24
        run: twine upload dist/*