强大的包管理器Poetry

Poetry

一、 概述

1、 介绍

Poetry 是Python 中用于依赖管理和**打包的工具。**它允许您声明项目所依赖的库，并将为您管理（安装/更新）它们。Poetry 提供了一个锁定文件以确保可重复安装，并且可以构建您的项目以进行分发。

作为一个传统虚拟环境的实现，poetry 凭借其强大的依赖分析能力被大量项目所推荐的虚拟环境管理工具。

对于绝大部分的开发者而言，poetry 作为首选的虚拟环境管理工具是最优方案，其强大的依赖分析能力、环境封装能力以及庞大的社区均可为你的开发保驾护航，这也是我目前最为推荐所有 python 开发者所掌握的虚拟环境管理工具。

2、 环境配置

2.1 官方推荐

2.1.1 安装

curl -sSL https://install.python-poetry.org | python3 -

环境变量：

• POETRY_HOME：安装目录
• POETRY_PREVIEW：是否安装预发布版本，如果需要，设置为POETRY_PREVIEW=1
• POETRY_VERSION：指定安装的版本
• --git：从git存储库中安装

使用示例：

curl -sSL https://install.python-poetry.org | python3 - --git https://github.com/python-poetry/poetry.git@master
curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.2.0 python3 -

2.1.2 配置环境变量

poetry安装程序在一个众所周知的、特定于平台的目录中创建一个包装器：

• $HOME/.local/bin在 Unix 上
• %APPDATA%\Python\Scripts在 Windows 上
• $POETRY_HOME/bin如果$POETRY_HOME设置

2.1.3 更新poetry

poetry self update  # 更新
poetry self update --preview  # 安装预装版
poetry self update 1.2.0  # 更新到指定的版本

2.1.4 卸载poetry

curl -sSL https://install.python-poetry.org | python3 - --uninstall
curl -sSL https://install.python-poetry.org | POETRY_UNINSTALL=1 python3 -

2.2 pip安装

pip install poetry  # 安装诗歌
pipx upgrade poetry  # 更新诗歌
pip uninstall poetry  # 卸载诗歌

最后，使用poetry --version进行测试：

如果没法使用，记得将poetry添加到环境变量中去

二、 基础使用

1、 创建项目

poetry new poetry_demo

生成的目录结果为：

poetry-demo
├── pyproject.toml
├── README.rst
├── poetry_demo
│   └── __init__.py
└── tests
    ├── __init__.py
    └── test_poetry_demo.py

该pyproject.toml文件是这里最重要的。这将协调您的项目及其依赖项。现在，它看起来像这样：

[tool.poetry]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = ["kun <3500515050@qq.com>"]
readme = "README.md"
packages = [{include = "poetry_demo"}]

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


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

2、 初始化包

Poetry 可用于“初始化”预填充目录，而不是创建新项目。在目录中以交互方式创建pyproject.toml文件pre-existing-project

cd pre-existing-project
poetry init

3、 指定依赖项

如果要向项目添加依赖项，可以在tool.poetry.dependencies部分中指定它们。

[tool.poetry.dependencies]
pendulum = "^2.1"

如您所见，它采用包名称和版本约束的映射。

tool.poetry.sourcePoetry 使用此信息在您在该部分注册的包“存储库”中搜索正确的文件集，或者默认情况下在PyPI上搜索。

pyproject.toml此外，您可以使用add命令而不是手动修改文件。

poetry add pendulum

它将自动找到合适的版本约束并安装包和子依赖项。

Poetry 支持丰富的依赖规范语法，包括插入符号、波浪号、通配符、不等式和 多重约束要求。

4、 运行项目

要运行您的脚本，只需使用poetry run python your_script.py. 同样，如果您有命令行工具，pytest或者black您可以使用poetry run pytest.

同时，我们还可以手动激活虚拟环境：

poetry shell  # 进入
exit  # 退出

# 同时，还可以像pipenv一样指定虚拟环境激活，使用虚拟环境里面的activate文件

5、 安装依赖

Poetry如何下载正确的文件？

当您在 中指定依赖项时，Poetry 首先获取您请求的包的名称，并在您使用该密钥pyproject.toml注册的任何存储库中搜索它。repositories如果您没有注册任何额外的存储库，或者它在您指定的存储库中找不到具有该名称的包，它会回退到 PyPI。

当 Poetry 找到正确的包时，它会尝试为您指定的版本约束找到最佳匹配。

poetry install

使用这种方式时，有注意一个情况，就是在第一次运行后，会生成一个poetry.lock的文件，将第三方库的版本锁定，这意味着，后面的开发人员根据puproject.toml安装的时候，第三方库的版本是固定的。

install当poetry.lock文件存在时运行会解析并安装您在中列出的所有依赖项pyproject.toml，但 Poetry 使用中列出的确切版本poetry.lock来确保包版本对于在您的项目中工作的每个人都是一致的。

使用poetry.lock进行项目的版本控制是非常重要的

只安装依赖项的方法：

poetry install --no-root

poetry.lock文件会阻止您自动获取最新版本的依赖项。要更新到最新版本，请使用update命令。这将获取最新的匹配版本（根据您的pyproject.toml文件）并使用新版本更新锁定文件。（这相当于删除poetry.lock文件并install重新运行。）

6、 列出可用包

要列出所有可用的包，您可以使用该show命令。

poetry show

如果要查看某个包的详细信息，可以传递包名。

poetry show pendulum

# name        : pendulum
# version     : 1.4.2
# description : Python datetimes made easy
# 
# dependencies
#  - python-dateutil >=2.6.1
#  - tzlocal >=1.4
#  - pytzdata >=2017.2.2
# 
# required by
#  - calendar >=1.4.0

三、 管理依赖项

1、 依赖组

poetry提供了一种按组****组织依赖关系的方法。例如，您可能拥有仅在测试项目或构建文档时需要的依赖项。

要声明一个新的依赖组，请使用一个包含依赖组名称的tool.poetry.group.部分<group>例如，test:

[tool.poetry.group.test]  # This part can be left out

[tool.poetry.group.test.dependencies]
pytest = "^6.0.0"
pytest-mock = "*"

隐式main组：

[tool.poetry.dependencies]  # main dependency group
httpx = "*"
pendulum = "*"
[tool.poetry.group.test.dependencies]  # test组
pytest = "^6.0.0"
pytest-mock = "*"

[tool.poetry.group.dev.dependencies]  # dev组
pytest = "^6.0.0"
pytest-mock = "*"

2、 可选组

依赖组可以声明为可选。当您拥有一组仅在特定环境或特定目的中需要的依赖项时，这是有意义的。

[tool.poetry.group.docs]
optional = true

[tool.poetry.group.docs.dependencies]
mkdocs = "*"

我们使用--with命令将可选组添加到安装的第三方库中：

poetry install --with docs

3、 添加依赖

我们需要将依赖添加到指定的组中：

poetry add pytest --group test

如果该组尚不存在，则会自动创建。

依赖的规范在官方文档中较为详细：https://python-poetry.org/docs/dependency-specification/

4、 安装和删除

4.1 安装依赖组

poetry install --without test,docs  # 使用 --without 将指定组排除安装
poetry install --with docs  # 您使用 --with 选项选择加入可选组

一起使用时，--without优先于--with. 例如，以下命令将仅安装可选test组中指定的依赖项。

poetry install --with test,docs --without docs

最后，在某些情况下，您可能只想安装特定的依赖组而不安装默认的依赖组。为此，您可以使用该--only选项：

poetry install --only docs  # 安装可选组
poetry install --only main  # 安装项目的运行时依赖项
poetry install --only-root  # 如果要安装项目根目录，并且没有其他依赖项

4.2 删除依赖组

poetry remove mkdocs --group docs

从特定组中删除包的选项

4.2 同步依赖项

Poetry支持所谓的依赖同步。依赖同步确保poetry.lock文件中锁定的依赖是环境中唯一存在的依赖，删除任何不必要的依赖。

这是通过使用命令的--sync选项来完成的install：

poetry install --sync

命令的一些详细的使用方法在官方文档中比较详细，大家可以查看官方文档：https://python-poetry.org/docs/cli/

四、 存储库

Poetry 支持使用PyPI和私有存储库来发现包以及发布您的项目。

默认情况下，Poetry 配置为使用PyPI存储库，用于包安装和发布。

因此，当您向项目添加依赖项时，Poetry 将假定它们在 PyPI 上可用。

这代表了大多数情况，对于大多数用户来说可能就足够了。

1、 换源

默认情况下，Poetry 配置为使用 Python 生态系统的规范包索引 PyPI。

除了隐式配置的PyPI源之外pypi，包源是项目本地的，必须在项目 pyproject.toml文件中配置。这与发布包时使用的配置不同**。**

从私有包源安装第三方库：

poetry source add foo https://pypi.example.org/simple/

在配置文件中生成以下配置：

[[tool.poetry.source]]
name = "foo"
url = "https://foo.bar/simple/"
default = false
secondary = false

注意：

• 如果为项目定义了包源，则这些源将优先于 PyPI。如果您不希望出现这种情况，则应将所有包源声明为secondary。

配置默认包源：

默认情况下，Poetry 将PyPI配置为项目的默认包源。您可以更改此行为并仅通过添加带有default = true.

poetry source add --default foo1 https://pypi.example.org/simple/

次要包源：

如果包源配置为辅助，这意味着在选择默认包源中也存在的兼容包分发时，这些将被赋予较低的优先级。

您可以在包源配置中将包源配置为辅助源secondary = true。

poetry source add --secondary foo2 https://pypi.tuna.tsinghua.edu.cn/simple

可以有多个二级包源

同时，每个包可以指定从一个包源下载：

poetry add --source pypi httpx@^0.22.0  # 使用@指定httpx的版本

2、 发布存储库

2.1 配置凭证

poetry config http-basic.foo <username> <password>

比如，配置pypi的令牌和凭证

poetry config pypi-token.pypi my-token  # 配置令牌
poetry config http-basic.pypi <username> <password>  # 使用用户名和密码配置凭证

2.2 生成并发布

锁定文件处理：

对于您的库，您可以根据poetry.lock需要提交文件。这可以帮助您的团队始终针对相同的依赖项版本进行测试。但是，这个锁文件不会对其他依赖它的项目产生任何影响。它只对主项目有影响。

如果您不想提交锁定文件并且正在使用 git，请将其添加到.gitignore.

poetry publish --build  # 发布前进行包的生成

此命令将以两种不同的格式打包您的库：sdist一种是源格式，另wheel一种是compiled包。

使用poetry publish -r my-repository发布到私有库

五、 环境管理

1、 简介

诗歌将项目环境隔离作为其核心特征之一。

这意味着它将始终与您的全局 Python 安装隔离开来。为此，它将首先检查它当前是否在虚拟环境中运行。如果是，它将直接使用它而不创建新的。但如果不是，它将使用它已经创建的一个或为您创建一个全新的。

默认情况下，Poetry 会尝试使用 Poetry 安装过程中使用的 Python 版本来为当前项目创建虚拟环境。

python但是，由于各种原因，这个 Python 版本可能与项目的需求不兼容。在这种情况下，Poetry 将尝试找到一个并使用它。如果它无法这样做，则会提示您显式激活一个。

2、 结合其他包管理器

如果你使用pyenv 之类的工具来管理不同的 Python 版本，你可以将实验virtualenvs.prefer-active-python选项设置为true. 然后诗歌会尝试找到python你的 shell 的当前状态。

例如，如果您的项目需要比系统可用的更新的 Python，则标准工作流程将是：

pyenv install 3.9.8
pyenv local 3.9.8  # Activate Python 3.9 for the current project
poetry install

3、 环境操作

有时这对您的系统可能不可行，尤其是在 Windowspyenv 不可用的情况下，或者您只是希望更明确地控制您的环境。为此，您可以使用该env use命令告诉 Poetry 哪个 Python 版本用于当前项目。

poetry env use /full/path/to/python  # 进行环境的切换
poetry env info  # 显示当前环境的信息
poetry env info --path  # 显示当前环境的路径
poetry env list [--full-path]# 列出与项目关联的环境

移除环境：

# 移除指定的环境
poetry env remove /full/path/to/python
poetry env remove python3.7
poetry env remove 3.7
poetry env remove test-O3eWbxRl-py3.7

poetry env remove --all  # 移除所有的环境

六、 配置

1、 相关操作

# Poetry 提供了通过将--local选项传递给config命令来获得特定于项目的设置的能力
poetry config virtualenvs.create false --local

# 列出当前的配置
poetry config --list

# 显示特定配置的值
poetry config virtualenvs.path

# 修改特定配置的值
poetry config virtualenvs.path D:\\poetryCache

# 移除某一配置默认的值
poetry config virtualenvs.path --unset

使用环境变量：

export POETRY_VIRTUALENVS_PATH=/path/to/virtualenvs/directory  # 设置虚拟环境的路径
export POETRY_HTTP_BASIC_MY_REPOSITORY_PASSWORD=secret  # 设置密钥

2、 默认目录

配置目录：

• Linux：$XDG_CONFIG_HOME/pypoetry或~/.config/pypoetry
• 视窗：%APPDATA%\pypoetry
• 苹果系统：~/Library/Preferences/pypoetry

POETRY_CONFIG_DIR您可以通过设置环境变量来覆盖 Config 目录。

数据目录：

• Linux：$XDG_DATA_HOME/pypoetry或~/.local/share/pypoetry
• 视窗：%APPDATA%\pypoetry
• 苹果系统：~/Library/Application Support/pypoetry

POETRY_DATA_DIR您可以通过设置或POETRY_HOME环境变量来覆盖数据目录。如果POETRY_HOME设置，它将被赋予更高的优先级。

缓存目录：

• Linux：$XDG_CACHE_HOME/pypoetry或~/.cache/pypoetry
• 视窗：%APPDATA%\pypoetry\Cache
• 苹果系统：~/Library/Caches/pypoetry

POETRY_CACHE_DIR您可以通过设置环境变量来覆盖缓存目录。

3、 可用配置

cache-dir：

类型：string

Poetry 使用的缓存目录的路径。

默认为以下目录之一：

• 苹果系统：~/Library/Caches/pypoetry
• 视窗：C:\Users\\AppData\Local\pypoetry\Cache
• Unix：~/.cache/pypoetry

experimental.system-git-client：

类型：boolean

默认：false

使用系统 git 客户端后端执行 git 相关任务。

Poetrydulwich默认使用 git 相关任务不依赖 git 客户端的可用性。

如果您遇到任何问题，请设置true为使用系统 git 后端。

installer.max-workers：

类型：int

默认：number_of_cores + 4

设置使用并行安装程序时的最大工作人员数。由number_of_cores决定os.cpu_count()。如果这引发NotImplementedError异常，number_of_cores则假定为 1。

如果此配置参数设置为大于 的值number_of_cores + 4，则最大工作人员的数量仍被限制为number_of_cores + 4。

installer.no-binary：

类型：string | boolean

默认：false

设置此配置后，用户可以为所有或特定包配置包分发格式策略。

配置	描述
:all:或者true	禁止所有包的二进制分发。
:none:或者false	允许所有包的二进制分发。
package[,package,..]	仅禁止指定软件包的二进制分发。

仅在使用新安装程序时才遵守此配置。如果您已禁用它，请考虑重新启用它。

与此处描述的所有配置一样，这是用户特定的配置。这意味着在生成锁定文件或解决依赖关系时不会考虑这一点。这仅在选择应将哪个依赖分布安装到 Poetry 管理环境中时应用。

对于项目特定用途，建议使用--local。

poetry config --local installer.no-binary :all:

对于使用环境变量配置的 CI 或容器环境 ，这可能很有用。

export POETRY_INSTALLER_NO_BINARY=:all:

除非这是系统范围内需要的，否则如果全局配置，如果设置不正确，您可能会在所有项目中遇到较慢的安装时间。

installer.parallel：

类型：boolean

默认：true

使用新的 ( >=1.1.0) 安装程序时使用并行执行。

virtualenvs.create：

类型：boolean

默认：true

如果尚不存在，则创建一个新的虚拟环境。

如果设置为false，Poetry 将不会创建新的虚拟环境。如果它检测到虚拟环境，{cache-dir}/virtualenvs或者{project-dir}/.venv它会将依赖项安装到其中，否则它将依赖项安装到系统 python 环境中。

如果 Poetry 检测到它在激活的虚拟环境中运行，它永远不会创建新的虚拟环境，无论为virtualenvs.create。

请注意，将依赖项安装到系统环境中可能会升级或卸载现有软件包，从而破坏其他应用程序。

这就是为什么建议始终创建虚拟环境的原因。在 Docker 容器中也是如此，因为它们也可能包含其他 Python 包。

virtualenvs.in-project

类型：boolean

默认：None

在项目的根目录中创建 virtualenv。

如果未明确设置，poetry默认情况下将在目录下创建虚拟环境 {cache-dir}/virtualenvs或在可用时使用该{project-dir}/.venv目录。

如果设置为true，则将在项目根目录中创建一个命名为.venv的文件夹作为 virtualenv 。

如果设置为false，poetry将忽略现有.venv目录。

virtualenvs.options.always-copy：

类型：boolean

默认：false

如果设置为true参数，则在创建虚拟环境时--always-copy传递给virtualenv，以便将所有需要的文件复制到其中而不是符号链接。

virtualenvs.options.no-pip：

类型：boolean

默认：false

如果设置为参数true，则在创建虚拟环境时，传递--no-pip参数。这意味着当创建新的虚拟环境virtualenv时，不会在该环境中安装 pip。

Poetry 在其内部操作中使用pip嵌入在virtualenv安装包中的轮子作为 Poetry 运行时环境中的依赖项。如果用户poetry run pip在此选项设置为 时运行true，则使用pip的嵌入实例pip。

如果您想要一个没有附加包的虚拟环境，您可以安全地将其与 no-setuptools一起设置为true。这对于生产环境来说是可取的。

virtualenvs.options.no-setuptools

类型：boolean

默认：false

如果设置为参数true，则在创建虚拟环境时传递--no-setuptools给该参数。这意味着当创建新的虚拟环境virtualenv时，不会在该环境中安装setuptools。Poetry，因为它的内部操作，不需要并且可以安全地设置为 true。

virtualenvs.options.system-site-packages

类型：boolean

默认：false

授予对系统站点包目录的虚拟环境访问权限。适用于 virtualenv 创建。

virtualenvs.path

类型：string

默认：{cache-dir}/virtualenvs

将创建虚拟环境的目录。

virtualenvs.prefer-active-python

类型：boolean

默认：false

使用当前激活的 Python 版本来创建一个新的虚拟环境。如果设置为false，则使用 Poetry 安装期间使用的 Python 版本。

virtualenvs.prompt

类型：string

默认：{project_name}-py{python_version}

定义激活虚拟环境时要显示的提示的格式字符串。变量project_name和python_version可用于格式化。

repositories.<name>

类型：string

设置一个新的替代存储库。

http-basic.<name>：

类型：(string, string)

为设置name存储库凭据（username和password）。

pypi-token.<name>：

类型：string

为存储库设置凭据（使用 API 令牌）<name> 。

certificates.<name>.cert：

类型：string | boolean

为存储库设置自定义证书颁发机构<name>。

如果此存储库可以跳过 TLS 证书验证，则可以将此配置设置为false。

certificates.<name>.client-cert：

类型：string

为存储库设置客户端证书<name>。