使用 Python Poetry 进行依赖管理

Python Poetry入门

安装 Poetry 后，是时候看看 Poetry 是如何工作的了。在本节中，您将学习如何开始一个新的 Poetry 项目以及如何将 Poetry 添加到现有项目中。您还将看到项目结构并检查pyproject.toml文件。

$ poetry new rp-poetry
$ cd rp-poetry

rp-poetry/
│
├── rp_poetry/
│   └── __init__.py
│
├── tests/
│   ├── __init__.py
│   └── test_rp_poetry.py
│
├── README.rst
└── pyproject.toml

$ poetry new rp-poetry --name realpoetry

$ poetry new --src rp-poetry
$ cd rp-poetry

rp-poetry/
│
├── src/
│   │
│   └── rp_poetry/
│       └── __init__.py
│
├── tests/
│   ├── __init__.py
│   └── test_rp_poetry.py
│
├── README.rst
└── pyproject.toml

检查项目结构

该rp_poetry/子文件夹本身是不是很壮观呢。在这个目录中，你会找到一个__init__.py包含你的包版本的文件：

# rp_poetry/__init__.py

__version__ = "0.1.0"

当您跳到tests/文件夹并打开 时test_rp_poetry.py，您会注意到它rp_poetry已经是可导入的：

# tests/test_rp_poetry.py

from rp_poetry import __version__

def test_version():
    assert __version__ == "0.1.0"

Poetry 还为该项目添加了第一个测试。该test_version()函数检查 的__version__变量是否rp_poetry/__init__.py包含预期的版本。但是，该__init__.py文件并不是您定义包版本的唯一位置。另一个位置是pyproject.toml文件。

使用pyproject.toml文件

使用 Poetry 最重要的文件之一是pyproject.toml文件。这个文件不是 Poetry 的发明。这是 PEP 518 中定义的配置文件标准：

此 PEP 指定 Python 软件包应如何指定它们具有的构建依赖项以执行其选择的构建系统。作为本规范的一部分，为软件包引入了一个新的配置文件，用于指定它们的构建依赖项（期望相同的配置文件将用于未来的配置细节）。（来源）

作者考虑了上面引用中提到的“新配置文件”的几种文件格式。最后，他们决定采用TOML格式，即Tom's Obvious Minimal Language 的缩写。在他们看来，TOML 足够灵活，比其他选项（YAML、JSON、CFG 或 INI）具有更好的可读性和更少的复杂性。要查看 TOML 的外观，请打开pyproject.toml文件：

 1# pyproject.toml
 2
 3[tool.poetry]
 4name = "rp-poetry"
 5version = "0.1.0"
 6description = ""
 7authors = ["Philipp <philipp@realpython.com>"]
 8
 9[tool.poetry.dependencies]
10python = "^3.9"
11
12[tool.poetry.dev-dependencies]
13pytest = "^5.2"
14
15[build-system]
16requires = ["poetry-core>=1.0.0"]
17build-backend = "poetry.core.masonry.api"

您可以在pyproject.toml文件中看到四个部分。这些部分称为表。它们包含诸如 Poetry 之类的工具识别和用于依赖项管理或构建例程的指令。

如果表名是特定于工具的，则必须以tool.为前缀。通过使用这样的子表，您可以为项目中的不同工具添加说明。在这种情况下，只有tool.poetry. 但是，你可能会看到这样的例子[tool.pytest.ini_options]为pytest在其他项目中。

在[tool.poetry]上面第 3 行的子表中，您可以存储有关您的 Poetry 项目的一般信息。您的可用键由 Poetry 定义。虽然有些键是可选的，但您必须指定四个键：

1. name: 你的包名
2. version: 包的版本，最好遵循语义版本控制
3. description：您的包裹的简短描述
4. authors: 作者列表，格式 name <email>

第[tool.poetry.dependencies]9 行和[tool.poetry.dev-dependencies]第 12行的子表对于您的依赖项管理至关重要。在下一部分向 Poetry 项目添加依赖项时，您将了解有关这些子表的更多信息。现在，重要的是要认识到的包相关性和发展依赖之间的区别。

该pyproject.toml文件的最后一个表位于第[build-system]15 行。该表定义了 Poetry 和其他构建工具可以使用的数据，但由于它不是特定于工具的，因此它没有前缀。Poetry 创建了pyproject.toml具有两个键的文件：

1. requires：构建包所需的依赖项列表，使此键成为必需
2. build-backend：用于执行构建过程的 Python 对象

如果您想更多地了解pyproject.toml文件的这一部分，那么您可以通过阅读PEP 517 中的源代码树来了解更多信息。

当您使用 Poetry 开始一个新项目时，这就是pyproject.toml您开始的文件。随着时间的推移，您将添加有关您的包和您正在使用的工具的配置详细信息。随着 Python 项目的增长，您的pyproject.toml文件也会随之增长。对于子表[tool.poetry.dependencies]和[tool.poetry.dev-dependencies]. 在下一节中，您将了解如何扩展这些子表。

使用 Poetry 的虚拟环境

当您开始一个新的 Python 项目时，创建一个虚拟环境是一种很好的做法。否则，您可能会混淆来自不同项目的不同依赖项。使用虚拟环境是 Poetry 的核心功能之一，它永远不会干扰您的全局 Python 安装。

但是，Poetry 不会在您启动项目时立即创建虚拟环境。您可以通过让 Poetry 列出连接到当前项目的所有虚拟环境来确认 Poetry 尚未创建虚拟环境。如果你还没有，cd进入rp-poetry/然后运行一个命令：

$ poetry env list

目前，不应该有任何输出。

当您运行某些命令时，Poetry 会一路创建一个虚拟环境。如果您想更好地控制虚拟环境的创建，那么您可能决定明确告诉 Poetry 您要为其使用哪个 Python 版本，然后从那里开始：

$ poetry env use python3

使用此命令，您将使用与安装 Poetry 相同的 Python 版本。使用python3的作品，当你在你的Python可执行程序PATH。

当你运行时env use，你会看到一条消息：

Creating virtualenv rp-poetry-AWdWY-py3.9 in ~/Library/Caches/pypoetry/virtualenvs
Using virtualenv: ~/Library/Caches/pypoetry/virtualenvs/rp-poetry-AWdWY-py3.9

如您所见，Poetry 为您的项目环境构建了一个唯一名称。该名称包含项目名称和 Python 版本。中间看似随机的字符串是您的父目录的哈希值。通过中间的这个唯一字符串，Poetry 可以处理系统上具有相同名称和相同 Python 版本的多个项目。这很重要，因为默认情况下，Poetry 在同一个文件夹中创建所有虚拟环境。

Poetry 无需任何其他配置，在virtualenvs/Poetry缓存目录的文件夹中创建虚拟环境：

如果要更改默认缓存目录，则可以编辑Poetry 的配置。当您已经在使用virtualenvwrapper或其他第三方工具来管理您的虚拟环境时，这会很有用。要查看当前配置，包括已配置的cache-dir，您可以运行以下命令：

$ poetry config --list

通常，您不必更改此路径。如果您想了解有关与 Poetry 的虚拟环境交互的更多信息，那么 Poetry 文档包含有关管理环境的一章。

只要您在项目文件夹中，Poetry 就会使用与之关联的虚拟环境。如果您有疑问，可以env list再次运行以下命令检查虚拟环境是否已激活：

$ poetry env list

这将显示类似rp-poetry-AWdWY-py3.9 (Activated). 有了激活的虚拟环境，您就可以开始管理一些依赖项并看到 Poetry 的魅力了。

声明你的依赖

Poetry 的一个关键元素是它对依赖项的处理。在开始之前，先看一下文件中的两个依赖表pyproject.toml：

# rp_poetry/pyproject.toml (Excerpt)

[tool.poetry.dependencies]
python = "^3.9"

[tool.poetry.dev-dependencies]
pytest = "^5.2"

当前为您的项目声明了两个依赖项。一个是 Python 本身。另一个是pytest，一个广泛使用的测试框架。正如您之前看到的，您的项目包含一个tests/文件夹和一个test_rp_poetry.py文件。使用pytest作为依赖项，Poetry 可以在安装后立即运行您的测试。

确保您在rp-poetry/项目文件夹中并运行命令：

$ poetry install

使用该install命令，Poetry 检查您的pyproject.toml文件中的依赖项，然后解析并安装它们。当您有许多依赖项需要使用不同版本的不同第三方包时，解析部分尤其重要。在安装任何包之前，Poetry 会确定哪个版本的包满足其他包设置为其要求的版本限制。

除了pytest它的要求之外，Poetry 还安装了项目本身。这样，您可以立即导入rp_poetry到您的测试中：

# tests/test_rp_poetry.py

from rp_poetry import __version__

def test_version():
    assert __version__ == "0.1.0"

安装项目包后，您可以导入rp_poetry测试并检查__version__字符串。随着pytest安装，您可以使用poetry run命令来执行测试：

 1$ poetry run pytest
 2========================= test session starts ==========================
 3platform darwin -- Python 3.9.1, pytest-5.4.3, py-1.10.0, pluggy-0.13.1
 4rootdir: /Users/philipp/Real Python/rp-poetry
 5collected 1 item
 6
 7tests/test_rp_poetry.py .                                        [100%]
 8
 9========================== 1 passed in 0.01s ===========================

您当前的测试已成功运行，因此您可以放心地继续编码。但是，如果您仔细观察第 3 行，就会发现有些奇怪。它说pytest-5.4.3，5.2不像pyproject.toml文件中所说的那样。接得好！

回顾一下，文件中的pytest依赖项pyproject.toml如下所示：

# rp_poetry/pyproject.toml (Excerpt)

[tool.poetry.dev-dependencies]
pytest = "^5.2"

^前面的插入符号 ( )5.2具有特定的含义，它是 Poetry 提供的版本约束之一。这意味着 Poetry 可以安装与版本字符串最左边的非零数字匹配的任何版本。这意味着5.4.3允许使用。版本6.0将不被允许。

当 Poetry 尝试解析依赖版本时，像插入符号这样的符号将变得很重要。如果只有两个要求，这并不太难。你声明的依赖越多，它就越复杂。让我们看看 Poetry 如何通过将新包安装到您的项目中来处理这个问题。

安装带有 Poetry 的包

您pip之前可能使用过安装不属于 Python 标准库的包。如果您pip install使用包名作为参数运行，则pip在Python Package Index上查找包。您可以以同样的方式使用 Poetry。

如果你想在requests你的项目中添加一个外部包，那么你可以运行一个命令：

$ poetry add requests

通过运行poetry add requests，您正在将最新版本的requests库添加到您的项目中。您可以使用版本约束，requests<=2.1或者requests==2.24如果您想更具体。当您不添加任何约束时，Poetry 将始终尝试安装最新版本的软件包。

有时，您只想在开发环境中使用某些包。使用pytest，您已经发现其中之一。另一种常见的库包括一个代码格式化像黑色，一个文档生成等斯芬克斯，和类似的一个静态分析工具pylint的，Flake8，mypy，或coverage.py。

要明确告诉 Poetry 一个包是一个开发依赖项，您可以poetry add使用该--dev选项运行。您还可以使用速记-D选项，它与以下内容相同--dev：

$ poetry add black -D

您添加requests为项目依赖项和black开发依赖项。Poetry 在后台为您做了一些事情。一方面，它将您声明的依赖项添加到pyproject.toml文件中：

# rp_poetry/pyproject.toml (Excerpt)

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.26.0"

[tool.poetry.dev-dependencies]
pytest = "^5.2"
black = "^21.9b0"

Poetry 将该requests包作为项目依赖项添加到tool.poetry.dependencies表中，同时将其black作为开发依赖项添加到tool.poetry.dev-dependencies.

区分项目依赖项和开发依赖项可以防止安装用户不需要运行程序的需求。开发依赖项仅与您的包的其他开发人员相关，他们希望pytest使用black. 当用户安装您的软件包时，他们只会安装requests它。

除了对pyproject.toml文件的更改之外，Poetry 还创建了一个名为poetry.lock. 在此文件中，Poetry 会跟踪您在项目中使用的所有包和确切版本。

引脚依赖关系 poetry.lock

如果您想使用 Python 构建网络爬虫，那么您可能需要使用Beautiful Soup来解析您的数据。将其添加到文件中的tool.poetry.dependencies表中pyproject.toml：

# rp_poetry/pyproject.toml (Excerpt)

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.26.0"
beautifulsoup4 = "4.10.0"

通过添加beautifulsoup4 = "4.10.0"，您告诉 Poetry 它应该完全安装这个版本。当您向pyproject.toml文件添加需求时，它尚未安装。只要poetry.lock你的项目中没有文件存在，你就可以poetry install在手动添加依赖后运行，因为 Poetry 会先查找poetry.lock文件。如果没有找到，Poetry 将解析pyproject.toml文件中列出的依赖项。

一旦poetry.lock文件存在，Poetry 将依赖该文件来安装依赖项。仅运行poetry install会触发警告，提示两个文件不同步并会产生错误，因为 Poetry 尚不知道beautifulsoup4项目中的任何版本。

要将pyproject.toml文件中手动添加的依赖项固定到poetry.lock，您必须首先运行以下poetry lock命令：

$ poetry lock
Updating dependencies
Resolving dependencies... (1.5s)

Writing lock file

通过运行poetry lock，Poetry 处理pyproject.toml文件中的所有依赖项并将它们锁定到poetry.lock文件中。诗歌并不止于此。运行时poetry lock，Poetry 还会递归遍历并锁定您的直接依赖项的所有依赖项。

$ poetry lock --no-update
Resolving dependencies... (0.1s)

现在您已经固定了所有依赖项，是时候安装它们以便您可以在您的项目中使用它们。

安装依赖项 poetry.lock

如果您按照上一节中的步骤操作，那么您已经安装pytest并black使用了该poetry add命令。您还锁定了beautifulsoup4，但您还没有安装 Beautiful Soup。要验证beautifulsoup4尚未安装，请使用以下命令打开Python 解释器poetry run：

$ poetry run python3

执行poetry run python3将在 Poetry 的环境中打开一个交互式REPL会话。首先，尝试导入requests. 这应该完美无缺。然后尝试 importing bs4，这是 Beautiful Soup 的模块名称。这应该会引发错误，因为尚未安装 Beautiful Soup：

>>> import requests
>>> import bs4
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ModuleNotFoundError: No module named 'bs4'

正如预期的那样，您可以requests毫无困难地导入，并且bs4找不到模块。通过键入exit()并点击退出交互式 Python 解释器Enter。

使用poetry lock命令锁定依赖项后，您必须运行该poetry install命令，以便您可以在项目中实际使用它们：

$ poetry install
Installing dependencies from lock file

Package operations: 2 installs, 0 updates, 0 removals

  • Installing soupsieve (2.2.1)
  • Installing beautifulsoup4 (4.10.0)

Installing the current project: rp-poetry (0.1.0)

通过运行poetry install，Poetry 读取poetry.lock文件并安装其中声明的所有依赖项。现在，bs4已准备好在您的项目中使用。要对此进行测试，请输入poetry run python3并导入bs4Python 解释器：

>>> import bs4
>>> bs4.__version__
'4.10.0'

完美的！这次没有错误，并且您拥有您声明的确切版本。这意味着 Beautiful Soup 已正确固定在您的poetry.lock文件中，已安装在您的项目中，并且可以使用了。要列出项目中的可用包并检查它们的详细信息，您可以使用该show命令。当您使用--help标志运行它时，您将看到如何使用它：

$ poetry show --help

要检查包，您可以使用show包名称作为参数，也可以使用--tree选项将所有依赖项以树的形式列出。这将帮助您查看项目的嵌套需求。

将poetry添加到现有项目

很有可能，您的项目不是从poetry new命令开始的。或者，您可能继承了一个不是用 Poetry 创建的项目，但现在您想使用 Poetry 进行依赖管理。在这些类型的情况下，您可以将 Poetry 添加到现有的 Python 项目中。

# rp-hello/hello.py

print("Hello World!")

$ poetry init

This command will guide you through creating your pyproject.toml config.

Package name [rp-hello]: rp-hello
Version [0.1.0]:
Description []: My Hello World Example
Author [Philipp <philipp@realpython.com>, n to skip]:
License []:
Compatible Python versions [^3.9]:

Would you like to define your main dependencies interactively? (yes/no) [yes] no
Would you like to define your development dependencies interactively? (yes/no) [yes] no
Generated file

# rp-hello/pyproject.toml

[tool.poetry]
name = "rp-hello"
version = "0.1.0"
description = "My Hello World Example"
authors = ["Philipp <philipp@realpython.com>"]

[tool.poetry.dependencies]
python = "^3.9"

[tool.poetry.dev-dependencies]

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

$ poetry run python3 hello.py
Creating virtualenv rp-simple-UCsI2-py3.9 in ~/Library/Caches/pypoetry/virtualenvs
Hello World!

命令参考

本教程向您介绍了 Poetry 的依赖管理。在此过程中，您使用了一些 Poetry 的命令行界面 (CLI) 命令：

您可以查看Poetry CLI 文档以了解有关上述命令和 Poetry 提供的其他命令的更多信息。您还可以poetry --help直接在终端中运行以查看信息！

结论

在本教程中，您探索了如何创建新的 Python Poetry 项目以及如何将 Poetry 添加到现有项目中。Poetry 的一个关键部分是pyproject.toml文件。与 结合使用poetry.lock，您可以确保安装项目所需的每个包的确切版本。当您跟踪poetry.lockGit 存储库中的文件时，您还要确保项目中的所有其他开发人员在他们的机器上安装相同的依赖项版本。

在本教程中，您学习了如何：

• 开始一个新的Poetry项目
• 将 Poetry 添加到现有项目
• 使用pyproject.toml文件
• Pin dependencies
• 安装依赖项 poetry.lock
• 执行基本的Poetry CLI命令

本教程侧重于 Poetry 依赖项管理的基础知识，但 Poetry 还可以帮助您构建和上传包。如果您想体验一下这种功能，那么您可以阅读有关在将开源 Python 包发布到 PyPI时如何使用 Poetry 的信息）。