Skip to content

PUBLISHING.md

Latest commit

 

History

History
193 lines (134 loc) · 3.92 KB

PUBLISHING.md

File metadata and controls

193 lines (134 loc) · 3.92 KB

Publishing pythonstl to PyPI

This document provides step-by-step instructions for building and publishing the pythonstl package to PyPI.

Prerequisites

Install required tools:

pip install --upgrade pip
pip install build twine

Step 1: Clean Previous Builds

Remove any existing build artifacts:

# Windows PowerShell
Remove-Item -Recurse -Force dist, build, *.egg-info -ErrorAction SilentlyContinue

# Linux/Mac
rm -rf dist build *.egg-info

Step 2: Build the Distribution

Build both source distribution and wheel:

python -m build

This creates:

  • dist/pythonstl-0.1.0.tar.gz (source distribution)
  • dist/pythonstl-0.1.0-py3-none-any.whl (wheel)

Step 3: Validate the Build

Check the distribution files for errors:

twine check dist/*

Expected output:

Checking dist/pythonstl-0.1.0-py3-none-any.whl: PASSED
Checking dist/pythonstl-0.1.0.tar.gz: PASSED

Step 4: Test on TestPyPI (Recommended)

Upload to TestPyPI

twine upload --repository testpypi dist/*

You'll be prompted for credentials. Use:

  • Username: __token__
  • Password: Your TestPyPI API token (starts with pypi-)

Install from TestPyPI

Test the installation:

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

Verify Installation

python -c "from pythonstl import vector; v = vector(); v.push_back(1); print('✓ Installation successful')"

Step 5: Publish to Production PyPI

Using API Token (Recommended)

twine upload dist/* -u __token__ -p YOUR_PYPI_API_TOKEN

Security Best Practices:

  • Never commit API tokens to version control
  • Store tokens in environment variables or password managers
  • Use project-scoped tokens when possible
  • Rotate tokens periodically

Using Environment Variable

Set your token as an environment variable:

# Windows PowerShell
$env:TWINE_PASSWORD = "pypi-YOUR_TOKEN_HERE"
twine upload dist/* -u __token__

# Linux/Mac
export TWINE_PASSWORD="pypi-YOUR_TOKEN_HERE"
twine upload dist/* -u __token__

Using .pypirc (Alternative)

Create ~/.pypirc:

[pypi]
username = __token__
password = pypi-YOUR_TOKEN_HERE

Warning: Ensure .pypirc has restricted permissions (chmod 600 on Unix).

Then upload:

twine upload dist/*

Step 6: Verify Publication

After successful upload:

  1. Visit https://pypi.org/project/pythonstl/
  2. Install from PyPI: 
    pip install pythonstl
  3. Test the installation: 
    from pythonstl import stack, queue, vector, stl_set, stl_map, priority_queue
print("✓ All imports successful")

Troubleshooting

Build Fails

  • Ensure pyproject.toml is valid
  • Check that all package directories have __init__.py
  • Verify Python version >= 3.10

Upload Fails

  • 403 Forbidden: Check API token permissions
  • 400 Bad Request: Package name may already exist
  • File already exists: Version already published (increment version)

Import Errors After Installation

  • Clear pip cache: pip cache purge
  • Reinstall: pip uninstall pythonstl && pip install pythonstl
  • Check for naming conflicts with other packages

Version Management

For future releases:

  1. Update version in pythonstl/__init__.py
  2. Update version in pyproject.toml
  3. Create git tag: git tag v0.1.1
  4. Rebuild and republish

Security Checklist

Before publishing:

  • No hardcoded secrets in code
  • No sensitive data in examples
  • LICENSE file included
  • README.md is accurate
  • All tests pass
  • Version number is correct
  • API token is secure

Post-Publication

  1. Create GitHub release with changelog
  2. Update documentation
  3. Announce on relevant channels
  4. Monitor PyPI download stats
  5. Respond to issues and feedback

Resources