pyproject.toml 文件是做啥用的？

Posted 2023-02-27

【中文标题】pyproject.toml 文件是做啥用的？

【英文标题】：What is pyproject.toml file for?pyproject.toml 文件是做什么用的？

【发布时间】：2020-11-09 00:26:03

【问题描述】：

背景

我正准备尝试从GitHub下载的Python包，发现它没有setup.py，所以我无法安装它

pip install -e <folder>

相反，该包有一个 pyproject.toml 文件，该文件似乎与 setup.py 通常具有非常相似的条目。

我发现了什么

谷歌搜索带我进入PEP-518，它在Rationale 部分对setup.py 提出了一些批评。但是，它并没有明确说明应该避免使用setup.py，或者pyproject.toml 将完全取代setup.py。

问题

pyproject.toml 是用来代替setup.py 的吗？还是应该同时提供一个包，pyproject.toml 和 setup.py？ 如何在可编辑状态下安装带有pyproject.toml 的项目？

【问题讨论】：

见PEP-518。

谢谢，@KlausD，这在 Google 搜索结果中名列前茅，但 PEP-518 并未就开发人员是否应避免使用 setup.py 以及如何以可编辑状态安装软件包（如果 @ 987654338@未使用等

【参考方案1】：

只回答这一部分，其他人已经很好地解释了：

如何在可编辑状态下安装 pyproject.toml 的项目？

解决方法（工作）

克隆项目并运行poetry install首先创建它的正常安装。

获取诗歌使用poetry env info -p 创建的virtualenv 的路径。它可能类似于<absolute path of your cloned project/.venv。然后检查其中site-packages 目录的路径是什么。这取决于您的 Python 版本，类似于<absolute path of your cloned project/.venv/lib/python3.9/site-packages。

在这个site-packages 中创建一个.pth file。它应该包含一行文本，其中包含要在可编辑模式下安装的包的完整路径：

echo "<absolute path of your cloned project>" > "<absolute path of your cloned project/.venv/lib/python3.9/site-packages/package_name.pth"

正确修复（自 2021 年 8 月起未实施）

2021 年 6 月，描述基于 pyproject.toml 的构建的可编辑安装的 PEP-660 已被接受。

poetry 的实现正在this PR 中进行。

所以我们需要等待它完成，合并并发布一个新的poetry 版本。

来源

除了上面链接的，我的主要来源是"pip install -e . equivalent?" - issue #34 in github.com/python-poetry/poetry。

【讨论】：

2022 年更新：PEP 660 在pip（来自 21.3.0）和一些后端实现，例如flit。但是setuptools 没有任何进展。

【参考方案2】：

目前 Python 社区中有多种打包工具很流行，虽然 setuptools 似乎仍然很流行，但它不再是事实上的标准。这种情况给最终用户和开发者带来了许多麻烦：

对于基于setuptools 的软件包，如果没有安装setuptools，则从源代码安装/构建分发版可能会失败； 无法使用pip 从源安装基于其他打包工具的包。必须先安装打包工具，然后使用工具特定的命令来安装/构建分发包； 如果包作者决定更改打包工具，则还必须更改工作流以使用不同的工具特定命令。

pyproject.toml是PEP 517和PEP 518为解决这些问题而引入的新配置文件：

...想想为项目生成构建工件所需的（粗略）步骤：

项目的源代码签出。 构建系统的安装。 执行构建系统。

此 PEP [518] 涵盖步骤 #2。 PEP 517 涵盖第 3 步 ...

任何工具也可以使用自己的部分（表）扩展此文件以接受特定于工具的选项，但这取决于他们而不是必需的。

---

对于基于setuptools 的包，pyproject.toml 并不是严格意义上的替换setup.py，而是在仍然需要时确保其正确执行。对于其他打包工具——是的，它是：

如果存在build-backend 键，则优先，源代码树遵循指定后端的格式和约定（因此不需要setup.py除非后端需要）。项目可能仍希望包含 setup.py 以与不使用此规范的工具兼容。

---

“可编辑安装”是setuptools 特有的功能，因此PEP 517 不支持：

Install Options:
  -e, --editable <path/url>   Install a project in editable mode (i.e. setuptools "develop mode")

要以可编辑模式安装基于setuptools 的软件包，它需要有一个至少包含最少内容的setup.py 文件：

from setuptools import setup

setup()

【参考方案3】：

是的，pyproject.toml 是PEP 518 的指定文件格式，其中包含 Python 项目的构建系统要求。

这解决了构建工具依赖鸡和蛋的问题，即pip 可以读取pyproject.toml 以及可能需要什么版本的setuptools 或wheel。

如果您需要 setup.py 进行可编辑安装，您可以在 setup.py 中使用 shim：

#!/usr/bin/env python

import setuptools

if __name__ == "__main__":
    setuptools.setup()

【讨论】：

感谢您的垫片！所以看起来pyproject.toml几乎是setup.py的替代品，开发人员应该both使用，以便可以在可编辑状态下安装项目？奇怪的是，我多年来一直在各种小型项目中使用setup.py，并且从未需要消除“鸡和蛋的问题”。

如果您不使用 setuptools，这也很有用，例如 flit 或 poetry

我很困惑... pip 与构建有什么关系？ pip 不只是为了安装依赖吗？

@Shannon 要构建一个项目，您可能需要至少安装一些抽象依赖项来执行构建系统。 pip 可以充当安装程序后端，而pip wheel target-dir pip 充当构建前端，pip install lxml==2.4.0 作为集成前端，请参阅PEP517

一个常见的先有鸡还是先有蛋的问题是使用 pybind11 构建扩展。 setup.py 需要将 pybind11.get_include() 添加到编译器标志，但除非安装了 pybind11，否则不能这样做。如果这被指定为setup.py 中的依赖项...

【参考方案4】：

pyproject.toml 是新的unified Python project settings file，即replaces setup.py。 Editable installs 还需要一个setup.py：import setuptools; setuptools.setup()

要使用pyproject.toml，请运行python -m pip install .

然后，如果项目使用poetry 而不是pip，您可以像这样安装依赖项（到%USERPROFILE%\AppData\Local\pypoetry\Cache\virtualenvs）：

poetry install

然后运行 ​​pytest 之类的依赖项：

poetry run pytest tests/

还有pre-commit（使用.pre-commit-config.yaml）：

poetry run pre-commit install
poetry run pre-commit run --all-files

【讨论】：

setup.py 不可编辑在什么意义上？

@Dave 可编辑安装 是一种安装，其中安装的文件是指向源目录的符号链接。这对开发人员特别有用，因此他们无需在每次更改代码行时都重新安装包。