6. Python 包索引 (PyPI)

Python 包索引 (PyPI) 存储元数据描述用 distutils 打包的发行版，如果包作者愿意，也可以存储像发行版文件这样的包数据。

Distutils 提供了 register 和 upload 命令，分别用于将元数据和分发文件推送到 PyPI。有关这些命令的信息，请参阅 Distutils 命令。

6.1. PyPI 概述

PyPI 允许您向索引提交任意数量的发行版版本。如果您更改特定版本的元数据，您可以再次提交它，索引将被更新。

PyPI 为提交的每个（名称、版本）组合保存一条记录。为给定名称提交信息的第一个用户被指定为该名称的所有者。可以通过 register 命令或通过 Web 界面提交更改。所有者可以将其他用户指定为所有者或维护者。维护者可以编辑包信息，但不能指定新的所有者或维护者。

默认情况下，PyPI 仅显示给定包的最新版本。 Web 界面允许更改此默认行为并手动选择要显示和隐藏的版本。

对于每个版本，PyPI 都会显示一个主页。主页是从 long_description 创建的，可以通过 register 命令提交。有关更多信息，请参阅 PyPI 包显示。

6.2. Distutils 命令

Distutils 公开了两个用于向 PyPI 提交包数据的命令：用于向 PyPI 提交元数据的 register 命令和用于提交分发文件的 upload 命令。这两个命令都从一个名为 .pypirc 文件的特殊文件中读取配置数据。

6.2.1. 这register命令

distutils 命令 register 用于将您的发行版的元数据提交到索引服务器。它的调用方式如下：

python setup.py register

Distutils 将响应以下提示：

running register
We need to know who you are, so please choose either:
    1. use your existing login,
    2. register as a new user,
    3. have the server generate a new password for you (and email it to you), or
    4. quit
Your selection [default 1]:

注意：如果您的用户名和密码保存在本地，您将看不到此菜单。另外，请参阅 .pypirc 文件，了解如何将您的凭据存储在 .pypirc 文件中。

如果您尚未注册 PyPI，那么您现在需要注册。您应该选择选项 2，并根据需要输入您的详细信息。提交您的详细信息后不久，您将收到一封电子邮件，用于确认您的注册。

注册后，您可以从菜单中选择选项 1。系统将提示您输入 PyPI 用户名和密码，然后 register 将您的元数据提交到索引。

有关 register 命令的选项，请参阅附加命令选项。

6.2.2. 这upload命令

distutils 命令 upload 将分发文件推送到 PyPI。

在构建一个或多个分发文件后立即调用该命令。例如，命令

python setup.py sdist bdist_wininst upload

将导致源分发和 Windows 安装程序上传到 PyPI。请注意，即使它们是使用 setup.py 的早期调用构建的，也会上传这些文件，但只有在命令行上命名的用于调用的发行版（包括 upload 命令）会被上传。

如果之前在同一命令中调用了 register 命令，并且在提示中输入了密码，则 upload 将重复使用输入的密码。如果您不想在 .pypirc 文件中以明文形式存储密码，这将非常有用。

您可以使用 --sign 选项告诉 upload 使用 GPG（GNU Privacy Guard）对每个上传的文件进行签名。 gpg 程序必须可在系统 PATH 上执行。您还可以使用 --identity=name 选项指定用于签名的密钥。

有关 upload 命令的附加选项，请参阅附加命令选项。

6.2.3. 附加命令选项

本节介绍 register 和 upload 命令的通用选项。

--repository 或 -r 选项允许您指定不同于默认值的 PyPI 服务器。例如：

python setup.py sdist bdist_wininst upload -r https://example.com/pypi

为方便起见，当 .pypirc 文件配置为这样做时，可以使用名称代替 URL。例如：

python setup.py register -r other

有关定义备用服务器的更多信息，请参阅 .pypirc 文件。

--show-response 选项显示来自 PyPI 服务器的完整响应文本，这在调试注册和上传问题时很有用。

6.2.4. 这.pypirc文件

register 和 upload 命令都检查 $HOME/.pypirc 位置是否存在 .pypirc 文件。如果此文件存在，该命令将使用文件中配置的用户名、密码和存储库 URL。 .pypirc文件的格式如下：

[distutils]
index-servers =
    pypi

[pypi]
repository: <repository-url>
username: <username>
password: <password>

distutils 部分定义了一个 index-servers 变量，该变量列出了描述存储库的所有部分的名称。

描述存储库的每个部分都定义了三个变量：

*; repository，定义了 PyPI 服务器的 url。默认为
https://upload.pypi.org/legacy/。
username，是PyPI服务器上注册的用户名。
*; password，用于认证。如果省略用户
需要时会提示输入。

如果您想定义另一个服务器，可以创建一个新部分并在 index-servers 变量中列出：

[distutils]
index-servers =
    pypi
    other

[pypi]
repository: <repository-url>
username: <username>
password: <password>

[other]
repository: https://example.com/pypi
username: <username>
password: <password>

这允许使用 --repository 选项调用 register 和 upload 命令，如附加命令选项中所述。

具体来说，您可能希望将 PyPI 测试存储库添加到 .pypirc 中，以便在首次上传到 PyPI 之前进行测试。

6.3. PyPI 包展示

long_description 字段在 PyPI 中扮演着特殊的角色。服务器使用它来显示已注册包的主页。

如果您对此字段使用 reStructuredText 语法，PyPI 将解析它并显示包主页的 HTML 输出。

long_description 字段可以附加到位于包中的文本文件：

from distutils.core import setup

with open('README.txt') as file:
    long_description = file.read()

setup(name='Distutils',
      long_description=long_description)

在这种情况下，README.txt 是位于包根目录中的常规 reStructuredText 文本文件，除了 setup.py。

为了防止注册损坏的 reStructuredText 内容，您可以使用 docutils 包提供的 rst2html 程序并从命令行检查 long_description：

$ python setup.py --long-description | rst2html.py > output.html

如果您的语法有问题，docutils 将显示警告。因为 PyPI 应用了额外的检查（例如通过在上面的命令中将 --no-raw 传递给 rst2html.py），能够在没有警告的情况下运行上面的命令并不能保证 PyPI 将成功转换内容。

6. Python 包索引 (PyPI) — Python 文档