掌握 PyPI：让你的 Python 项目触手可及 – wiki基地

作者： /

掌握 PyPI：让你的 Python 项目触手可及

你是否曾花费心血构建了一个出色的 Python 库、一个便捷的命令行工具，或者一个解决了特定问题的实用模块？你希望与世界分享你的成果，让其他开发者能够通过一句简单的 pip install your-package 就轻松使用它吗？

如果答案是肯定的，那么 PyPI (Python Package Index) 就是你必须掌握的平台。本文将作为一份详尽的指南，带你从零开始，一步步将你的 Python 项目打包并发布到 PyPI，真正实现“让你的项目触手可及”。

第一步：理解 PyPI 和现代 Python 打包

PyPI 是 Python 社区官方的、也是最大的软件包仓库。全世界的 Python 开发者都将他们的开源项目发布到这里。当你执行 pip install 时，pip 默认就是从 PyPI 查找并下载你需要的包。

随着 Python 的发展，项目打包的方式也在演进。过去，setup.py 和 setuptools 是主流。而现在，社区转向了更现代化、更声明式的标准：pyproject.toml。这种方式将项目元数据和构建配置分离，使得整个过程更加清晰和标准化。

本指南将完全基于现代的 pyproject.toml 标准。

第二步：准备你的项目

在发布之前，一个结构清晰的项目至关重要。一个标准的 Python 项目结构如下：

your-project/
├── src/
│ └── your_package_name/
│ ├── __init__.py
│ └── main.py
├── tests/
│ └── test_main.py
├── .gitignore
├── LICENSE
├── README.md
└── pyproject.toml

关键文件说明：

  1. src/your_package_name/：这是你项目源代码的核心目录。将代码放在 src 目录下是一种推荐的最佳实践，它可以避免很多潜在的导入问题。
  2. tests/：存放你的单元测试和集成测试。
  3. LICENSE：开源项目的灵魂。你必须为你的项目选择一个许可证，例如 MIT, Apache 2.0 等。这决定了其他人如何使用你的代码。choosealicense.com 可以帮助你选择。
  4. README.md：项目的门面。用清晰的语言描述你的项目是做什么的、如何安装、如何使用，并提供一个简单的示例。一个高质量的 README 是吸引用户的关键。
  5. pyproject.toml：项目的配置文件，也是我们接下来要关注的重点。

pyproject.toml：项目的灵魂

pyproject.toml 文件定义了项目的一切。它告诉 Python 的构建工具（如 build 和 pip）如何处理你的项目。

一个最小但完整的 pyproject.toml 示例如下：

“`toml

pyproject.toml

[build-system]
requires = [“hatchling”]
build-backend = “hatchling.build”

[project]
name = “your-unique-package-name” # 替换成你独一无二的包名
version = “0.1.0”
authors = [
{ name=”Your Name”, email=”[email protected]” },
]
description = “A small example package”
readme = “README.md”
requires-python = “>=3.8”
classifiers = [
“Programming Language :: Python :: 3”,
“License :: OSI Approved :: MIT License”,
“Operating System :: OS Independent”,
]

[project.urls]
Homepage = “https://github.com/your-username/your-project”
Issues = “https://github.com/your-username/your-project/issues”
“`

配置解析：

  • [build-system]：
    • requires: 指定构建项目所需的包。hatchling 是一个现代、快速的构建后端，你也可以使用 setuptools。
    • build-backend: 指定了实际执行构建过程的 Python 对象。
  • [project]：
    • name: 极其重要。这是用户通过 pip install 使用的名字，它在整个 PyPI 上必须是唯一的。
    • version: 项目的版本号。我们推荐遵循语义化版本（Semantic Versioning），即 主版本号.次版本号.修订号 (e.g., 1.2.3)。每次更新包时，你都需要增加版本号。
    • authors: 你的名字和邮箱。
    • description: 一段简短的项目描述。
    • readme: 指向你的 README.md 文件。PyPI 会将这个文件的内容展示在你的项目页面上。
    • requires-python: 你的项目支持的最低 Python 版本。
    • classifiers: 分类器。帮助用户更好地了解你的项目。你可以在 pypi.org/classifiers/ 找到完整的列表。
  • [project.urls]：提供一些有用的链接，比如项目主页、文档、Bug 追踪等。

第三步：构建你的包

配置好 pyproject.toml 后，我们就可以正式构建用于分发的软件包了。

  1. 安装构建工具
    你需要两个关键的工具：build 用于构建包，twine 用于上传包。

    bash
    pip install --upgrade build twine

  2. 执行构建命令
    在你的项目根目录（即 pyproject.toml 所在的目录）下，运行以下命令：

    bash
    python -m build

    执行完毕后，你会发现项目根目录下多了一个 dist/ 文件夹。里面通常有两个文件：
    * your_unique_package_name-0.1.0-py3-none-any.whl: 这是一个Wheel文件，它是现代 Python 包的二进制分发格式，安装速度快。
    * your_unique_package_name-0.1.0.tar.gz: 这是一个源码归档文件，是传统的源码分发格式。

    这两个文件就是我们要上传到 PyPI 的最终产物。

第四步：发布到 PyPI

在将你的心血之作公之于众前，强烈建议先在一个测试环境中演练一遍。

  1. 创建 PyPI 和 TestPyPI 账户

    • TestPyPI: test.pypi.org 是 PyPI 的一个独立测试实例。你可以在这里随意上传和测试，不会污染主仓库。请先在这里注册一个账户。
    • PyPI: pypi.org 是正式的仓库。在这里也注册一个账户（注意：账户与 TestPyPI 不通用）。

  2. 安全最佳实践：使用 API 令牌
    为了安全，不要直接使用用户名和密码上传。你应该为你的项目创建一个 API 令牌。

    • 登录 TestPyPI，进入 “Account settings”。
    • 拉到最下方，找到 “API tokens”，点击 “Add API token”。
    • 给令牌起个名字，范围（Scope） 选择 “Entire account” 或者限定在特定项目。
    • 点击创建后，立即复制生成的令牌。这个令牌只会显示一次，关掉页面后就找不回来了。它看起来像 pypi-AgEIcH...。

  3. 上传到 TestPyPI
    使用 twine 将 dist/ 目录下的文件上传到 TestPyPI。

    bash
    twine upload --repository testpypi dist/*

    twine 会提示你输入用户名和密码：
    * 用户名: 输入 __token__ （没错，就是这个固定的字符串）。
    * 密码: 粘贴你刚才复制的 API 令牌。

    上传成功后，你就可以访问 https://test.pypi.org/project/your-unique-package-name/ 查看你的项目页面了。你甚至可以尝试从 TestPyPI 安装它：

    bash
    pip install --index-url https://test.pypi.org/simple/ your-unique-package-name

  4. 正式发布到 PyPI
    当你在 TestPyPI 上的所有操作都确认无误后，就可以进行最终的发布了。

    • 首先，在正式的 PyPI 网站上用同样的方式创建一个 API 令牌。
    • 然后，运行上传命令，但这次去掉 --repository testpypi 选项：

    bash
    twine upload dist/*

    同样，用户名为 __token__，密码为你在 pypi.org 上生成的 API 令牌。

    恭喜！ 你的项目现在已经全球可访问了！任何人都可以通过以下命令安装你的杰作：

    bash
    pip install your-unique-package-name

第五步：自动化发布（进阶）

每次更新代码、修改版本号、手动构建和上传，这个过程很繁琐且容易出错。真正的“掌握”，意味着实现自动化。GitHub Actions 是实现这一目标的绝佳工具。

你可以在你的项目仓库中创建一个 .github/workflows/publish.yml 文件，内容如下：

“`yaml

.github/workflows/publish.yml

name: Publish Python Package to PyPI

on:
release:
types: [created]

jobs:
build-and-publish:
name: Build and publish Python distributions to PyPI
runs-on: ubuntu-latest
steps:
– name: Checkout repository
uses: actions/checkout@v3

  - name: Set up Python
    uses: actions/setup-python@v3
    with:
      python-version: "3.x"

  - name: Install dependencies
    run: |
      python -m pip install --upgrade pip
      pip install build

  - name: Build package
    run: python -m build

  - name: Publish package to PyPI
    uses: pypa/gh-action-pypi-publish@release/v1
    with:
      password: ${{ secrets.PYPI_API_TOKEN }}

“`

工作流程解释：

  1. on: release: types: [created]：这个工作流会在你每次在 GitHub 上创建新的 Release 时触发。
  2. secrets.PYPI_API_TOKEN：为了安全，你需要将你的 PyPI API 令牌存储在 GitHub 仓库的 “Settings” -> “Secrets and variables” -> “Actions” -> “Repository secrets” 中。创建一个名为 PYPI_API_TOKEN 的新 Secret，值为你的 PyPI 令牌。
  3. 工作流步骤：
    • 检出代码。
    • 安装 Python 和构建工具。
    • 运行 python -m build。
    • 使用官方的 pypa/gh-action-pypi-publish 动作，将 dist/ 目录下的文件发布到 PyPI，它会自动使用你存储的 Secret 进行身份验证。

现在，你的发布流程变成了：
1. 完成代码开发。
2. 在 pyproject.toml 中提升版本号。
3. 提交代码，并在 GitHub 上创建一个新的 Release (例如，v0.1.1)。

GitHub Actions 会自动接管剩下的所有工作。这才是专业、高效且可靠的发布方式。

总结

将一个 Python 项目发布到 PyPI 是从“为自己写代码”到“为社区贡献”的关键一步。虽然初看起来步骤繁多，但遵循现代化的 pyproject.toml 标准，整个过程变得前所未有地清晰和简单。

核心回顾：
1. 准备：清晰的项目结构，完善的 README.md 和 LICENSE。
2. 配置：精心编写 pyproject.toml，定义好项目元数据。
3. 构建：使用 python -m build 生成分发文件。
4. 测试：先用 TestPyPI 和 API 令牌进行演练。
5. 发布：使用 twine upload 上传到 PyPI。
6. 自动化：通过 GitHub Actions 实现优雅、自动化的持续发布。

现在，开始动手将你的项目分享给世界吧！

滚动至顶部