Skip to content

PUBLISHING.md

Latest commit

 

History

History
187 lines (143 loc) · 4.17 KB

PUBLISHING.md

File metadata and controls

187 lines (143 loc) · 4.17 KB

Publishing RankVectors Python SDK to PyPI

This guide will help you publish the RankVectors Python SDK to PyPI.

Prerequisites

  1. PyPI Account: Create an account at https://pypi.org/account/register/
  2. API Token: Generate a PyPI API token at https://pypi.org/manage/account/token/
  3. Required Tools: Install build and twine 
    pip install build twine

Publishing Steps

Option 1: Using the Publishing Script (Recommended)

cd sdk/python
./publish-pypi.sh

The script will:

  • Check prerequisites
  • Clean previous builds
  • Build the package (wheel and source distribution)
  • Show you what will be uploaded
  • Prompt for confirmation
  • Upload to PyPI

Option 2: Manual Publishing

  1. Navigate to the Python SDK directory:

    cd sdk/python

  2. Clean previous builds:

    rm -rf dist/ build/ *.egg-info/

  3. Build the package:

    python -m build

  4. Check the distribution files:

    ls -lh dist/

  5. Test the build (optional):

    pip install dist/rankvectors-*.whl

  6. Upload to TestPyPI (recommended first):

    twine upload --repository testpypi dist/*

  7. Test installation from TestPyPI:

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

  8. Upload to PyPI:

    twine upload dist/*

Authentication

You can authenticate in several ways:

Method 1: API Token (Recommended)

export TWINE_USERNAME='__token__'
export TWINE_PASSWORD='pypi-your-token-here'
twine upload dist/*

⚠️ Security Note: Never commit your API token to version control. Use environment variables or a secure secret management system.

Method 2: Username and Password

When prompted by twine, enter your PyPI username and password.

Method 3: Config File (~/.pypirc)

Create a file ~/.pypirc:

[pypi]
username = __token__
password = pypi-your-token-here

Post-Publishing Verification

  1. Verify on PyPI: Visit https://pypi.org/project/rankvectors/

  2. Test installation:

    pip install --upgrade rankvectors

  3. Verify functionality:

    python -c "import rankvectors; print(rankvectors.__version__)"

Version Management

To release a new version:

  1. Update the version in:

    • setup.py (line 39)
    • pyproject.toml (line 3)

  2. Use semantic versioning (MAJOR.MINOR.PATCH):

    • MAJOR: Breaking changes
    • MINOR: New features, backward compatible
    • PATCH: Bug fixes, backward compatible

  3. Commit the changes:

    git add setup.py pyproject.toml
git commit -m "Bump version to X.Y.Z"
git tag vX.Y.Z
git push && git push --tags

Troubleshooting

Error: Package already exists

If you're trying to upload a version that already exists:

  • Update the version number
  • Build and upload again

Error: Invalid API token

Error: Missing required files

  • Ensure py.typed file exists in the rankvectors package
  • Check that all source files are included in the build

TestPyPI upload fails

  • TestPyPI is a separate instance
  • You need a separate account at https://test.pypi.org/
  • Use --repository testpypi flag

CI/CD Integration

To automate publishing on each release:

  1. Add GitHub Actions workflow (.github/workflows/publish.yml)
  2. Store PyPI credentials as GitHub Secrets
  3. Trigger on git tags

Example workflow:

name: Publish to PyPI

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
      - run: pip install build twine
      - run: cd sdk/python && python -m build
      - run: twine upload dist/*
        env:
          TWINE_USERNAME: __token__
          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}

Additional Resources