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 文件。

poetry install

参考文献

[1] Poetry官方文档：https://python-poetry.org/docs/

[2] Poetry的帮助文档：https://github.com/GeekFong/how_to_use_poetry/blob/main/How_To_Use_Poetry/Poetry的帮助文档

[3] https://github.com/python-poetry/poetry

[4] poetry 入门完全指南：https://notes.zhengxinonly.com/environment/use-poetry.html

[5] https://pypi.org/

NLP工程化(星球号)