# poetry

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

python版本要求：python 3.8+

# 名词解释

# 虚拟环境

虚拟环境是指内建的 venv 或 virtualenv 、 conda 以及其他用来创建与管理 Python 虚拟环境的工具，不同的虚拟环境各自独立，存放的位置、安装的模块也都不一样。

# 模块管理

模块是指虚拟环境中安装的第三方模块及其版本。大多数项目对第三方库的版本都是有特定要求，如果对旧版本的项目使用新版本的依赖，可能会报很奇怪的错误。

# 依赖管理

安装第三方模块时，第三方模块可能会安装自己依赖的模块。当安装两个以上模块时，就可能出现第三方模块的依赖出现冲突。这种情况一般是依赖的版本冲突。这种就叫做相关性依赖。

# 修改poetry镜像源

# 全局配置

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

# 项目配置

在项目toml文件中增加如下配置

[[tool.poetry.source]]
name = "netease"
url = "https://mirrors.163.com/pypi/simple/"
priority = "primary"

# 安装

Poetry应始终安装在专用的虚拟环境中，以将其与系统的其他部分隔离开来。在任何情况下，它都不应该安装在由Poetry管理的项目环境中。这确保了Poetry自身的依赖项不会意外升级或卸载。此外：不应激活安装诗歌的隔离虚拟环境来运行诗歌命令。

我们接下来使用pipx安装poetry，安装完成后直接在命令行使用poetry即可。

如果你没有安装pipx，请参考pipx目录

安装

pipx install poetry

更新

pipx upgrade poetry

卸载

pipx uninstall poetry

# 指令

# 初始化项目

这里创建一个poetry-demo的项目

X:\>mkdir poetry-demo
X:\>cd poetry-demo
X:\poetry-demo>poetry init

然后对话交互，全部回车，最后生成pyproject.toml配置

# 配置管理

可以使用poetry config --list指令来查看poetry的设定

PS C:\Users\cheng> poetry config --list
cache-dir = "C:\\Users\\cheng\\AppData\\Local\\pypoetry\\Cache"
experimental.system-git-client = false
installer.max-workers = null
installer.modern-installation = true
installer.no-binary = null
installer.parallel = true
keyring.enabled = true
solver.lazy-wheel = true
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.options.always-copy = false
virtualenvs.options.no-pip = false
virtualenvs.options.no-setuptools = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "E:\\poetry"
virtualenvs.prefer-active-python = true
virtualenvs.prompt = "{project_name}-py{python_version}"
warnings.export = true

virtualenvs.create 检查不到虚拟环境是否自动创建新的虚拟环境 virtualenvs.in-project 如果设置为true，则会将虚拟环境目录建在项目目录下 virtualenvs.path 虚拟环境存放目录

设置虚拟环境的方式

poetry config virtualenvs.in-project true

# 创建虚拟环境

TIP

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

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

创建指令使用指令 poetry env use python
启动虚拟环境 poetry shell
退出虚拟环境 exit
查看虚拟环境配置中我们配置虚拟环境目录为virtualenvs.path = "E:\\poetry"，这里我们看到新创建的目录poetry-demo-KUQZbBxs-py3.11

虚拟环境目录名组成：项目名-随机字符-python版本组成
当前项目下创建虚拟环境配置中我们配置virtualenvs.in-project=true则可将虚拟环境创建在项目目录下

# 安装模块

    poetry add

[tool.poetry.dependencies]
python = "^3.10"
flask = "^2.3.2"  # 新增部分

TIP

poetry 会将所有的信息全部列出来，并且清楚的告知了新增了那些第三方模块。但是pyproject.toml只会新增flask的依赖，其余依赖不会出现在toml文件中

# poetry.lock

当使用poetry add后，项目中还会增加一个文件poetry.lock

当使用 poetry add 指令时，poetry 会自动依序帮你做完这三件事：更新 pyproject.toml。依照 pyproject.toml 的内容，更新 poetry.lock 。依照 poetry.lock 的内容，更新虚拟环境。

WARNING

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

如果自行修改了pyproject.toml内容，比如更改了特定模块的版本，此时lock文件和toml文件会脱钩，必须让lock文件依据新的toml文件进行内容更新、同步。

poetry lock

WARNING

poetry lock 指令，仅会更新 poetry.lock ，不会同时安装模块至虚拟环境

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

特别注意： --no-update 参数，当使用poetry install来安装模块时，会自动更新其他依赖项，可以通过增加 --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 。

WARNING

强烈建议善用 dev-dependencies

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

首先，这些模块常常属于「检测型」工具，相关的依赖模块着实不少！比如 flake8 ，它依赖了 pycodestyle 、 pyflakes 、 mccabe 等等，还有 black 、 pre-commit ，依赖模块数量也都很可观

# 更新模块

poetry update

更新指定模块

poetry update requests toml

# 列出全部模板清单

poetry show 特别提醒的是，这里的清单内容并不是来自于虚拟环境，这点和 pip 不同，而是来自于 poetry.lock 的内容。

树状显示依赖层级
```
poetry show --tree
```
只显示指定模块的依赖层级
```
poetry show celery --tree
```

# 移除模块

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

TIP

poetry remove不仅可以移除模块，会连依赖一并移除，这是pip所部具备的

# 输出 Poetry 虚拟环境的 requirements.txt

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

dev 环境中的依赖不会被输出

如果想输出dev-dependencies，需要增加--dev参数

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

输出的requirements.txt