python-packaging

name	python-packaging
description	Python package creation and PyPI distribution via pyproject.toml and entry points. Use when publishing a package or setting up build configuration.
globs	**/*.py
alwaysApply	false
category	packaging
tags	["python","packaging","pyproject.toml","uv","pip","pypi","distribution"]
tools	[]
usage_patterns	["package-creation","pypi-publishing","cli-tool-development","library-distribution"]
complexity	beginner
model_hint	fast
estimated_tokens	200
progressive_loading	true
modules	["uv-workflow.md","pyproject-patterns.md","entry-points.md","ci-cd-integration.md"]

Table of Contents

• Quick Start
• When to Use
• Core Decisions
• 1. Layout Choice
• 2. Project Structure
• Detailed Topics
• Best Practices
• Exit Criteria

Python Packaging

Modern Python packaging with pyproject.toml, uv, and best practices for distribution.

Quick Start

# Create new project with uv
uv init my-package
cd my-package

# Add dependencies
uv add requests click

# Build package
uv build

# Publish to PyPI
uv publish

Verification: Run the command with --help flag to verify availability.

When To Use

• Creating distributable Python libraries
• Building CLI tools
• Publishing to PyPI
• Setting up development environments
• Managing project dependencies

When NOT To Use

• Testing packages - use python-testing instead
• Optimizing package performance - use python-performance
• Testing packages - use python-testing instead
• Optimizing package performance - use python-performance

Core Decisions

1. Layout Choice

# Source layout (recommended)
src/my_package/
    __init__.py
    module.py

# Flat layout (simple)
my_package/
    __init__.py
    module.py

Verification: Run the command with --help flag to verify availability.

Source layout benefits:

• Clear separation of source and tests
• Prevents accidental imports of uninstalled code
• Better for packages with complex structure

2. Project Structure