# Python Packaging

> Create distributable Python packages with proper project structure, setup.py/pyproject.toml, and publishing to PyPI. Use when packaging Python libraries, creating CLI tools, or distributing Python code.

Source: https://skillsagentes.com/skills/wshobson/agents/python-packaging
Repository: https://github.com/wshobson/agents
Author: wshobson
License: MIT
Updated: hace 2 meses
Context cost: 51 tok installed, 983 tok once triggered, 4.5k tok with every bundled file
Bundle: 3 files, 18 KB
Permissions requested: none declared

## Install

```bash
npx -y skills add wshobson/agents --skill python-packaging --agent claude-code
```

## What it does

- Guía la creación de estructura de proyecto Python (source layout o flat layout) con pyproject.toml
- Configura sistemas de build (setuptools, hatchling, flit, poetry) y metadatos según PEP 517/518/621
- Explica cómo generar wheels y source distributions y publicarlas en PyPI/TestPyPI o repositorios privados
- Ayuda a definir entry points para herramientas CLI y dependencias opcionales

## Use it when

- Crear librerías Python para distribución
- Construir herramientas de línea de comandos con entry points
- Publicar paquetes en PyPI o repositorios privados
- Configurar estructura de proyecto Python o versionar/lanzar paquetes

## What triggers it

- "Ayúdame a estructurar mi librería Python para publicarla en PyPI"
- "Necesito un pyproject.toml para mi paquete con entry points de CLI"
- "Quiero migrar mi setup.py a pyproject.toml"

## Before you install

- Para casos detallados, consulta el archivo references/details.md incluido en el skill.

## Files

- SKILL.md — 4 KB
- references/advanced-patterns.md — 7 KB
- references/details.md — 7 KB

## SKILL.md

Reproduced verbatim from wshobson/agents under MIT. This section is the upstream document and is in English.

# 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

```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:**

```toml
[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.

---

Skills Agentes — https://skillsagentes.com/skills/wshobson/agents/python-packaging