| name | python-packaging |
| description | Create distributable Python packages with proper structure and publishing. Triggers: Python packaging, pyproject.toml, uv, pip, PyPI, distribution, CLI tools, entry points, package structure, publishing Use when: creating Python packages, configuring pyproject.toml, setting up entry points, publishing to PyPI, CI/CD for packages DO NOT use when: testing packages - use python-testing instead. DO NOT use when: optimizing package performance - use python-performance. Consult this skill for Python package creation and distribution. |
| category | packaging |
| tags | python, packaging, pyproject.toml, uv, pip, pypi, distribution |
| tools | package-analyzer, build-runner |
| usage_patterns | package-creation, pypi-publishing, cli-tool-development, library-distribution |
| complexity | beginner |
| estimated_tokens | 200 |
| progressive_loading | true |
| modules | uv-workflow.md, pyproject-patterns.md, entry-points.md, ci-cd-integration.md |
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
When to Use
- Creating distributable Python libraries
- Building CLI tools
- Publishing to PyPI
- Setting up development environments
- Managing project dependencies
Core Decisions
1. Layout Choice
# Source layout (recommended)
src/my_package/
__init__.py
module.py
# Flat layout (simple)
my_package/
__init__.py
module.py
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:
my-project/
├── pyproject.toml
├── README.md
├── src/
│ └── my_package/
│ └── __init__.py
└── tests/
└── test_init.py
Complete Project:
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
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 comprehensive 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