mcpField
P
python-packaging

python-packaging

github.com/wshobson开发41.9k13.1k 次安装2 周前更新
代码仓库

关于 python-packaging

这项技能介绍如何使用现代打包规范组织、构建和分发 Python 包，面向开发库或命令行工具的开发者，并涵盖发布流程。

主要功能

  1. 01源码布局与扁平布局
  2. 02pyproject.toml 与打包规范
  3. 03构建后端选择
  4. 04Wheel 与源码分发包
  5. 05发布到包仓库

适用场景

  1. 01创建可分发的 Python 库
  2. 02通过入口点构建命令行工具
  3. 03发布到 PyPI 或私有仓库
  4. 04管理版本并准备包发布

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wshobson/agents --skill python-packaging

安装后在 Claude Code 中输入/python-packaging确认已加载。

附带文件references/advanced-patterns.mdreferences/details.md

详细介绍

Python 打包

使用现代打包工具、pyproject.toml 创建、组织 Python 包并发布到 PyPI 的全面指南。

何时使用本技能

  • 创建用于分发的 Python 库
  • 使用入口点构建命令行工具
  • 将包发布到 PyPI 或私有仓库
  • 搭建 Python 项目结构
  • 创建带依赖的可安装包
  • 构建 wheel 和源码分发
  • 对 Python 包进行版本管理与发布
  • 创建命名空间包
  • 实现包元数据与分类器

核心概念

1. 包结构
  • 源码布局：src/package_name/（推荐）
  • 扁平布局：package_name/（更简单但灵活性较差）
  • 包元数据：pyproject.toml、setup.py 或 setup.cfg
  • 分发格式：wheel（.whl）和源码分发（.tar.gz）
2. 现代打包标准
  • PEP 517/518：构建系统要求
  • PEP 621：pyproject.toml 中的元数据
  • PEP 660：可编辑安装
  • pyproject.toml：单一配置来源
3. 构建后端
  • setuptools：传统方案，使用广泛
  • hatchling：现代方案，有明确约定
  • flit：轻量级，适用于纯 Python
  • poetry：依赖管理 + 打包
4. 分发
  • PyPI：Python Package Index（公开）
  • TestPyPI：生产前的测试环境
  • 私有仓库：JFrog、AWS CodeArtifact 等

快速开始

最小包结构
my-package/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── module.py
└── tests/
    └── test_module.py
最小 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 = "[email protected]"}]
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
]

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

包结构模式

模式 1：源码布局（推荐）
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

优势：

  • 防止意外从源码导入
  • 更清晰的测试导入
  • 更好的隔离性

适用于源码布局的 pyproject.toml：

[tool.setuptools.packages.find]
where = ["src"]
模式 2：扁平布局
my-package/
├── pyproject.toml
├── README.md
├── my_package/
│   ├── __init__.py
│   └── module.py
└── tests/
    └── test_module.py

更简单，但是：

  • 无需安装即可导入包
  • 对于库来说不够专业
模式 3：多包项目
project/
├── pyproject.toml
├── packages/
│   ├── package-a/
│   │   └── src/
│   │       └── package_a/
│   └── package-b/
│       └── src/
│           └── package_b/
└── tests/

详细模式与完整示例

详细的模式文档位于 references/details.md。当上方的导航层级不够用时，请阅读该文件。

评论

支持 Markdown