Python Packaging

Configure Python package metadata and build configuration for distribution.

Quick Start

Create pyproject.toml with UV or setuptools configuration for package distribution.

Instructions

Choosing Build System

Use UV with pyproject.toml (recommended) when:

Starting new projects
Want fast, modern tooling
Need dependency management + packaging
Building libraries for PyPI
Want PEP 621 compliance

Use setuptools (pyproject.toml + setup.py) when:

Maintaining existing projects
Need compatibility with older tools
Require custom build steps
Complex C extensions

Use setuptools (pyproject.toml only) when:

Modern setuptools-only approach
No custom build logic
Want declarative configuration
PEP 621 compliance

UV Configuration (Recommended)

Create

pyproject.toml

with UV (PEP 621 standard):

toml

[project]
name = "my-package"
version = "0.1.0"
description = "Package description"
readme = "README.md"
requires-python = ">=3.9"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "you@example.com"}
]
keywords = ["keyword1", "keyword2"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
]
dependencies = [
    "requests>=2.28.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "mypy>=1.0.0",
]

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

[project.urls]
Homepage = "https://github.com/username/my-package"
Repository = "https://github.com/username/my-package"

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

Key fields:

```
name
```
: Package name (use hyphens, will be converted to underscores for import)
```
version
```
: Semantic versioning (MAJOR.MINOR.PATCH)
```
requires-python
```
: Python version constraint
```
dependencies
```
: Runtime dependencies with version constraints
```
optional-dependencies
```
: Development and optional dependencies
```
scripts
```
: Console script entry points

Version constraints:

```
>=2.28.0,<3.0.0
```
: Compatible versions
```
~=2.28.0
```
: >=2.28.0, <2.29.0 (patch updates)
```
>=2.28.0
```
: Minimum version
```
==2.28.0
```
: Exact version

Setuptools Configuration (Modern)

Create

pyproject.toml

with setuptools (PEP 621):

toml

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

[project]
name = "my-package"
version = "0.1.0"
description = "Package description"
readme = "README.md"
requires-python = ">=3.9"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "you@example.com"}
]
keywords = ["keyword1", "keyword2"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
]
dependencies = [
    "requests>=2.28.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "mypy>=1.0.0",
]

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

[project.urls]
Homepage = "https://github.com/username/my-package"
Repository = "https://github.com/username/my-package"

Setuptools Configuration (Legacy)

Create

setup.py

for projects requiring custom build logic:

python

from setuptools import setup, find_packages

setup(
    name="my-package",
    version="0.1.0",
    description="Package description",
    long_description=open("README.md").read(),
    long_description_content_type="text/markdown",
    author="Your Name",
    author_email="you@example.com",
    url="https://github.com/username/my-package",
    packages=find_packages(where="src"),
    package_dir={"": "src"},
    python_requires=">=3.9",
    install_requires=[
        "requests>=2.28.0",
    ],
    extras_require={
        "dev": [
            "pytest>=7.0.0",
            "black>=23.0.0",
            "mypy>=1.0.0",
        ],
    },
    entry_points={
        "console_scripts": [
            "my-cli=my_package.cli:main",
        ],
    },
    classifiers=[
        "Development Status :: 3 - Alpha",
        "Intended Audience :: Developers",
        "License :: OSI Approved :: MIT License",
        "Programming Language :: Python :: 3",
    ],
)

When to use setup.py:

Custom build steps (compiling C extensions)
Dynamic version from git tags
Complex package discovery
Conditional dependencies

Package Structure

Flat layout:

my-package/
├── my_package/
│   ├── __init__.py
│   └── module.py
├── tests/
├── pyproject.toml
└── README.md

Src layout (recommended for libraries):

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

For src layout, configure package discovery:

UV/Hatchling (pyproject.toml):

toml

[tool.hatch.build.targets.wheel]
packages = ["src/my_package"]

Setuptools (pyproject.toml):

toml

[tool.setuptools.packages.find]
where = ["src"]

Setuptools (setup.py):

python

packages=find_packages(where="src"),
package_dir={"": "src"},

Version Management

Static version in pyproject.toml:

toml

[project]
version = "0.1.0"

Dynamic version from file:

toml

[project]
dynamic = ["version"]

[tool.setuptools.dynamic]
version = {attr = "my_package.__version__"}

Then in

src/my_package/__init__.py

python

__version__ = "0.1.0"

Dynamic version from git tags (requires setup.py):

python

from setuptools import setup
from setuptools_scm import get_version

setup(
    use_scm_version=True,
    setup_requires=["setuptools_scm"],
)

Entry Points and Scripts

Console scripts create command-line tools:

toml

[project.scripts]
my-cli = "my_package.cli:main"
another-tool = "my_package.tools:run"

This creates executables that call the specified functions.

Entry point function:

python

# my_package/cli.py
def main():
    print("Hello from my-cli!")
    
if __name__ == "__main__":
    main()

Including Data Files

Include package data:

toml

[tool.setuptools.package-data]
my_package = ["data/*.json", "templates/*.html"]

Include non-package files:

Create

MANIFEST.in

include README.md
include LICENSE
recursive-include src/my_package/data *

Classifiers

Use PyPI classifiers to categorize your package:

toml

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.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    
    # Topics
    "Topic :: Software Development :: Libraries",
    "Topic :: Internet :: WWW/HTTP",
]

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

Building and Publishing

With UV (recommended):

bash

# Build distribution
uv build

# Publish to PyPI
uv publish

# Or use twine
uv build
twine upload dist/*

With setuptools:

bash

# Install build tools
pip install build twine

# Build distribution
python -m build

# Publish to PyPI
twine upload dist/*

Testing Installation

Test your package locally before publishing:

bash

# Install in editable mode with UV
uv pip install -e .

# Or with pip
pip install -e .

# Test the package
python -c "import my_package; print(my_package.__version__)"

# Test console scripts
my-cli --help

Common Patterns

Multi-Package Project

For projects with multiple packages:

toml

[tool.hatch.build.targets.wheel]
packages = ["src/package1", "src/package2"]

Optional Dependencies

Group optional features:

toml

[project.optional-dependencies]
dev = ["pytest", "black", "mypy"]
docs = ["sphinx", "sphinx-rtd-theme"]
aws = ["boto3"]
all = ["pytest", "black", "mypy", "sphinx", "boto3"]

Install with:

pip install my-package[dev]

pip install my-package[all]

Platform-Specific Dependencies

toml

[project]
dependencies = [
    "requests",
    "pywin32; platform_system=='Windows'",
    "python-daemon; platform_system=='Linux'",
]

Validation

Before publishing, verify:

Package builds successfully:
bash
```
uv build  # or python -m build
```
Metadata is correct:
bash
```
twine check dist/*
```
Installation works:
bash
```
uv pip install dist/*.whl
```
Entry points work:
bash
```
my-cli --version
```

Imports work:

python

import my_package
print(my_package.__version__)

Troubleshooting

Package not found after installation:

Check package name vs. import name (hyphens vs. underscores)
Verify package discovery configuration
Ensure
```
__init__.py
```
exists in package directory

Entry points not working:

Verify function signature (should take no arguments or use argparse)

Check entry point syntax:

"script-name = "package.module:function"

Reinstall package after changes

Data files not included:

Add to
```
package-data
```
in pyproject.toml
Or create MANIFEST.in
Verify with:
```
python -m tarfile -l dist/*.tar.gz
```

Version conflicts:

Use compatible version constraints (
```
>=,<
```
syntax)
Test with different dependency versions
UV automatically creates lock files for reproducibility

python-packaging

NPX Install

Tags

SKILL.md Content

Python Packaging

Quick Start

Instructions

Choosing Build System

UV Configuration (Recommended)

Setuptools Configuration (Modern)

Setuptools Configuration (Legacy)

Package Structure

Version Management

Entry Points and Scripts

Including Data Files

Classifiers

Building and Publishing

Testing Installation

Common Patterns

Multi-Package Project

Optional Dependencies

Platform-Specific Dependencies

Validation

Troubleshooting