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

Minimal Project:

Verification: Run pytest -v to verify tests pass. my-project/ ├── pyproject.toml ├── README.md ├── src/ │ └── my_package/ │ └── init.py └── tests/ └── test_init.py

Verification: Run pytest -v to verify tests pass.

Complete Project:

Verification: Run the command with --help flag to verify availability. my-project/ ├── pyproject.toml ├── README.md ├── LICENSE ├── .gitignore ├── src/ │ └── my_package/ │ ├── init.py │ ├── cli.py │ ├── core.py │ └── utils.py ├── tests/ │ ├── conftest.py │ └── test_core.py └── docs/ └── index.md

Verification: Run pytest -v to verify tests pass.

Detailed Topics

See modules for detailed information:

• uv Workflow - Complete uv commands and troubleshooting

• pyproject.toml Patterns - Configuration examples for different package types

• Entry Points - Console scripts, GUI scripts, and plugins

• CI/CD Integration - GitHub Actions and automated publishing

Best Practices

• Use source layout for anything beyond simple packages

• Pin direct dependencies with minimum versions

• Use optional dependency groups for dev/docs/test

• Include py.typed for type hint support

• Add detailed README with usage examples

• Use semantic versioning (MAJOR.MINOR.PATCH)

• Test on multiple Python versions before publishing

Exit Criteria

• Modern pyproject.toml configuration

• Clear dependency specification

• Proper version management

• Tests included and passing

• Build process reproducible

• Publishing pipeline automated