Skip to content

PUBLISHING.md

Latest commit

 

History

History
229 lines (157 loc) · 4.76 KB

PUBLISHING.md

File metadata and controls

229 lines (157 loc) · 4.76 KB
Raw

Publishing Guide

This guide explains how to publish the Apiframe Python SDK to PyPI.

Prerequisites

  1. A PyPI account (create one at pypi.org)
  2. PyPI API token (recommended) or username/password
  3. Install required tools:
pip install build twine

Pre-Publication Checklist

Before publishing, ensure:

  • All tests pass (pytest)
  • Code is properly formatted (black, isort)
  • Type checking passes (mypy)
  • Linting passes (flake8)
  • Version number is updated in pyproject.toml
  • CHANGELOG.md is updated with changes
  • README.md is up to date
  • Examples are working and tested
  • Documentation is complete

Version Numbering

We follow Semantic Versioning:

  • MAJOR version: Incompatible API changes
  • MINOR version: Add functionality in a backward compatible manner
  • PATCH version: Backward compatible bug fixes

Update the version in pyproject.toml:

[project]
version = "1.0.0"  # Update this

Building the Package

  1. Clean previous builds:
rm -rf dist/ build/ *.egg-info
  1. Build the distribution packages:
python -m build

This creates two files in the dist/ directory:

  • A source distribution (.tar.gz)
  • A wheel (.whl)

Testing the Build

Before uploading to PyPI, test the build locally:

# Install in a fresh virtual environment
python -m venv test_env
source test_env/bin/activate  # On Windows: test_env\Scripts\activate

# Install the built package
pip install dist/apiframe-1.0.0-py3-none-any.whl

# Test basic import
python -c "from apiframe import Apiframe; print('Import successful')"

# Deactivate and clean up
deactivate
rm -rf test_env

Publishing to TestPyPI (Recommended First Step)

Before publishing to the main PyPI, test on TestPyPI:

  1. Create an account at test.pypi.org

  2. Upload to TestPyPI:

python -m twine upload --repository testpypi dist/*
  1. Test installation from TestPyPI:
pip install --index-url https://test.pypi.org/simple/ --no-deps apiframe

Publishing to PyPI

Once you've verified everything works on TestPyPI:

  1. Upload to PyPI:
python -m twine upload dist/*

You'll be prompted for your PyPI credentials or API token.

  1. Verify the upload:

Visit pypi.org/project/apiframe-sdk/ to see your package.

  1. Test installation:
pip install apiframe-sdk

Using PyPI API Token (Recommended)

For security, use an API token instead of username/password:

  1. Generate a token at pypi.org/manage/account/token/

  2. Create or update ~/.pypirc:

[pypi]
username = __token__
password = pypi-YOUR_TOKEN_HERE

[testpypi]
username = __token__
password = pypi-YOUR_TOKEN_HERE
  1. Set appropriate permissions:
chmod 600 ~/.pypirc

Automated Publishing with GitHub Actions

You can automate publishing using GitHub Actions. Create .github/workflows/publish.yml:

name: Publish to PyPI

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.x'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        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: twine upload dist/*

Add your PyPI API token as a GitHub secret named PYPI_API_TOKEN.

Post-Publication Steps

After publishing:

  1. Create a GitHub release:

    • Tag: v1.0.0 (matching the version)
    • Title: "Release 1.0.0"
    • Description: Copy from CHANGELOG.md

  2. Update documentation:

    • Ensure docs.apiframe.ai reflects the new version
    • Update any external documentation or blog posts

  3. Announce the release:

    • Social media
    • Email newsletter
    • Community forums

Troubleshooting

"File already exists" error

PyPI doesn't allow re-uploading the same version. You must:

  • Increment the version number
  • Rebuild the package
  • Upload again

Import errors after installation

  • Check that all dependencies are listed in pyproject.toml
  • Ensure __init__.py files are in all package directories
  • Verify the package structure is correct

Missing files in distribution

Check MANIFEST.in to ensure all necessary files are included.

Version History

Keep track of published versions:

  • 1.0.0 - Initial release (2024-10-10)

Support

For publishing issues: