Publishing to PyPI¶

This guide covers how to publish your ZigX project to PyPI.

Prerequisites¶

Create a PyPI account at pypi.org
Set up API tokens for authentication

Using `zigx publish`¶

The simplest way to publish:

zigx publish

This: 1. Builds a release wheel 2. Uploads to PyPI using twine

Manual Publishing¶

Step 1: Build the Wheel¶

zigx build --release

Step 2: Install Twine¶

pip install twine

Step 3: Upload¶

twine upload dist/*

Authentication¶

Using API Tokens (Recommended)¶

Go to PyPI → Account Settings → API tokens
Create a token with upload permissions
Configure in ~/.pypirc:

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

Using Environment Variables¶

export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-YOUR-API-TOKEN-HERE
twine upload dist/*

Test PyPI¶

Test your package on TestPyPI first:

twine upload --repository testpypi dist/*

Then install from TestPyPI:

pip install --index-url https://test.pypi.org/simple/ myproject

Version Management¶

Update version in pyproject.toml:

[project]
name = "myproject"
version = "0.2.0"  # Bump version before publishing

ZigX follows semantic versioning: - MAJOR: Breaking changes - MINOR: New features, backward compatible - PATCH: Bug fixes

Multi-Platform Builds¶

For true cross-platform distribution, build on each platform:

GitHub Actions Example¶

name: Build and Publish

on:
  release:
    types: [published]

jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python: ['3.10', '3.11', '3.12', '3.13', '3.14']

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}

      - name: Install Zig
        uses: goto-bus-stop/setup-zig@v2
        with:
          version: 0.15.2

      - name: Install ZigX
        run: pip install zigx

      - name: Build wheel
        run: zigx build --release

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: wheels-${{ matrix.os }}-${{ matrix.python }}
          path: dist/*.whl

  publish:
    needs: build
    runs-on: ubuntu-latest

    steps:
      - name: Download all wheels
        uses: actions/download-artifact@v4
        with:
          path: dist
          merge-multiple: true

      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          password: ${{ secrets.PYPI_API_TOKEN }}

Best Practices¶

Test locally first - Ensure the package works
Use TestPyPI - Validate the upload process
Use CI/CD - Automate multi-platform builds
Keep tokens secure - Never commit API tokens
Update documentation - Keep README and docs current