python-packaging

Python Packaging - Python 包打包与发布指南

技能概述

Python Packaging 提供创建可分发 Python 包的完整指导，涵盖项目结构、pyproject.toml 配置、wheel 构建以及 PyPI 发布全流程。

适用场景

创建 Python 库：将可复用的 Python 代码打包成库，方便他人通过 pip 安装使用

开发 CLI 工具：构建命令行应用程序，配置入口点实现全局命令调用

发布到 PyPI：将完成的 Python 包发布到 Python 包索引，供全球开发者使用

核心功能

项目结构初始化：创建符合 Python 打包标准的目录结构，包括必需的 __init__.py、README、LICENSE 等文件

构建配置管理：编写或生成 pyproject.toml 或 setup.py，配置元数据、依赖关系和入口点

打包与发布：使用 setuptools 或现代构建工具生成 wheel 和源码分发，通过 twine 或其他工具上传到 PyPI

常见问题

如何将 Python 项目发布到 PyPI？

发布流程包括：准备项目结构、编写 pyproject.toml 配置文件、使用构建工具生成分发包、在 PyPI 注册账号、使用 twine 上传包。首次发布需要注册包名，后续更新只需递增版本号重新上传。

setup.py 和 pyproject.toml 应该用哪个？

推荐使用 pyproject.toml，这是 Python 现代打包标准（PEP 518/621）的配置文件。setup.py 仍被广泛支持，但属于旧式方法。新项目应优先使用 pyproject.toml，除非需要兼容非常老的 Python 版本或使用尚未迁移的构建后端。

Python 打包需要哪些文件？

最小化打包需要：项目代码目录、pyproject.toml（或 setup.py）、README.md、LICENSE 文件。推荐还包括：MANIFEST.in（控制打包内容）、tests/ 目录、.github/ 工作流配置、以及 CHANGELOG.md 记录版本变更。