python-packaging
Create distributable Python packages with proper structure and publishing.Triggers: Python packaging, pyproject.toml, uv, pip, PyPI, distribution, CLI tools,entry points, package structure, publishingUse when: creating Python packages, configuring pyproject.toml, setting upentry points, publishing to PyPI, CI/CD for packagesDO 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.
When & Why to Use This Skill
This Claude skill streamlines the end-to-end process of creating, configuring, and distributing modern Python packages. By leveraging industry-standard tools like , , and , it helps developers establish professional project structures, manage complex dependencies, and automate the publishing workflow to PyPI, ensuring codebases are distributable and CI/CD ready.
Use Cases
- Project Scaffolding: Quickly initialize new Python projects with recommended source layouts, essential metadata, and standardized directory structures.
- CLI Tool Development: Configure entry points and console scripts to transform Python modules into executable command-line interfaces for distribution.
- PyPI Publishing & Distribution: Automate the build and upload process to PyPI or private registries, including version management and dependency pinning.
- CI/CD Integration: Set up automated pipelines for testing, building, and deploying Python packages using modern workflows like GitHub Actions.
| name | python-packaging |
|---|---|
| description | | |
| Triggers | Python packaging, pyproject.toml, uv, pip, PyPI, distribution, CLI tools, |
| Use when | creating Python packages, configuring pyproject.toml, setting up |
| DO NOT use when | optimizing package performance - use python-performance. |
| category | packaging |
| tags | [python, packaging, pyproject.toml, uv, pip, pypi, distribution] |
| tools | [package-analyzer, build-runner] |
| complexity | beginner |
| estimated_tokens | 200 |
| progressive_loading | true |
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
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