python-packaging

来源声明：本技能内容源自 wshobson/agents （MIT License, Copyright (c) 2024 Seth Hobson；完整许可文本见同目录 LICENSE.txt）。 使用、修改与再分发须遵守该 MIT 许可条款并保留版权声明。

中文描述

本技能提供全栈开发相关的最佳实践和模式指导。

---

name: python-packaging description: 使用合适的项目结构、setup.py/pyproject.toml 和 PyPI 发布流程，创建可分发的 Python 包。适用于打包 Python 库、创建 CLI 工具或分发 Python 代码。

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 包索引（公共）
• 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。如果上文的导航层级无法满足需求，请阅读该文件。

能力边界

✅ 擅长处理

• 全栈开发相关的最佳实践
• 代码架构设计指导
• 性能优化建议

⚠️ 需要素材

• 具体的项目上下文
• 技术栈信息

❌ 超出范围

• 非技术领域的业务决策
• 具体的代码实现（仅提供指导）

工作流程

步骤 1：需求分析

理解项目需求和技术约束

步骤 2：架构设计

设计系统架构和组件划分

步骤 3：实现指导

提供具体的实现建议和代码模式

步骤 4：代码审查

审查代码质量和最佳实践遵循情况

步骤 5：优化建议

提供性能优化和改进建议

注意事项

1. 过度设计

避免在简单场景中使用复杂的设计模式

2. 忽视性能

不要忽视性能优化，特别是在生产环境中

3. 安全考虑

始终考虑安全性和数据保护

4. 测试覆盖

确保有足够的测试覆盖，特别是边界情况

5. 文档维护

保持文档与代码同步更新