python-packaging

athola's avatarfrom athola

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.

⭐83stars🔀11forks📁View on GitHub🕐Updated Jan 3, 2026

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.
namepython-packaging
description|
TriggersPython packaging, pyproject.toml, uv, pip, PyPI, distribution, CLI tools,
Use whencreating Python packages, configuring pyproject.toml, setting up
DO NOT use whenoptimizing package performance - use python-performance.
categorypackaging
tags[python, packaging, pyproject.toml, uv, pip, pypi, distribution]
tools[package-analyzer, build-runner]
complexitybeginner
estimated_tokens200
progressive_loadingtrue

Table of Contents

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:

Best Practices

  1. Use source layout for anything beyond simple packages
  2. Pin direct dependencies with minimum versions
  3. Use optional dependency groups for dev/docs/test
  4. Include py.typed for type hint support
  5. Add detailed README with usage examples
  6. Use semantic versioning (MAJOR.MINOR.PATCH)
  7. 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