PyPI 打包工具 - twine

Twine 是一个用于将 Python 包发布到 PyPI 的实用工具，它通过安全的 HTTPS 连接处理上传，并支持上传任何包格式。下面这个表格汇总了 Twine 的核心使用流程和常见场景，方便你快速了解：

🔧 详细使用步骤#

1. 安装与项目打包#

首先，你需要安装打包和上传所需的工具，并使用 setuptools 对项目进行打包。

• 安装工具：在命令行中执行以下命令来安装 twine、setuptools 和 wheel。

  pip install twine setuptools wheel

• 项目打包：在项目根目录（包含 setup.py 的目录）下，运行以下命令来生成源码包（sdist）和预编译的轮子文件（bdist_wheel），它们会保存在项目下的 dist 目录中。

  python setup.py sdist bdist_wheel

2. 上传与发布包#

打包完成后，就可以使用 twine 将生成的包文件上传到 PyPI 了。

• 基本上传命令：使用 twine upload 命令并指定 dist 目录下的所有文件。

  twine upload dist/*

  执行后，Twine 会提示你输入 PyPI 的用户名和密码。如果使用新式的 API token 进行认证，用户名填写 __token__，密码即为获取到的 token。

• 上传到测试环境：在实际发布到生产环境前，你可以先上传到 PyPI 的测试环境进行验证。使用 -r 参数指定测试仓库。

  twine upload -r testpypi dist/*

3. 配置认证信息#

为了避免每次上传都手动输入用户名和密码，你可以通过配置文件或环境变量来设置认证信息。

• 配置文件法（推荐）：在用户主目录下创建或编辑 .pypirc 文件。在该文件中配置你的 PyPI 账号信息或 token。

  [pypi]
  username = your_username
  password = your_password_or_token

  如果使用 token，username 应填写 __token__，password 填写 token 内容。

• 环境变量法：你也可以通过设置 TWINE_USERNAME 和 TWINE_PASSWORD 环境变量来传递认证信息。

🚀 进阶使用与常见问题#

1. 自动化上传#

你可以将打包和上传命令整合到项目的 setup.py 中，创建一个自定义命令来实现一键发布。这通常通过定义一个继承自 setuptools.Command 的类，并在 setup() 函数的 cmdclass 参数中注册来实现。之后，只需运行 python setup.py upload 即可完成打包和上传。

2. 处理代理环境#

如果你在公司代理后面，上传时可能会遇到连接问题。此时，可以设置 HTTPS_PROXY 环境变量来指定代理服务器。

set HTTPS_PROXY=proxy.company.com:8080

如果代理使用自定义的 CA 证书，可能还需要通过 TWINE_CERT 环境变量指定证书路径，并且确保证书为 PEM 格式。

3. 版本管理与冲突#

PyPI 不允许重复上传相同版本号的包。每次上传新版本时，请务必在 setup.py 中更新项目的版本号。

💎 核心优势#

• 安全上传：Twine 始终通过 HTTPS 上传，保障了传输安全。
• 支持多种格式：它可以上传任何使用 setuptools 生成的包格式，如源码包 sdist 和预编译轮子 bdist_wheel。
• 灵活认证：支持用户名密码和个人访问令牌（API Token），并可通过配置文件或环境变量管理，方便集成到自动化流程中。

希望这份指南能帮助你顺利发布 Python 包。如果你在特定步骤上遇到更具体的问题，比如 setup.py 的详细配置，我很乐意提供进一步的帮助。