强大的包管理器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=1POETRY_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>。
本文来自博客园，作者：Kenny_LZK，转载请注明原文链接：https://www.cnblogs.com/liuzhongkun/p/16797346.html
