python 依赖管理工具之--Poetry 完全指南

以下是一份 Poetry 完全指南，涵盖从安装到高级功能的全面教程，结合最佳实践和实用技巧：

1. 安装 Poetry

系统级安装（推荐）

# Linux/macOS
curl -sSL https://install.python-poetry.org | python3 -

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

验证安装

poetry --version# 输出示例: Poetry (version 1.8.0)

配置中国镜像加速

poetry config repo.pypi.url https://pypi.tuna.tsinghua.edu.cn/simple/

️ 2. 项目管理

创建新项目

poetry new my-project && cd my-project

生成目录结构：

my-project/
├── pyproject.toml# 核心配置文件
├── README.md
├── src/
│└── my_project/
│└── __init__.py
└── tests/
└── test_my_project.py

初始化现有项目

cd existing-project
poetry init# 交互式生成 pyproject.toml

📦 3. 依赖管理

安装依赖

poetry install# 安装所有依赖（含开发依赖）
poetry install --no-dev# 仅生产依赖

添加/移除依赖

# 生产依赖
poetry add requests numpy@^1.24# 指定版本约束

# 开发依赖（测试/文档等）
poetry add --group dev pytest black

# 移除依赖
poetry remove pandas

锁定依赖版本

poetry lock# 生成 poetry.lock 确保版本一致性

🌐 4. 虚拟环境管理

自动创建环境（默认）

poetry env use python3.10# 指定Python版本
poetry shell# 激活虚拟环境

项目内建环境（推荐）

poetry config virtualenvs.in-project true# 创建 .venv 在项目内

常用命令

poetry env info# 查看环境信息
poetry env list# 列出所有环境
poetry env remove 3.10# 删除环境

🔧 5. 依赖分组（高级功能）

分组管理（测试/文档/性能）

# pyproject.toml
[tool.poetry.group.test.dependencies]
pytest = "^7.4"
coverage = "*"

[tool.poetry.group.docs.dependencies]
sphinx = "^7.0"

安装指定组

poetry install --with test,docs# 安装多组依赖
poetry add --group perf pyinstrument# 添加新组

📦 6. 打包与发布

构建包

poetry build# 生成 dist/ 目录下的 .whl 和 .tar.gz

发布到 PyPI

# 配置 API Token
poetry config pypi-token.pypi your-token-here

# 发布
poetry publish

发布到私有仓库

# pyproject.toml
[[tool.poetry.source]]
name = "private"
url = "https://private-repo.example/simple"

poetry publish -r private

️ 7. 进阶配置

脚本别名

# pyproject.toml
[tool.poetry.scripts]
start = "my_project.main:run_app"
bench = "python benchmarks/main.py"

运行：poetry run start

多环境配置

# 条件依赖 (Windows专用)
pathlib2 = { version = "*", markers = "sys_platform == 'win32'" }

源码依赖

[tool.poetry.dependencies]
my-lib = { git = "https://github.com/user/repo.git", branch = "main" }

8. 故障排查

常见问题解决

# 重置环境
poetry env remove --all
poetry cache clear --all pypi
poetry lock --no-cache
poetry install

# 依赖冲突诊断
poetry show --tree
poetry show --latest | grep -v up-to-date

✅ 9. 最佳实践

1. 锁定文件必提交：将 poetry.lock 加入 Git 确保团队版本一致
2. 版本约束规范：
3. ^1.2.3 = 1.x.x (x≥2.3)
4. ~1.2.3 = 1.2.x (x≥3)
5. >=4.5,<5.0

6. CI/CD 集成示例：

7. name: Install Poetry
   run: pipx install poetry
8. name: Install dependencies
   run: poetry install --no-interaction

9. name: Run tests
   run: poetry run pytest

💻 10. 工作流示例

graph LR
A[poetry new] --> B[编写代码]
B --> C[poetry add 依赖]
C --> D[poetry run pytest]
D --> E[poetry build]
E --> F[poetry publish]

🔍 11. 学习资源

1. 官方文档

2. Cheat Sheet：

   # 查看已安装包
   poetry show
   
   # 更新所有依赖
   poetry update
   
   # 导出 requirements.txt
   poetry export -f requirements.txt --output requirements.txt

提示：结合 uv 加速安装：
poetry export -f requirements.txt | uv pip install -r /dev/stdin