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