将python项目打包并发布到pypi（python package index）是让您的代码被全球python社区轻松发现和使用的关键一步。一旦项目成功发布，用户便可以通过简单的pip install your-package-name命令进行安装。本教程将引导您完成从项目准备到最终发布的每一个环节。
1. 准备项目结构
为了确保打包过程的顺畅和包内容的清晰，推荐采用标准的项目结构，特别是将核心代码放置在src目录下。这种结构有助于明确区分可分发代码与项目中的其他文件（如测试、文档、示例等）。
推荐的项目结构示例：
your_project_name/ ├── src/ │ └── your_package_name/ │ ├── __init__.py │ └── module1.py │ └── module2.py ├── tests/ │ └── test_module1.py ├── docs/ ├── .gitignore ├── README.md ├── LICENSE └── pyproject.toml
- src/your_package_name/: 这是您的实际Python包代码所在的位置。your_package_name应是您希望用户在import时使用的名称。
- __init__.py: 使your_package_name目录成为一个Python包。
- README.md: 包含项目的描述、安装指南、使用示例等信息。
- LICENSE: 您的项目所遵循的开源许可证文件。
2. 配置 pyproject.toml 文件
pyproject.toml是现代Python项目打包的核心配置文件，它定义了项目的元数据和构建系统信息。它取代了旧的setup.py和setup.cfg，提供了更统一和标准化的配置方式。
首先，确保您的环境中安装了setuptools和wheel，它们是构建Python包的常用工具：
立即学习“Python免费学习笔记（深入）”；
pip install setuptools wheel
然后，在项目根目录下创建或编辑pyproject.toml文件。以下是一个基本的配置示例：
[build-system]
requires = ["setuptools>=61.0.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "your-package-name" # 包在PyPI上的名称，通常与您的项目名称一致
version = "0.1.0" # 包的版本号，遵循语义化版本规范（MAJOR.MINOR.PATCH）
authors = [
{ name="Your Name", email="your.email@example.com" },
]
description = "A short description of your awesome Python package." # 包的简短描述
readme = "README.md" # 指向您的README文件
requires-python = ">=3.7" # 包运行所需的Python版本
classifiers = [ # 分类器，帮助用户在PyPI上找到您的包
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
"Topic :: Software Development :: Libraries :: Python Modules",
]
keywords = ["AI", "Assistant", "Debug"] # 关键词，提高可搜索性
# 可选：定义项目依赖
dependencies = [
"requests>=2.25.1",
"numpy",
]
# 可选：定义项目URL，如主页、问题追踪器等
[project.urls]
"Homepage" = "https://github.com/your_username/your_project_name"
"Bug Tracker" = "https://github.com/your_username/your_project_name/issues"
# 可选：如果您的包有命令行脚本，可以在这里定义
# [project.scripts]
# your-command = "your_package_name.cli:main"
# 可选：如果您的包需要包含非Python文件，如数据文件、图片等
# [tool.setuptools.package-data]
# your_package_name = ["data/*.txt"]关键字段说明：
- [build-system]: 定义构建包所需的工具和后端。setuptools和wheel是标准选择。
- [project]: 包含包的所有元数据。
- name: 包在PyPI上的唯一名称。
- version: 包的版本号，每次发布新版本时都需要更新。
- authors: 包的作者信息。
- description: 包的简短描述。
- readme: 指向项目的README.md文件。
- requires-python: 兼容的Python版本范围。
- classifiers: PyPI提供的分类标签，有助于用户发现您的包。
- dependencies: 包运行时所需的其他Python库及其版本范围。
3. 构建分发包
配置好pyproject.toml后，您可以使用build工具来生成分发包。如果尚未安装，请先安装它：
pip install build
在项目根目录下运行构建命令：
python -m build
执行成功后，会在您的项目根目录下生成一个名为dist/的目录。这个目录中会包含两个文件：
- .whl文件（wheel）：这是一个预编译的二进制分发包，通常用于快速安装。
- .tar.gz文件（source distribution）：这是一个源代码分发包，包含项目的原始代码。
这两个文件就是您将要上传到PyPI的包。
4. 上传到 PyPI
在将包上传到PyPI之前，强烈建议您先上传到TestPyPI进行测试。TestPyPI是一个用于测试包发布流程的沙盒环境，不会影响真实的PyPI。
简约流程导航箭头编号矢量模板适用于科技公司的宣传材料、商务演示文稿、产品发布会议的背景板、创新项目的报告封面、科技论坛和研讨会的邀请函、科学展览的指南、科技产品的用户界面、未来主义风格的概念艺术等与科技和商业推广相关设计的AI格式素材。
4.1 注册 PyPI 和 TestPyPI 账号
访问以下链接注册账号：
- TestPyPI: https://www.php.cn/link/b62510e29bba2eb5af6ba88c3dce08e0
- PyPI: https://www.php.cn/link/1f6325d1b1080e812e7b713ae61f4ebc
为了安全起见，推荐使用API令牌进行身份验证，而不是用户名和密码。在您的账号设置页面生成API令牌，并妥善保存。
4.2 安装 Twine
twine是一个安全的PyPI上传工具：
pip install twine
4.3 上传到 TestPyPI（强烈推荐）
使用您的TestPyPI API令牌上传：
twine upload --repository testpypi dist/*
当提示输入用户名时，输入__token__。当提示输入密码时，粘贴您的TestPyPI API令牌（以pypi-开头）。
上传成功后，您可以在TestPyPI网站上找到您的包，并通过pip install --index-url https://test.pypi.org/simple/ --no-deps your-package-name来测试安装。
4.4 上传到 PyPI
在确认您的包在TestPyPI上运行正常后，您可以将其上传到真实的PyPI：
twine upload dist/*
同样，当提示输入用户名时，输入__token__。当提示输入密码时，粘贴您的PyPI API令牌。
上传成功后，您的包将可在PyPI上公开访问，并可以通过pip install your-package-name进行安装。
注意事项
- 版本管理： 每次发布新版本时，务必在pyproject.toml中更新version字段。遵循语义化版本规范（Semantic Versioning）有助于用户理解版本间的兼容性。
- 许可证： 务必在项目中包含一个LICENSE文件，明确您的项目所遵循的开源许可证。这对于开源项目至关重要。
- README文件： 编写一个清晰、详细的README.md文件，包含项目简介、安装方法、使用示例、API文档链接等。这是用户了解您项目的第一站。
- 依赖管理： 在dependencies中准确列出所有直接依赖，并尽可能使用版本范围限制，以避免未来的兼容性问题。
- 持续集成/部署 (CI/CD)： 对于更复杂的项目，考虑设置CI/CD流程，自动化测试和发布过程。
总结
通过遵循本文的指南，您已掌握了将Python项目打包并发布到PyPI的关键步骤。这不仅让您的项目更易于分发和使用，也为您的代码贡献给更广阔的Python生态系统打开了大门。持续维护您的包，及时发布更新，将有助于您的项目获得更广泛的采纳和认可。
