Python的pyproject.toml：概述

分享代码并在开源软件上协作对软件开发起了变革性作用。它使开发人员能够使用现有的软件包和库在较小的团队中构建更复杂的应用程序。

在Python生态系统中，大多数软件包都在Python Package Index (PyPI)上注册。使用索引，开发人员可以将其代码作为软件包与其他开发人员共享。要创建自己的软件包并将其上传到PyPI，您将需要一个pyproject.toml文件。本文是关于它的工作原理的指南。

pyproject.toml是什么？

在介绍这个文件是什么之前，让我们先了解它试图填补的空白。当您将软件包上传到PyPI时，它将变为可通过pip安装。例如，如果您的软件包名为example-package，在上传到PyPI后，它可以通过以下命令进行安装：

pip install example-package

在将软件包发布到Python软件包索引时，您将上传一个.whl文件。但是当您编写代码时，您主要编写的是.py文件，那么如何生成一个.whl文件呢？您可以使用构建工具，如setuptools或poetry。

这个工具将接受您的源代码并将其转换为可以上传的.whl文件。如前所述，您可以使用多种工具来生成whl文件。要指定希望Python使用哪个工具，您需要在pyproject.toml文件中写入它。

因此，pyproject.toml文件是一个指定如何将您的Python项目构建为软件包的文件。除此之外，您还可以提供其他信息，例如您的软件包的元数据，这些信息将显示在PyPI上的软件包列表中。

Python构建过程

要运行构建过程工具，您使用以下命令：

python -m build

但是，在此之前，您需要安装它

python -m pip install build

当您在包含pyproject.toml文件的项目中运行构建命令时，它将创建新的文件和目录。其中包括dist文件夹，其中包含两个文件，一个名为sdist的压缩存档文件和一个.whl文件，然后您在PyPI上分发该文件。

如何生成Python软件包？

为了帮助您巩固刚刚学到的知识，这里有一个生成Python软件包的演示示例。

#1. 创建一个示例项目

首先，创建一个简单的软件包，具有以下文件夹结构

example_package/
├─ example_package/
│  ├─ example_module.py
│  ├─ __init__.py
├─ pyproject.toml
├─ setup.cfg
├─ README.md

项目的根目录称为example_package。这是我们整个代码库的所在位置。在项目根目录中，我们有三个文件和一个目录。它们的内容如下所示：

pyproject.toml

此文件包含有关构建项目时要使用的构建工具的信息。对于这个简单的示例，它们的内容如下：

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

在这种情况下，我们将setuptools.build_meta声明为我们的构建后端。但是setuptools.build_meta包含在setuptools包中，因此首先，我们将其列为需求列表中的一个要求。我们将在本文后面讨论您可以指定的其他选项。

README.md

包含有关您的软件包的信息。这将显示为PyPI上软件包页面上的文档。您可以在该文件中编写任何内容。

setup.cfg

setup.cfg文件包含项目的元数据，例如软件包的名称和当前版本。现在，将以下代码添加为setup.cfg的内容：

[metadata]
name = example-package
version = 1.0.0

example-project

在我们的根目录中，还有一个同名的目录。这个目录是我们源代码所在的地方。为了演示目的，我包含了两个文件：

• example_module.py – 它包含一个虚拟函数。您也可以做同样的事情。
• __init__.py – 它会使目录成为可导入的包。它可以为空。

#2. 运行构建命令

现在，您可以在项目根目录中运行构建命令。

python -m build

如果您还没有安装该工具，请确保使用以下命令安装：

pip install build

您应该得到以下输出：

如您所见，最后一行告诉您它构建了example-package-1.0.0.tar.gz和example-package-1.0.0-py3-none-any-whl。当您使用下面的ls命令列出目录内容时，您应该会看到新的文件。

ls

输出应如下所示：

dist  example_package  example_package.egg-info  pyproject.toml  README.md  setup.cfg

如果您列出dist目录的内容，您应该会找到.whl文件和tar.gz文件。

$ ls dist
example_package-1.0.0-py3-none-any.whl
example-package-1.0.0.tar.gz

pyproject.toml文件的内容

在我们的简单示例中，我们只指定了Python项目的构建系统。然而，您可以在pyproject.toml文件中添加更多信息。以下是一些常见选项。

metadata

您可以在pyproject.toml中编写元数据，而不是在setup.cfg中指定。这些信息将在创建软件包索引上的软件包列表时使用。

此外，您还可以指定您的软件包的依赖关系及其版本，以便在安装您的软件包时可以安装它们。

[project]
name = "hello-world"
version = "1.0.0"
description = "My first Python package"
requires-python = ">=3.8"
keywords = ["python", "first-project"]
authors = [
    {name = "John Doe", email = "[email protected]"},
]
dependencies = [
    "requests",
    "gidgethub[httpx]>4.0.0",
]

tool.

您还可以使用tool.，其中是工具的名称，以为您使用的工具提供不同的配置选项。

只有支持使用此方法进行配置的工具才能这样做。例如，您可以向Black传递配置选项，这是一个代码检查工具。

[tool.black]
line-length = 88
target-version = ["py38", "py39"]

示例文件

将我们所学的东西综合起来，这是一个pyproject.toml文件的示例：

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

[metadata]
name = "my-project"
version = "1.0.0"
description = "一个示例项目"
author = "Your Name"
author_email = "[email protected]"
license = "MIT"
keywords = ["示例", "项目"]

[options]
python_requires = ">=3.6"

[tool.black]
line-length = 88
include = ".pyi?$"
exclude = '''
/(
  .git
  | .hg
  | .mypy_cache
  | .tox
  | .venv
  | _build
  | buck-out
  | build
  | dist
)/
'''

[tool.blackd]
port = 45484
host = "localhost"

更多信息，请阅读此 page。

pyproject.toml的优点

✅ 它为Python项目提供了一种管理依赖项的标准方法。项目的依赖关系和其他相关元数据可以以声明性的方式指定。

✅ 它还提供了一种在项目中指定其他元数据的方法，例如作者、许可证和GitHub URL等其他有用属性。

✅ 它适用于不同的构建系统，切换构建系统很容易。

最后的话

pyproject.toml是一个有用的标准，有助于避免使用setup.py的缺点。它在创建分发包时非常有用。对于大多数新项目，您应该使用pyproject.toml而不是setup.py。

接下来，查看 how to check the Python version in Windows, Linux, and macOS。