Python环境管理器—Poetry入门指南

• 官网：https://python-poetry.org/
• Poetry GitHub：https://github.com/python-poetry/poetry#poetry-dependency-management-for-python

一. 基础知识

1. Poetry是什么？

• Poetry 帮助你定义、管理和安装 Python 项目的依赖，还可以用于项目的打包和发布。

• 简单来说，Poetry 类似pip，能协助你进行套件管理（dependency management），但又比pip 强大得多，因为它还包含了pip 所未有的下列功能：
• 管理第三方模块的安装与卸载
• 管理虚拟环境
• 管理虚拟环境的依赖
• 管理打包与发布。其中最重要的是 虚拟环境的依赖。

2. 名词解释：虚拟环境管理、模块管理、模块依赖管理

3. pip的不足

• pip 是Python 内建的套件管理工具，而它的最大罩门，就是对于「套件间的相依性管理」能力不足。尤其是在「移除」套件时的依赖解析——可以说没有。这也是我提议改用Poetry 的根本原因。

• 怎么说？看完下面的例子就能明白。
• pip uninstall的困境：以Flask 为例
• 假设现在你的工作专案中有开发API 的需求，经过一番研究与讨论，决定使用Flask网页框架来进行开发。
• 我们知道，很多套件都有依赖的套件，也就是使用「别人已经造好的轮子」来构成套件功能的一部分。
• 安装主套件时，这些依赖套件也必须一并安装，主套件才能正常运作，这里的Flask 就是如此。安装Flask 时，不会只安装单一个flask套件，还会安装所有Flask 的必要构成部分——也就是依赖套件，结果如下：

❯ pip install flask 
Collecting flask 
  Downloading Flask-2.1.1-py3-none-any.whl (95 kB) 
     |█████████████████████████ ███████| 95 kB 993 kB/s 
... 
Installing collected packages: zipp, MarkupSafe, Werkzeug, Jinja2, itsdangerous, importlib-metadata, click, flask 
Successfully installed Jinja2-3.1.1 MarkupSafe-2.1.1 Werkzeug-2.1.1 click-8.1.2 flask-2.1.1 importlib-metadata-4.11.3 itsdangerous-2.1.2 zipp-3.7.0

• 从上可知，pip install flask还会一并安装importlib-metadata、itsdangerous等7 个依赖套件，实际上总共安装了8 个套件！

• pip 替代方案选择——Pipenv vs Poetry

二. 从零开始使用Poetry

1. 安装Poetry

• 官网文档：https://python-poetry.org/docs/#installation

2. 初始化Poetry

3. 管理Poetry 虚拟环境

• 虚拟环境的命名模式为 项目名-随机数-python版本
• 更多资讯可参考官方文件：https://python-poetry.org/docs/managing-environments/

4. 修改config，建立专案内.venv虚拟环境

5. 启动与退出虚拟环境

6. Poetry 指令

6.1. Poetry 新增套件

6.2. poetry.lock与更新顺序

6.3. poetry lock：更新poetry.lock

7. 指定套件「版本」范围

7.1. Poetry 的版本管理能力

8. 新增套件至dev-dependencies

• https://python-poetry.org/docs/cli/#add

9. Poetry 更新套件

10. 列出全部套件清单

11. 「树状」显示套件依赖层级

12. Poetry移除套件(remove)

13. 输出requirements.txt

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

• 网友提醒，hash 有其价值，并建议保留，详见留言区

14. 输出dev-dependencies

• poetry export所有参数用法与说明，请参考文件。

15. Poetry 常用指令清单

三. Poetry 常见使用情境与操作QA

1. 新增专案并使用Poetry

2. 现有项目改用Poetry

3. 在别台主机上重现项目的Poetry虚拟环境

4. 我想要移除并重建虚拟环境

5. 为什么我不在Docker 环境中使用Poetry？

6. 我可以使用自己习惯的virtualenv 吗？

7. 修改 poetry 镜像源

• 修改为清华镜像源

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

四. 轻松打包(poetry build)和发布(poetry publish)

• 具体可以参考入门项目：https://github.com/zhangkaifang/vpdbz

1. 打包(poetry build)

• 文档：https://python-poetry.org/docs/cli/#build

2. 发布(poetry publish)

• 文档：https://python-poetry.org/docs/cli/#build

# -----------------------使用账户密码方式
poetry publish --build --username xxx --password xxx
# -----------------------使用token方式
# poetry config pypi-token.pypi xxxx
poetry config pypi-token.pypi pypi-AgEIcHlwaS5vcmcCJDkxNTQ2NzA5LTY4NzMtNDhmNC04ZDczLWM2NGM2ZTI2MWNlNwACKlszLCI0OWRlYjAyZC0xNzM5LTRmNTctOWUyNi1iOTUyOWQzMzM1YWMiXQAABiCr2ay7NyHuJUnJhRPgLeWsJ7nrWE-9V28KDHiOdBK1jA

五. 参考文献

• poetry 入门完全指南
• Python 套件管理器——Poetry 完全入门指南