python-packaging by wshobson

Python Packaging

Comprehensive guide to creating, structuring, and distributing Python packages using modern packaging tools, pyproject.toml, and publishing to PyPI.

When to Use This Skill

Creating Python libraries for distribution
Building command-line tools with entry points
Publishing packages to PyPI or private repositories
Setting up Python project structure
Creating installable packages with dependencies
Building wheels and source distributions
Versioning and releasing Python packages
Creating namespace packages
Implementing package metadata and classifiers

Core Concepts

1. Package Structure

Source layout: src/package_name/ (recommended)
Flat layout: package_name/ (simpler but less flexible)
Package metadata: pyproject.toml, setup.py, or setup.cfg
Distribution formats: wheel (.whl) and source distribution (.tar.gz)

2. Modern Packaging Standards

PEP 517/518: Build system requirements
PEP 621: Metadata in pyproject.toml
PEP 660: Editable installs
pyproject.toml: Single source of configuration

3. Build Backends

setuptools: Traditional, widely used
hatchling: Modern, opinionated
flit: Lightweight, for pure Python
poetry: Dependency management + packaging

4. Distribution

PyPI: Python Package Index (public)
TestPyPI: Testing before production
Private repositories: JFrog, AWS CodeArtifact, etc.

Quick Start

Minimal Package Structure

my-package/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── module.py
└── tests/
    └── test_module.py

Minimal pyproject.toml

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
version = "0.1.0"
description = "A short description"
authors = [{name = "Your Name", email = "you@example.com"}]
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=22.0",
]

Package Structure Patterns

Pattern 1: Source Layout (Recommended)

my-package/
├── pyproject.toml
├── README.md
├── LICENSE
├── .gitignore
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core.py
│       ├── utils.py
│       └── py.typed          # For type hints
├── tests/
│   ├── __init__.py
│   ├── test_core.py
│   └── test_utils.py
└── docs/
    └── index.md

Advantages:

Prevents accidentally importing from source
Cleaner test imports
Better isolation

pyproject.toml for source layout:

[tool.setuptools.packages.find]
where = ["src"]

Pattern 2: Flat Layout

my-package/
├── pyproject.toml
├── README.md
├── my_package/
│   ├── __init__.py
│   └── module.py
└── tests/
    └── test_module.py

Simpler but:

Can import package without installing
Less professional for libraries

Pattern 3: Multi-Package Project

project/
├── pyproject.toml
├── packages/
│   ├── package-a/
│   │   └── src/
│   │       └── package_a/
│   └── package-b/
│       └── src/
│           └── package_b/
└── tests/

Detailed patterns and worked examples

Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.

Third-party checks

No alerts1d5 checks · Risk SAFE

Gen Agent Trust Hub1d
This skill is a comprehensive guide to Python packaging. It provides templates and best practices for creating, building, and distributing Python libraries and CLI tools using standard industry tools like setuptools, build, and twine. No security issues were detected.
Socket1d
No alerts
Snyk1d
Risk: LOW · No issues
Runlayer6mo
1/1 file flagged
ZeroLeaks5mo
Score: 93/100 · 2 sections analyzed

What it does

Instructs Claude and other AI agents on creating and distributing Python packages using modern standards like pyproject.toml, setuptools, and PyPI. Covers package structure patterns (source layout, flat layout, multi-package), build backends, and publishing workflows.

Generated from the current SKILL.md.

Frequently asked

Does this skill cover publishing to PyPI?

Yes. The skill includes publishing to PyPI, TestPyPI, and private repositories like JFrog and AWS CodeArtifact.

Which build backends does this skill support?

The skill covers setuptools, hatchling, flit, and poetry. setuptools is the traditional choice; hatchling and flit are modern alternatives; poetry handles both packaging and dependency management.

What Python versions does this cover?

The skill teaches how to specify minimum Python versions via requires-python in pyproject.toml. The minimal example shows Python 3.8+, but you set your own requirements.

Does this cover CLI tools with entry points?

Yes. The skill lists building command-line tools with entry points as a core use case, though specific entry point syntax is in the detailed pattern documentation.

What's the recommended package structure?

Source layout (src/package_name/) is recommended. It prevents accidentally importing from source and provides better isolation than flat layout.

Generated from the current SKILL.md. These answers refresh after source changes.

/python-packaging

SKILL.md