打包和分发项目¶

Packaging and distributing projects

页面状态:: 过时(Outdated)
最后更新:: 2023-12-14

中文

本节介绍了使用 setuptools 配置、打包和分发 Python 项目的一些额外细节，这些内容没有包含在打包Python项目的入门教程中。它假定您已经熟悉安装软件包页面中的内容。

本节的目标不是涵盖 Python 项目开发的最佳实践。例如，它不提供关于版本控制、文档编写或测试的指导或工具推荐。

有关更多参考资料，请参见构建和分发包中的 Setuptools 文档，但请注意，其中的一些建议内容可能已经过时。如有冲突，请优先参考 Python 打包用户指南中的建议。

英文

This section covers some additional details on configuring, packaging and distributing Python projects with setuptools that aren't covered by the introductory tutorial in 打包Python项目. It still assumes that you are already familiar with the contents of the 安装软件包 page.

The section does not aim to cover best practices for Python project development as a whole. For example, it does not provide guidance or tool recommendations for version control, documentation, or testing.

For more reference material, see Building and Distributing Packages in the Setuptools docs, but note that some advisory content there may be outdated. In the event of conflicts, prefer the advice in the Python Packaging User Guide.

打包和分发的要求¶

Requirements for packaging and distributing

中文

首先，确保您已经满足了安装包的要求。
安装 "twine" [1]:
Unix/macOS
python3 -m pip install twine
Windows
py -m pip install twine
您需要安装这个工具来将您的项目分发包上传到 PyPI （参见下面的内容）。

英文

First, make sure you have already fulfilled the requirements for installing packages.
Install "twine" [1]:
Unix/macOS
python3 -m pip install twine
Windows
py -m pip install twine
You'll need this to upload your project distributions to PyPI (see below).

在“开发模式”下工作¶

Working in "development mode"

中文

你可以在开发过程中以“可编辑”或“开发”模式安装项目。当项目以可编辑模式安装时，你可以在不重新安装的情况下直接编辑项目：对安装为可编辑模式的项目中的 Python 源文件的修改将在下次启动解释器时立即反映出来。

要以“可编辑”/“开发”模式安装 Python 包，首先进入项目根目录并运行：

python3 -m pip install -e .

pip 命令行标志 -e 是 --editable 的简写，而 . 指当前工作目录，因此合起来表示将当前目录（即你的项目）安装为可编辑模式。这也会安装所有在 install_requires 中声明的依赖项以及在 console_scripts 中声明的任何脚本。依赖项将以通常的非可编辑模式安装。

你可能还想以可编辑模式安装某些依赖项。例如，假设你的项目需要“foo”和“bar”，但是你希望从 VCS 中以可编辑模式安装“bar”，那么你可以构建如下的 requirements 文件:

-e .
-e bar @ git+https://somerepo/bar.git

第一行表示安装你的项目及其所有依赖项。第二行覆盖了“bar”依赖项，使其从 VCS 安装，而不是从 PyPI 安装。

然而，如果你想从本地目录以可编辑模式安装“bar”，则 requirements 文件应该如下所示，并将本地路径放在文件的顶部:

-e /path/to/project/bar
-e .

否则，由于 requirements 文件的安装顺序，依赖项将从 PyPI 安装。有关 requirements 文件的更多信息，请参阅 pip 文档中的 Requirements File 部分。有关 VCS 安装的更多信息，请参阅 pip 文档中的 VCS Support 部分。

最后，如果你不想安装任何依赖项，可以运行：

python3 -m pip install -e . --no-deps

有关更多信息，请参见 Development Mode 部分，在 Setuptools 文档中。

英文

You can install a project in "editable" or "develop" mode while you're working on it. When installed as editable, a project can be edited in-place without reinstallation: changes to Python source files in projects installed as editable will be reflected the next time an interpreter process is started.

To install a Python package in "editable"/"development" mode Change directory to the root of the project directory and run:

python3 -m pip install -e .

The pip command-line flag -e is short for --editable, and . refers to the current working directory, so together, it means to install the current directory (i.e. your project) in editable mode. This will also install any dependencies declared with install_requires and any scripts declared with console_scripts. Dependencies will be installed in the usual, non-editable mode.

You may want to install some of your dependencies in editable mode as well. For example, supposing your project requires "foo" and "bar", but you want "bar" installed from VCS in editable mode, then you could construct a requirements file like so:

-e .
-e bar @ git+https://somerepo/bar.git

The first line says to install your project and any dependencies. The second line overrides the "bar" dependency, such that it's fulfilled from VCS, not PyPI.

If, however, you want "bar" installed from a local directory in editable mode, the requirements file should look like this, with the local paths at the top of the file:

-e /path/to/project/bar
-e .

Otherwise, the dependency will be fulfilled from PyPI, due to the installation order of the requirements file. For more on requirements files, see the Requirements File section in the pip docs. For more on VCS installs, see the VCS Support section of the pip docs.

Lastly, if you don't want to install any dependencies at all, you can run:

python3 -m pip install -e . --no-deps

For more information, see the Development Mode section of the Setuptools docs.

将您的项目上传到 PyPI¶

Uploading your Project to PyPI

中文

当你运行命令创建分发包时，一个新的目录 dist/ 会在你的项目根目录下创建。你可以在这个目录中找到你的分发文件，以便上传。

备注

这些文件只有在你运行创建分发包的命令时才会生成。这意味着，每次你更改项目源代码或更新 setup.py 文件中的配置时，都需要重新生成这些文件，才能将更改分发到 PyPI。

备注

在将包发布到主 PyPI 仓库之前，你可以先在 PyPI 测试站点上进行测试，该站点会定期清理。请参见使用 TestPyPI 了解如何配置以使用该站点。

警告

在其他资源中，你可能会看到使用 python setup.py register 和 python setup.py upload 的方法。这些注册和上传包的方式 强烈不推荐，因为在某些 Python 版本中，这些方法可能会使用明文 HTTP 或未验证的 HTTPS 连接，从而在传输过程中让你的用户名和密码受到拦截。

小技巧

PyPI 使用的 reStructuredText 解析器不是 Sphinx！此外，为了确保用户安全，某些类型的 URL 和指令被禁止或会被删除（例如 .. raw:: 指令）。在尝试上传你的分发包之前，你应该检查在 setup.py 中提供的简短描述和长描述是否有效。你可以通过运行以下命令检查包文件：

twine check dist/*

英文

When you ran the command to create your distribution, a new directory dist/ was created under your project's root directory. That's where you'll find your distribution file(s) to upload.

备注

These files are only created when you run the command to create your distribution. This means that any time you change the source of your project or the configuration in your setup.py file, you will need to rebuild these files again before you can distribute the changes to PyPI.

备注

Before releasing on main PyPI repo, you might prefer training with the PyPI test site which is cleaned on a semi regular basis. See 使用 TestPyPI on how to setup your configuration in order to use it.

警告

In other resources you may encounter references to using python setup.py register and python setup.py upload. These methods of registering and uploading a package are strongly discouraged as it may use a plaintext HTTP or unverified HTTPS connection on some Python versions, allowing your username and password to be intercepted during transmission.

小技巧

The reStructuredText parser used on PyPI is not Sphinx! Furthermore, to ensure safety of all users, certain kinds of URLs and directives are forbidden or stripped out (e.g., the .. raw:: directive). Before trying to upload your distribution, you should check to see if your brief / long descriptions provided in setup.py are valid. You can do this by running twine check on your package files:

twine check dist/*

创建帐户¶

Create an account

中文

首先，你需要一个 PyPI 用户账户。你可以通过 PyPI 网站上的注册表单创建一个账户。

接下来，你需要创建一个 PyPI API 令牌以便能够安全地上传你的项目。

访问 https://pypi.org/manage/account/#api-tokens 并创建一个新的 API 令牌；不要将其范围限制为某个特定项目，因为你正在创建一个新的项目。

在复制和保存令牌之前不要关闭页面——令牌仅显示一次，无法再次查看。

注意

为避免每次上传时都需要复制和粘贴令牌，你可以创建一个 $HOME/.pypirc 文件：

[pypi]
username = __token__
password = <令牌值，包括 `pypi-` 前缀>

请注意，这会将你的令牌以明文方式存储。

有关更多详细信息，请参阅 .pypirc 的规范。

英文

First, you need a PyPI user account. You can create an account using the form on the PyPI website.

Now you'll create a PyPI API token so you will be able to securely upload your project.

Go to https://pypi.org/manage/account/#api-tokens and create a new API token; don't limit its scope to a particular project, since you are creating a new project.

Don't close the page until you have copied and saved the token — you won't see that token again.

备注

To avoid having to copy and paste the token every time you upload, you can create a $HOME/.pypirc file:

[pypi]
username = __token__
password = <the token value, including the `pypi-` prefix>

Be aware that this stores your token in plaintext.

For more details, see the specification for .pypirc.

上传您的分发¶

Upload your distributions

中文

一旦你拥有了一个账户，你可以使用 twine 将你的分发包上传到 PyPI。

上传发布的过程对于是否已经在 PyPI 上存在该项目是相同的——如果项目尚不存在，它将在第一次上传发布时自动创建。

对于第二次及之后的发布，PyPI 只要求新发布的版本号与任何先前的版本不同。

twine upload dist/*

你可以通过访问网址 https://pypi.org/project/<sampleproject> 来查看你的包是否已成功上传，其中 sampleproject 是你上传的项目名称。可能需要一两分钟，项目才会出现在网站上。

英文

Once you have an account you can upload your distributions to PyPI using twine.

The process for uploading a release is the same regardless of whether or not the project already exists on PyPI - if it doesn't exist yet, it will be automatically created when the first release is uploaded.

For the second and subsequent releases, PyPI only requires that the version number of the new release differ from any previous releases.

twine upload dist/*

You can see if your package has successfully uploaded by navigating to the URL https://pypi.org/project/<sampleproject> where sampleproject is the name of your project that you uploaded. It may take a minute or two for your project to appear on the site.

打包和分发项目¶

打包和分发的要求¶

配置您的项目¶

初始文件¶

setup.py¶

setup.cfg¶

README.rst / README.md¶

MANIFEST.in¶

LICENSE.txt¶

<您的包>¶

setup() 参数¶

`packages`¶

`py_modules`¶

`install_requires`¶

`package_data`¶

`data_files`¶

`scripts`¶

选择版本控制方案¶

在“开发模式”下工作¶

打包您的项目¶

源代码分发¶

Wheels¶

纯 Python Wheels¶

平台 Wheels¶

将您的项目上传到 PyPI¶

创建帐户¶

上传您的分发¶

打包和分发项目¶

打包和分发的要求¶

配置您的项目¶

初始文件¶

setup.py¶

setup.cfg¶

README.rst / README.md¶

MANIFEST.in¶

LICENSE.txt¶

<您的包>¶

setup() 参数¶

packages¶

py_modules¶

install_requires¶

package_data¶

data_files¶

scripts¶

选择版本控制方案¶

在“开发模式”下工作¶

打包您的项目¶

源代码分发¶

Wheels¶

纯 Python Wheels¶

平台 Wheels¶

将您的项目上传到 PyPI¶

创建帐户¶

上传您的分发¶

`packages`¶

`py_modules`¶

`install_requires`¶

`package_data`¶

`data_files`¶

`scripts`¶