Poetry

[官网 - Poetry] https://python-poetry.org/

安装

pip install poetry

简单使用

初始化 poetry 项目

cd ~ && mkdir demo
poetry init

管理虚拟环境

poetry 预设了很多自己的虚拟环境配置，这些配置可以通过 poetry config 进行修改

当用户在执行 poetry add 等指令时，poetry 都会自动检查当下是否正在使用虚拟环境：

• 如果是，则会直接安装模块到当前的虚拟环境下
• 如果否，则会自动帮你创建一个新的虚拟环境，然后再安装模块

创建虚拟环境 (Linux 默认在 ~/.cache/pypoetry/)

# 虚拟环境的命名模式为 项目名-随机数-python版本
cd demo
poetry env use python
# 输出 Using virtualenv: /home/yin/.cache/pypoetry/virtualenvs/demo-NLZ_vRHG-py3.11

在当前项目创建虚拟环境

# 查看 poetry 的几个主要设定
poetry config --list
# 更改设置
poetry config virtualenvs.in-project true
# 先把之前创建的虚拟环境删除
poetry env remove python
# 重新创建虚拟环境
poetry env use python
# 输出 Using virtualenv: ~/demo/.venv

启动与退出虚拟环境

在项目目录下使用 poetry shell 就可以进入到虚拟环境

poetry shell 指令会检查当前目录或上层目录是否存在 pyproject.toml 来确定需要启动的虚拟环境

退出虚拟环境输入 exit

Poetry 指令

安装

poetry add

相较于 pip install , 例如使用命令 poetry add flask , poetry 会将全部信息列出来(flask 及其依赖)。

同时项目中的 pyproject.toml 会新增 flask = "^2.3.2" , 而 flask 的其余依赖不会出现在 toml 文件中。

这里是一个非常大的优点, 以便区分那些是用户安装的第三方模块, 那些是第三方模块一并安装的依赖。

poetry.lock 与更新顺序

除了更新 pyproject.toml , 此时项目中还会新增一个文件, 名为 poetry.lock , 它实际上就相当于 pip 的 requirements.txt , 详细记录了所有安装的模块与版本。

当使用 poetry add 指令时, poetry 会自动依序帮你做完这三件事：

1. 更新 pyproject.toml
2. 依照 pyproject.toml 的内容，更新 poetry.lock
3. 依照 poetry.lock 的内容，更新虚拟环境

由此可见, poetry.lock 的内容是取决于 pyproject.toml , 但两者并不会自己连动, 一定要基于特定指令才会进行同步与更新, poetry add 就是一个典型案例。

poetry lock ：更新 poetry.lock

档自行修改了 pyproject.toml 内容, 此时 poetry.lock 的内容与 pyproject.toml 出现了脱钩., 必须让它依照新的 pyproject.toml 内容更新、同步, 使用指令

poetry lock

虚拟环境如果要重新建立, 是基于 poetry.lock 的内容来安装模块, 而非 pyproject.toml

但要特别注意的是， poetry lock 指令，仅会更新 poetry.lock ，不会同时安装模块至虚拟环境

因此，在执行完 poetry lock 指令后，必须再使用 poetry install 来安装模块。否则就会出现 poetry.lock 和虚拟环境不一致的状况。

更多 poetry lock 细节可参考 官方文件，其中特别值得注意的是 --no-update 参数

新增模块至 dev-dependencies

有些模块, 比如 pytest 、 black 等等, 只会在开发环境中使用, 产品的部署环境并不需要。

Poetry 允许你区分这两者，将上述的模块安装至 dev-dependencies 区块，方便让你轻松建立一份「不包含」 dev-dependencies 开发模块的安装清单。

在此以 Black 为例，安装方式如下：

poetry add black --group dev

结果的区别显示在 pyproject.toml 里：

[tool.poetry.dependencies]
python = "^3.10"
flask = "^2.3.2"[tool.poetry.group.dev.dependencies]
black = "^23.7.0"

可以看到 black 被列在不同区块： tool.poetry.dev-dependencies 。

强烈建议善用 dev-dependencies

善用 --group dev 参数，明确区分开发环境，我认为非常必要。

Poetry 更新模块

使用 poetry update 更新所有模块

使用 poetry update requests toml 更新指定模块

注意 : 关于模块版本的升级限制规则，取决于你在 pyproject.toml 中的设定

列出全部模块清单

使用 poetry show

注意 : 这里的清单内容并不是来自于虚拟环境, 而是来自于 poetry.lock 的内容, 不一定和虚拟环境中的一样, 比如你使用了 pip install 指令安装模块, 就不会记载在 poetry.lock 中, 那 poetry show 自然也不会显示。

树状显示模块依赖层级

poetry show --tree

也可以只显示指定模块的依赖层级, 以 celery 为例：

poetry show celery --tree

Poetry 移除模块

使用 poetry remove 指令。和 poetry add 一样，可以加上 -D 参数来移除置于开发区的模块。

前面已经提过, pip uninstall 只会移除你所指定的模块, 而不会连同依赖模块一起移除, 这就是Poetry的优点

输出 dev-dependencies

因为 poetry export 预设只会输出 toml 中的 [tool.poetry.dependencies] 区块的模块！还记得上面我们把 Black 安装到 [tool.poetry.dev-dependencies] 了吗?

基于需求，必须输出 [tool.poetry.dev-dependencies] 的模块，才能看到 Black。

加上 --dev 参数即可：

poetry export -f requirements.txt -o requirements.txt --without-hashes --dev

输出的 requirements.txt 内容：

black==22.3.0; python_full_version >= "3.6.2"
click==8.1.2; python_version >= "3.7" and python_full_version >= "3.6.2"
colorama==0.4.4; python_version >= "3.7" and python_full_version >= "3.6.2" and platform_system == "Windows"
...

虽然长得有点不一样，但这个档案确实是可以 pip install 的。

Poetry 常用指令清单

• poetry add
• poetry remove
• poetry export
• poetry env use
• poetry shell
• poetry show
• poetry init
• poetry install

修改 poetry 镜像源

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