Python项目PyPI包发布指南

将python项目打包并发布到pypi（python package index）是提升项目可访问性和复用性的关键一步。通过pypi，全球的开发者都可以使用pip install your-package-name命令轻松安装和使用您的代码。本指南将详细阐述将python项目转化为可分发pypi包的完整过程。

项目结构调整：拥抱 src 目录

在开始打包之前，建议对项目目录结构进行优化。采用src布局是一种最佳实践，它将实际的包代码与项目中的其他文件（如测试、文档、示例等）清晰地分离。这种结构有助于避免在打包时包含不必要的开发文件，并确保包的导入行为与安装后一致。

推荐的目录结构示例：

my_project/
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── main.py
├── tests/
│   └── test_main.py
├── docs/
├── .gitignore
├── pyproject.toml
├── README.md
└── LICENSE

在这个结构中，my_package是您希望发布到PyPI的实际Python包。所有可安装的代码都应位于src/my_package/目录下。

核心配置：pyproject.toml 文件详解

pyproject.toml是现代Python项目用于定义构建系统和项目元数据的文件。它取代了传统的setup.py和setup.cfg，提供了更统一和声明式的配置方式。

立即学习“Python免费学习笔记（深入）”；

在项目根目录下创建pyproject.toml文件，并按以下结构填充：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-ai-assistant" # 您的包名，应在PyPI上唯一
version = "0.1.0"         # 包的版本号，遵循语义化版本控制
description = "An open-source AI coding assistant written in Python." # 包的简短描述
readme = "README.md"      # 指向您的README文件
requires-python = ">=3.8" # 包所需的Python版本
license = { text = "MIT License" } # 许可证信息，或使用 file = "LICENSE"
authors = [
    { name = "Your Name", email = "your.email@example.com" },
]
keywords = ["ai", "coding", "assistant", "python"] # 关键词，方便搜索
classifiers = [ # 分类器，描述包的特性和兼容性
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
    "Development Status :: 3 - Alpha", # 开发状态
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Libraries :: Python Modules",
]
dependencies = [ # 包的运行时依赖
    "requests>=2.28.1",
    "openai>=0.27.0",
    # 更多依赖...
]

[project.urls]
Homepage = "https://github.com/00-Python/AI-Debug" # 项目主页
Repository = "https://github.com/00-Python/AI-Debug" # 代码仓库
Issues = "https://github.com/00-Python/AI-Debug/issues" # 问题跟踪

[project.optional-dependencies]
dev = [ # 开发环境依赖，例如用于测试或文档生成
    "pytest>=7.0",
    "build>=0.10.0",
    "twine>=4.0.0",
]

# 如果您的包需要查找 src 目录下的模块，需要此配置
[tool.setuptools.packages.find]
where = ["src"] # 查找包的目录

关键字段说明：

• [build-system]: 定义了构建包所需的工具链。setuptools是常用的构建后端。
• [project]: 包含包的所有核心元数据。
  • name: 包在PyPI上的名称，必须是唯一的。
  • version: 包的版本号，推荐遵循语义化版本控制（例如MAJOR.MINOR.PATCH）。
  • description、readme、requires-python、license、authors、keywords、classifiers：提供包的详细信息，有助于用户了解和发现您的包。
  • dependencies: 列出您的包运行时所依赖的其他PyPI包。
• [project.urls]: 提供项目相关的外部链接。
• [project.optional-dependencies]: 定义可选的依赖项组，例如用于开发、测试或特定功能。
• [tool.setuptools.packages.find]: 如果您的代码位于src目录下，此配置告知setuptools在哪里查找包。

构建分发包：生成轮子与源码包

配置好pyproject.toml后，您可以使用build工具来生成可分发的包文件。首先，确保您已安装build工具：

pip install build

然后，在项目的根目录下执行构建命令：

FashionLabs

AI服装模特、商品图，可商用，低价提升销量神器

38

查看详情

python -m build

执行成功后，会在项目根目录下生成一个dist/目录。该目录通常包含两个文件：

• .whl文件（Wheel）：这是一个预编译的二进制分发包，通常包含纯Python代码和一些元数据，可以直接安装，速度快。
• .tar.gz文件（Source Distribution）：这是一个源码分发包，包含包的源代码和构建信息，可以在目标机器上进行编译安装。

这两个文件就是您的PyPI包，它们将上传到PyPI供用户下载。

发布上线：使用 twine 上传至 PyPI

将构建好的包上传到PyPI需要使用twine工具。twine是一个安全的上传工具，它能确保您的包在上传过程中不会被篡改。

1. 安装 twine：

   pip install twine

   登录后复制

2. 创建 PyPI 账户和 API Token： 如果您还没有PyPI账户，请访问PyPI官网注册。 为了安全起见，推荐使用API Token进行认证，而不是直接使用用户名和密码。登录PyPI账户后，导航到“Account settings” -> “API tokens”，生成一个新的API Token。请务必保存好生成的Token，因为它只显示一次。

3. 上传包： 在项目根目录下，执行以下命令上传dist/目录中的所有包文件：

   python -m twine upload dist/*

   登录后复制

   twine会提示您输入PyPI用户名（通常是__token__）和API Token作为密码。

   提示： 在正式发布到PyPI之前，您可以使用TestPyPI进行测试。TestPyPI是一个用于测试包上传和安装的沙盒环境。上传到TestPyPI的命令是：

   python -m twine upload --repository testpypi dist/*

   登录后复制

   在TestPyPI上测试成功后，再上传到正式的PyPI。

重要提示与最佳实践

• 版本管理： 每次发布新版本时，务必更新pyproject.toml中的version字段。遵循语义化版本控制（MAJOR.MINOR.PATCH）有助于用户理解版本间的兼容性。
• 许可证（License）： 在您的项目中包含一个LICENSE文件是至关重要的。它明确了他人如何使用您的代码。选择一个合适的开源许可证，并在pyproject.toml中正确声明。
• README.md： 一个清晰、详细的README.md文件是包的门面。它应该包含项目的简介、安装指南、使用示例、API文档链接等，帮助用户快速上手。
• 虚拟环境： 在开发和打包过程中始终使用Python虚拟环境（如venv或conda），以避免依赖冲突和污染全局Python环境。
• 测试： 在发布任何版本之前，务必对您的包进行彻底的测试，确保其功能完善且稳定。

通过遵循上述步骤和最佳实践，您将能够成功地将您的Python项目打包并发布到PyPI，让更多开发者能够发现、使用并贡献您的开源项目。

以上就是Python项目PyPI包发布指南的详细内容，更多请关注php中文网其它相关文章！