如何将Python项目打包并发布到PyPI

1. 理解项目结构与准备

在将python项目打包为可分发的pypi包之前，首要任务是确保项目结构清晰且符合打包规范。现代python打包推荐使用src布局，即将所有源代码放在一个名为src的子目录中。

推荐的项目结构示例：

your_project_name/
├── src/
│   └── your_package_name/
│       ├── __init__.py
│       └── your_module.py
├── tests/
│   └── test_your_package.py
├── .gitignore
├── LICENSE
├── README.md
└── pyproject.toml

关键点：

• src/目录： 您的实际Python包代码应位于此目录下。例如，如果您的包名为my_ai_assistant，那么路径将是src/my_ai_assistant/。这样做的好处是，可以清晰地将源代码与项目根目录下的其他文件（如测试、文档、构建配置等）区分开来，避免在打包时误包含不必要的开发文件。
• __init__.py： 确保您的包目录（例如src/your_package_name/）包含一个__init__.py文件（即使是空的），这表示该目录是一个Python包。
• 非代码文件： 像测试文件（tests/）、文档（docs/）、示例代码、CI/CD配置文件等，不应包含在src目录内，因为它们不是最终用户安装包时所需的运行时代码。

2. 配置 pyproject.toml 文件

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

在项目根目录创建pyproject.toml文件，并根据您的项目信息进行配置。以下是一个典型的pyproject.toml示例：

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

[build-system]
requires = ["setuptools>=61.0.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "ai-debug-assistant" # 您的包在PyPI上的名称
version = "0.1.0"           # 包的版本号
authors = [
  { name="Your Name", email="your.email@example.com" },
]
description = "An open source AI Coding Assistant for debugging Python projects." # 简短描述
readme = "README.md"        # 指向您的README文件
requires-python = ">=3.8"   # 兼容的Python版本
classifiers = [             # 分类器，帮助用户发现您的包
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
    "Development Status :: 3 - Alpha", # 开发状态，如Alpha, Beta, Production/Stable
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Libraries :: Python Modules",
    "Topic :: Scientific/Engineering :: Artificial Intelligence",
]
keywords = ["AI", "debugging", "python", "assistant"] # 关键词

dependencies = [            # 运行时依赖
    "requests>=2.28.1",
    "openai>=1.0.0",
    # 其他依赖...
]

[project.urls]
"Homepage" = "https://github.com/00-Python/AI-Debug" # 项目主页
"Bug Tracker" = "https://github.com/00-Python/AI-Debug/issues" # Bug跟踪器
"Source" = "https://github.com/00-Python/AI-Debug" # 源代码链接

[project.optional-dependencies] # 可选依赖，例如用于测试或文档
dev = [
    "pytest>=7.0",
    "flake8>=6.0",
]

配置说明：

• [build-system]： 定义了构建包所需的工具。setuptools和wheel是常用的构建后端。
• [project]： 包含了包的所有核心元数据。
  • name：您的包在PyPI上显示的名称，通常与您的项目名称一致。
  • version：遵循语义化版本（Semantic Versioning）规范，例如MAJOR.MINOR.PATCH。
  • authors：作者信息。
  • description：项目的简短描述。
  • readme：指向您的README.md文件，PyPI会将其作为包的详细描述。
  • requires-python：指定包兼容的Python版本范围。
  • classifiers：一系列描述包属性的字符串，用于PyPI上的分类和搜索。
  • keywords：有助于搜索的关键词。
  • dependencies：列出项目运行时所需的所有第三方库及其版本约束。
• [project.urls]： 提供项目相关的外部链接。
• [project.optional-dependencies]： 定义可选的依赖项组，例如开发、测试或文档构建所需的依赖。

3. 构建分发包

配置好pyproject.toml后，您就可以构建项目的分发包了。Python官方推荐使用build工具来完成此任务。

首先，确保您已安装build工具：

pip install build

然后，在您的项目根目录（即pyproject.toml所在的目录）运行构建命令：

python -m build

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

• .whl文件（Wheel）：这是一种预编译的二进制分发格式，安装速度快，推荐用于大多数用户。
• .tar.gz文件（Source Distribution）：这是一个源码分发包，包含所有源代码和元数据，允许在安装时进行编译。

4. 发布到 PyPI

有了构建好的分发包，最后一步就是将它们上传到PyPI。这通常通过twine工具完成。

4.1 安装 Twine

pip install twine

4.2 创建 PyPI 账户与 API Token

如果您还没有PyPI账户，请访问 pypi.org 注册一个。

落笔AI

AI写作，AI写网文、AI写长篇小说、短篇小说

41

查看详情

为了安全起见，推荐使用API Token而非用户名密码进行上传。登录您的PyPI账户，进入“Account settings”或“API tokens”页面，生成一个新的API Token。请务必妥善保存此Token，因为它只显示一次。

4.3 上传包

使用twine将dist/目录下的所有包上传到PyPI：

twine upload dist/*

当提示输入用户名时，输入__token__（两个下划线，token，两个下划线）。当提示输入密码时，粘贴您之前生成的API Token。

4.4 测试发布（可选但推荐）

在正式发布到PyPI之前，您可以使用TestPyPI进行测试。TestPyPI是一个PyPI的测试环境，可以用来验证您的打包和上传流程是否正确，而不会污染正式的PyPI。

• 访问 test.pypi.org 注册一个账户（与正式PyPI账户独立）。

• 生成TestPyPI的API Token。

• 上传到TestPyPI的命令如下：

  twine upload --repository testpypi dist/*

  登录后复制

  同样，用户名输入__token__，密码输入TestPyPI的API Token。

成功上传后，您的包就可以通过pip install your-package-name来安装了。

5. 注意事项与最佳实践

• 版本管理： 每次发布新版本时，务必更新pyproject.toml中的version字段。推荐使用语义化版本（Semantic Versioning），即MAJOR.MINOR.PATCH。
• README.md： 一个清晰、详细的README.md文件至关重要，它应该包含项目的简介、安装方法、使用示例、API文档链接、贡献指南和许可证信息。
• 许可证（LICENSE）： 为您的开源项目选择一个合适的许可证（如MIT, Apache 2.0, GPL等），并将其放在项目根目录下的LICENSE文件中。在pyproject.toml中也应指定。
• 持续集成/持续部署 (CI/CD)： 考虑使用GitHub Actions、GitLab CI/CD等工具自动化您的测试、打包和发布流程，确保每次代码提交都能自动进行质量检查和发布。
• 安全性： 始终使用API Token上传，避免在命令行或脚本中直接暴露您的PyPI密码。
• 依赖管理： 明确列出所有直接依赖项，并尽量指定合理的版本范围，以避免依赖冲突。

通过遵循上述步骤和最佳实践，您将能够有效地将您的Python项目打包并发布到PyPI，使其更容易被其他开发者发现、安装和使用，从而扩大您的项目影响力。

以上就是如何将Python项目打包并发布到PyPI的详细内容，更多请关注php中文网其它相关文章！