Publishing to PyPI¶

This guide explains how to publish the mini-arm package to PyPI.

Prerequisites¶

Create accounts on PyPI and TestPyPI
Install build tools:

pip install build twine

Build the Package¶

From the repository root:

# Clean previous builds
rm -rf dist/ build/ src/*.egg-info

# Build source and wheel distributions
python -m build

This creates:

dist/mini_arm-X.Y.Z.tar.gz (source distribution)
dist/mini_arm-X.Y.Z-py3-none-any.whl (wheel)

Test on TestPyPI¶

Always test on TestPyPI first:

# Upload to TestPyPI
python -m twine upload --repository testpypi dist/*

# Test installation
pip install --index-url https://test.pypi.org/simple/ mini-arm

Publish to PyPI¶

Once verified on TestPyPI:

# Upload to PyPI
python -m twine upload dist/*

# Verify installation
pip install mini-arm

Using API Tokens (Recommended)¶

Instead of username/password, use API tokens:

Go to PyPI → Account Settings → API tokens
Create a token scoped to the mini-arm project
Create ~/.pypirc:

[pypi]
username = __token__
password = pypi-YOUR-TOKEN-HERE

[testpypi]
username = __token__
password = pypi-YOUR-TESTPYPI-TOKEN-HERE

Automated Publishing with GitHub Actions¶

Add this workflow to .github/workflows/publish.yml:

name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install build tools
        run: pip install build twine

      - name: Build package
        run: python -m build

      - name: Publish to PyPI
        env:
          TWINE_USERNAME: __token__
          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
        run: python -m twine upload dist/*

Then add PYPI_API_TOKEN to your repository secrets.

Version Checklist¶

Before publishing a new version:

☐ Update src/mini_arm/version.py
☐ Update pyproject.toml version
☐ Update ROS2 package.xml versions
☐ Update CHANGELOG.md
☐ Run tests: pytest tests/ -v
☐ Build docs: cd docs && make html
☐ Commit and tag: git tag -a vX.Y.Z
☐ Push: git push origin main --tags
☐ Create GitHub release
☐ Publish to PyPI

Verifying Installation¶

After publishing, verify the package works:

import mini_arm
print(mini_arm.__version__)

from mini_arm import MiniArmClient
# Test basic functionality