Python Packaging

Python Packaging

Quick reference for building and publishing Python packages with UV and modern build tools.

When to Use This Skill

When This Skill Applies

• Building Python packages (wheels, sdists)
• Publishing to PyPI or private indexes
• Package versioning
• Build system configuration
• Editable installations

Quick Reference

Building Packages

# Build package
uv build

# Build specific formats
uv build --wheel
uv build --sdist

# Output location: dist/

Publishing

# Publish to PyPI
uv publish

# With token
uv publish --token $PYPI_TOKEN

# To Test PyPI
uv publish --publish-url https://test.pypi.org/legacy/

Package Structure

my-package/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── __version__.py
│       └── main.py
└── tests/

pyproject.toml Configuration

[project]
name = "my-package"
version = "0.1.0"
description = "A great package"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "you@example.com"}
]
keywords = ["python", "package"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.11",
]

dependencies = [
    "requests>=2.31.0",
]

[project.optional-dependencies]
dev = ["pytest", "ruff", "ty"]

[project.urls]
Homepage = "https://github.com/user/my-package"
Documentation = "https://my-package.readthedocs.io"
Repository = "https://github.com/user/my-package.git"
Issues = "https://github.com/user/my-package/issues"

[project.scripts]
my-cli = "my_package.cli:main"

[build-system]
requires = ["uv_build>=0.9.2,<0.10.0"]
build-backend = "uv_build"

Versioning

[project]
version = "0.1.0"  # Manual versioning

# Dynamic versioning (from git tags)
dynamic = ["version"]

[tool.uv]
version-provider = "git"

Entry Points

[project.scripts]
my-cli = "my_package.cli:main"

[project.gui-scripts]
my-gui = "my_package.gui:main"

[project.entry-points."my_plugin"]
plugin1 = "my_package.plugins:plugin1"

Build Backends

UV Build (default)

[build-system]
requires = ["uv_build>=0.9.2,<0.10.0"]
build-backend = "uv_build"

Setuptools

[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

Hatchling

[build-system]
requires = ["hatchling>=1.18"]
build-backend = "hatchling.build"

Common Workflows

Publish to PyPI

# 1. Build
uv build

# 2. Check built packages
ls dist/

# 3. Publish
uv publish --token $PYPI_TOKEN

Test PyPI First

# Publish to Test PyPI
uv publish --publish-url https://test.pypi.org/legacy/ \
           --token $TEST_PYPI_TOKEN

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

Package Classifiers

Common classifiers:

classifiers = [
    # Development Status
    "Development Status :: 3 - Alpha",
    "Development Status :: 4 - Beta",
    "Development Status :: 5 - Production/Stable",

    # Audience
    "Intended Audience :: Developers",
    "Intended Audience :: Science/Research",

    # License
    "License :: OSI Approved :: MIT License",

    # Python Versions
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",

    # Framework
    "Framework :: Django",
    "Framework :: FastAPI",

    # Topic
    "Topic :: Software Development :: Libraries",
    "Topic :: Scientific/Engineering",
]

Full list: https://pypi.org/classifiers/

See Also

• uv-project-management - Project setup and dependencies
• python-development - Core Python patterns
• uv-workspaces - Building workspace packages

References

• UV build: https://docs.astral.sh/uv/guides/publish/
• PyPI: https://pypi.org/
• Detailed guide: See REFERENCE.md

Python Packaging - Comprehensive Reference

Complete guide to building and publishing Python packages.

Building Packages

UV simplifies the build process:

# Build both wheel and sdist
uv build

# Build only wheel
uv build --wheel

# Build only source distribution
uv build --sdist

# Output: dist/
# - my_package-0.1.0-py3-none-any.whl
# - my_package-0.1.0.tar.gz

---

Publishing

PyPI

# Set token
export PYPI_TOKEN="pypi-..."

# Publish
uv publish --token $PYPI_TOKEN

# Or use .pypirc
uv publish

Test PyPI

export TEST_PYPI_TOKEN="pypi-..."

uv publish \
  --publish-url https://test.pypi.org/legacy/ \
  --token $TEST_PYPI_TOKEN

Private Index

uv publish \
  --publish-url https://private.pypi.org/simple/ \
  --token $PRIVATE_TOKEN

---

Package Metadata

All metadata goes in pyproject.toml:

[project]
name = "my-package"
version = "1.0.0"
description = "Short description"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "MIT"}
authors = [{name = "Author", email = "email@example.com"}]
keywords = ["keyword1", "keyword2"]
classifiers = [...]
dependencies = [...]

[project.urls]
Homepage = "https://github.com/user/repo"
Documentation = "https://docs.example.com"

---

Build Systems

Choose a build backend:

1. uv_build (recommended) - Fast, simple 2. setuptools - Traditional, widely supported 3. hatchling - Modern, feature-rich 4. flit - Minimal, simple 5. poetry-core - Poetry projects

---

Versioning Strategies

Manual

[project]
version = "1.0.0"

Dynamic (Git tags)

[project]
dynamic = ["version"]

[tool.uv]
version-provider = "git"

Semantic Versioning

• Major: Breaking changes (1.0.0 → 2.0.0)
• Minor: New features (1.0.0 → 1.1.0)
• Patch: Bug fixes (1.0.0 → 1.0.1)

---

Best Practices

1. Use src/ layout 2. Include comprehensive README 3. Add license file 4. Test on Test PyPI first 5. Use semantic versioning 6. Include type hints 7. Document public API 8. Add classifiers

---

References

• UV Publishing: https://docs.astral.sh/uv/guides/publish/
• PyPI: https://pypi.org/
• PEP 621: https://peps.python.org/pep-0621/ (pyproject.toml metadata)