Poetry 是一款现代化的 Python 依赖管理和打包工具。它通过一个 pyproject.toml文件来统一管理你的项目依赖、配置和元数据，并用一个 poetry.lock文件来锁定所有依赖的精确版本，确保项目在任何环境下都能完全一致地复现。

Poetry 的核心优势

Poetry 的强大之处在于它用两个文件清晰地区分了依赖的声明和锁定：

• pyproject.toml：这是你手动定义项目元数据和所需依赖及其版本范围的地方。它代表了你的项目“需要什么”。
• poetry.lock：这个文件由 Poetry 自动生成和管理。它记录了当前环境下所有依赖包（包括次级依赖）的精确版本信息及其哈希值。它确保了在不同机器或环境中安装的依赖版本完全一致，从而实现确定性构建。

Poetry对比pipenv

相信通过前面的描述，大家觉得poetry和pipenv非常相似，在包管理和虚拟环境管理功能上的确如此，但是poetry还拥有更多的新特性相较于pipenv。

• poetry功能更加全面：一体化的依赖管理和打包工具，涵盖项目创建、依赖管理、虚拟环境、打包发布
• poetry更加高效：公认的依赖解析算法更强大、更快，能高效处理复杂的依赖关系
• poetry原生支持打包：通过 poetry build和 poetry publish命令可以轻松打包和发布项目到 PyPI
• poetry更现代化：命令相对更多，虽然学习曲线稍陡，但功能全面，适合新项目使用

基本使用流程

1. 安装 Poetry：

# 推荐使用官方安装脚本 
curl -sSL <https://install.python-poetry.org> | python3 -

安装后，通过 poetry --version验证。

2. 创建新项目：

poetry new my-project cd my-project

这会创建一个标准化的项目结构，包含 pyproject.toml文件。

3. 为现有项目初始化：

如果你的项目已有代码，在其根目录下运行：

poetry init

这会交互式地引导你创建 pyproject.toml文件。

4. 添加依赖：

poetry add requests   # 添加生产依赖 
poetry add --group dev pytest    # 添加开发依赖（如测试框架）

5. 安装所有依赖并创建锁文件：

poetry install

此命令会读取 pyproject.toml，安装所有依赖，并生成/更新 poetry.lock文件。如果只想安装生产依赖，可使用 poetry install --only main。

6. 在虚拟环境中运行代码：

你可以激活虚拟环境并在其中工作：

# 激活虚拟环境 
poetry shell 

# 使用虚拟环境运行代码 
python main.py 

# 退出虚拟环境 
exit

7. 也可以不激活环境，直接用 run命令执行：

poetry run python main.py

pyproject.toml文件

一个典型的 pyproject.toml文件结构如下：

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
authors = ["Your Name <you@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
# 生产依赖
python = "^3.8"
requests = "^2.28.1"
django = { version = "^4.1.2", optional = true }

[tool.poetry.group.dev.dependencies]
# 开发依赖
pytest = "^7.2.0"
black = "^22.10.0"

[tool.poetry.extras]
# 可选依赖组
full = ["django"]

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

实用技巧与注意事项

• 依赖版本约束：Poetry 使用语义化版本控制。^1.2.3表示允许安装 1.2.3及以上、但低于 2.0.0的版本。~1.2.3则表示允许 1.2.3及以上、但低于 1.3.0的版本。
• 使用国内镜像源加速：在国内环境下，为 Poetry 配置国内镜像源（如清华源、阿里云源）可以显著加快下载速度。你可以在 pyproject.toml中配置源：

[[tool.poetry.source]] 
name = "tsinghua" 
url = "<https://pypi.tuna.tsinghua.edu.cn/simple/>" 
priority = "primary"

• 依赖组：Poetry 支持将依赖分组，例如 dev, test, docs。你可以使用 poetry install --with test, docs来安装特定组的依赖。

常见问题处理

• 虚拟环境问题：如果虚拟环境损坏或需要彻底重建，可以删除后重新安装：

# 删除虚拟环境 
poetry env remove <Python版本路径或环境名> 
  
  # 重新创建虚拟环境并安装依赖 
  poetry install

• 从 requirements.txt 迁移：如果你有一个现有的 requirements.txt文件。

不建议手动编辑 pyproject.toml文件，使用 Poetry 命令添加依赖能让它自动解析合适的版本并处理依赖关系。

方法一：批量迁移（如果 requirements.txt 格式规整）。

你可以使用一条命令尝试安装 requirements.txt中的所有包：

poetry add $(cat requirements.txt)

这条命令会读取 requirements.txt中的每一行并执行 poetry add。

但注意，此方法可能不适用于所有情况，特别是当 requirements.txt中包含注释（#）、索引源（-i）、额外选项或非标准格式时，可能会报错。

方法二：逐行手动迁移（推荐，更可控）

更稳妥的方法是**逐个添加你的主要依赖，**Poetry 会自动处理这些主要依赖所附带的其他依赖。

poetry add requests django pandas

对于需要特定版本的包，可以这样指定其版本：

poetry add "flask==2.2.3" "numpy>=1.21.0"