chore: import upstream snapshot with attribution

2026-07-13 12:36:35 +08:00
commit d389869988
1095 changed files with 222202 additions and 0 deletions
@@ -0,0 +1,166 @@
+---
+name: python-packaging
+description: 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.
+---
+
+# 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.
+