Poetry入门教程

以前使用模块管理和虚拟环境为pip和Virtualenv组合，随着Rasa、Dify等开源项目逐步使用Poetry模块管理，也开始尝试使用Poetry。本文简要介绍Poetry入门操作。

1.Poetry安装

可参考Poetry官网[1]推荐的安装方式：

通过Windows的Powershell如下：

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

配置Poetry环境变量：

查看Poetry版本和路径：

通过poetry new创建一个新的Poetry项目：

2.管理虚拟环境

poetry 默认会将虚拟环境统一放在指定目录，即 C:\Users\xxx\AppData\Local\pypoetry\Cache\virtualenvs\。虚拟环境的命名规则为项目名-随机数-python版本。如何将虚拟环境放在当前项目目录中呢？通过命令poetry config --list如下：

PS F:\Python资料\PythonProject\PythonExample> poetry config --list
cache-dir = "C:\\Users\\wangs\\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 = "{cache-dir}\\virtualenvs"  # C:\Users\wangs\AppData\Local\pypoetry\Cache\virtualenvs
virtualenvs.prefer-active-python = false
virtualenvs.prompt = "{project_name}-py{python_version}"
warnings.export = true

将virtualenvs.in-project设置为true即可：

poetry config virtualenvs.in-project true

通过命令poetry add flask试一试：

可以看到当执行 poetry add 指令时，poetry 会自动检查当下是否正在使用虚拟环境，如果没有，那么会自动创建一个新的虚拟环境，然后再安装模块。

进入虚拟环境变量的命令为poetry shell，退出虚拟环境变量的命令为exit。

3.Poetry常用命令 [2]

Poetry常用命令、功能和示例：

命令	功能	示例
`poetry add`	添加依赖到项目	`poetry add requests`
`poetry remove`	从项目中移除依赖	`poetry remove requests`
`poetry export`	导出依赖到其它格式文件	`poetry export -f requirements.txt`
`poetry env use`	指定项目使用的Python解释器	`poetry env use python3.8`
`poetry shell`	启动项目的虚拟环境	`poetry shell`
`poetry show`	显示项目依赖的详细信息	`poetry show requests`
`poetry init`	初始化一个新项目并生成pyproject.toml	`poetry init`
`poetry install`	安装项目依赖	`poetry install`
`poetry new`	创建一个新的Poetry项目	`poetry new my_project`
`poetry build`	打包项目，通常在 `dist` 目录	`poetry build`
`poetry publish`	发布项目到PyPI	`poetry publish --username <your-username> --password <your-password>`

可修改Poetry为清华镜像源：

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

4.pyproject.toml和poetry.lock关系

当使用 poetry add 指令时，poetry 会自动更新 [4]：

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

poetry.lock 实际上相当于 pip 的 requirements.txt 文件，详细记录了所有安装的模块与版本。

（1）pyproject.toml文件

这段代码是一个pyproject.toml文件的内容，用于配置和管理一个Python项目。

[tool.poetry]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = ["wangss <913292836@qq.com>"]
readme = "README.md"[tool.poetry.dependencies]
python = "^3.10"[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

[tool.poetry] 部分包含了与Poetry项目相关的基本信息：

name: 项目的名称，这里是 "poetry-demo"。
version: 项目的版本号，这里是 "0.1.0"。
description: 项目的描述，这里为空字符串。
authors: 项目的作者列表，这里是 ["wangss <913292836@qq.com>"]。
readme: 项目的README文件，这里是 "README.md"。

[tool.poetry.dependencies] 部分定义了项目的依赖：

python: 项目所需的Python版本，这里是 "^3.10"，表示需要Python 3.10版本及其以上的版本。

[build-system] 部分指定了构建系统的信息：

requires: 构建系统所需的包列表，这里是 ["poetry-core"]。
build-backend: 构建后端，这里是 "poetry.core.masonry.api"，表示使用Poetry的核心构建API。

（2）poetry.lock文件

这段代码是一个由Poetry生成的poetry.lock文件的一部分，用于锁定项目的依赖关系版本，确保项目在不同环境中具有一致的依赖。

# This file is automatically @generated by Poetry 1.8.3 and should not be changed by hand.
package = [][metadata]
lock-version = "2.0"
python-versions = "^3.10"
content-hash = "53f2eabc9c26446fbcc00d348c47878e118afc2054778c3c803a0a8028af27d9"

package 部分：通常会列出所有被锁定的依赖包及其版本信息。在这里它是一个空列表，表示当前项目没有额外的依赖或依赖尚未锁定。

package = []

[metadata] 部分：包含了关于锁文件和项目的一些元数据信息：

lock-version: 锁文件的版本，这里是 "2.0"。这表明文件遵循Poetry锁文件的2.0版本规范。
python-versions: 项目所支持的Python版本范围，这里是 "^3.10"，表示需要Python 3.10版本及其以上的版本。
content-hash: 内容哈希值。该哈希值用于验证依赖关系的完整性，确保依赖关系未被篡改。

5.poetry安装whl文件

pip是可以直接安装whl文件的，如何通过poetry安装whl文件呢？Poetry 主要用于管理项目依赖和构建，而不像 pip 那样直接安装 .whl 文件。不过，Poetry 可间接地通过 pyproject.toml 文件指定依赖来安装 .whl 文件。如果已经有一个 .whl 文件，并且希望使用 Poetry 安装它，可以通过以下步骤来实现：

（1）创建或更新 pyproject.toml

在项目的 pyproject.toml 文件中添加对本地 .whl 文件的依赖。假设 .whl 文件路径是 ./dist/poetry_demo-0.1.0-py3-none-any.whl，pyproject.toml 文件可像这样配置：

[tool.poetry]
name = "example-project"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"][tool.poetry.dependencies]
python = "^3.10"
poetry-demo = { path = "./dist/poetry_demo-0.1.0-py3-none-any.whl" }[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

（2）使用 Poetry 安装依赖

在项目目录下运行以下命令来安装依赖，包括本地的 .whl 文件。这样Poetry 会根据 pyproject.toml 文件中的配置来安装依赖，包括本地的 .whl 文件。