Poetry基本用法教程 | 读书or跑步，旅行or思考

1.背景

最近在复现一个项目的时候，发现项目的环境安装是使用Poetry，一脸懵逼，不知道Poetry是什么东西，以前也从来没有接触过。于是开始学习Poetry，一番了解下来，决定专门学习掌握一下Poetry这个包依赖管理工具。

1.1 Poetry是什么？

Poetry官网如此写到：

Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution.

简而言之，就是一个python依赖管理工具，具有虚拟环境管理、Package依赖性管理、Package的打包与分布的功能。

1.2 为什么要使用Poetry？相比pip、conda等工具他有什么优势呢？

答：相比pip和conda等虚拟环境包管理工具，Poetry的优点就是其可以管理包之间的依赖的关系，比如我们安装一个包，可能这个包的使用，还需要依赖好几个其他包。pip在安装包的时候，可以将依赖的包一并进行安装，但是当我们安装完之后，我们不需要这个包的时候，我们用pip工具进行uninstall这个包的时候，由于pip无法处理依赖管理，只会uninstall指定的那个包，那么其他的依赖包就需要我们手动进行卸载，但是问题来了，如果其中某些包是好几个其他包共同依赖的包的话，这样就很容易出现依赖问题，处理起来非常棘手。Poetry的目标，就是解决pip在依赖性管理上的不足。

总结: 在我们个人小项目的开发上，如果包比较少，管理起来比较方便的话，pip其实可以满足我们的需求，但是如果是大型项目，管理起来依赖就非常麻烦，如果有一些不必要的包保留下来，还会影响我们部署，浪费资源，因此使用Poetry来进行包管理工具是一件很有必要的事情。

2.Poetry的安装

建议大家还是主要参考官网的教程Poetry官网、
我在ubuntu上安装的时候使用的官网推荐的official installer安装方式，并非使用pipx的安装方式，因为中科大镜像源最新版本就是2.1.3的原因，因此我安装了2.1.3,可根据自身情况指定版本号。

1	curl -sSL https://install.python-poetry.org \| python3 - --version 2.1.3

安装完成后执行：(需要先设置环境变量)

1	Poetry --version

返回版本号之后就说明安装成功。

2.1 设定PATH环境变量

在linux上，设置PATH相对简单，在.bashrc 或 .zshrc后边追加：

1 2	echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc

windows上同样也需要设置环境变量，可以参考官网教程。

3.使用Poetry生成虚拟环境

3.1 从0开始创建项目

3.1.1.初始化项目

1	poetry init #生成poetry.toml文件

或者

1	poetry new demo-name # 创建一个完整的Poetry管理的包结构

3.1.2.建立项目虚拟环境并使用

1	poetry env use python

注：该命令建立的虚拟环境所使用的python版本，取决于python指令在PATH中的连接的版本。

修改config .建立项目内.venv虚拟环境
查看poetry的设置类型

1	poetry config --list

修改为项目内建立的虚拟环境

1	poetry config virtualenvs.in-project true

3.1.3.激活poetry环境

1	poetry env activate

3.1.4.添加包

poetry add package-name 
-D参数指定开发环境
# 或
poetry add package-name --dev

3.1.5.删除包

poetry remove package-name
-D参数指定开发环境

# 删除虚拟环境命令
poetry env remove python

3.1.5 更新包

更新全部可能可以更新的包,但是更新包收到poetry.toml中包的版本限制。

1	poetrty update

更新指定包

1	poetry update package-name

Note(Important☆)

如果手动修改了Poetry.toml文件，需要执行以下命令，使修改生效。

1 2	poetry lock # 将toml文件改动同步到lock文件中 poetry install # 根据lock文件改动，拉取相关依赖到环境中

3.2 在其他主机复现Poetry虚拟环境

1.git clone 项目。
2.此时项目中存在Poetry.toml 和 Poetry.lock文件。
3.poetry env use python 建立虚拟环境并使用。
4.执行poetry install,会根据poetry.lock记录的包版本安装到虚拟环境中。
*激活poetry环境命令为：poetry env activate

3.3 如何在原项目基础上重建环境

删除.venv文件后，直接执行’poetry env use python’,但是这个应该用的会很少

4.常用命令（使用export插件导出requirement.txt方法）

一、poetry shell插件
from poetry2.0起，shell命令不再是默认安装的了。
poetry shell插件安装查看: https://github.com/python-poetry/poetry-plugin-shell


二、基本常用命令作用
1.env activate: Print the command to activate a virtual environment.
2.env info: Displays information about the current environment.
3.env list: Lists all virtualenvs associated with the current project.
4.env remove: Remove virtual environments associated with the project.
5.env use: Activates or creates a new virtualenv for the current project.


1.更新命令 
poetry lock 
依据 poetry.toml 来更新 poetry.lock
但是仅仅会更新poetry.lock，而不会安装相关依赖

2.根据poetry.lock安装相关依赖包
poetry install

3.Poetry更新套件(一般不使用)
poetry update: 更新全部套件
poetry update requests toml 更新指定的某个套件

4.poetry show
展示环境包内容，环境不是来自虚拟环境，而是根据poetry.lock文件来展示的。

5.poetry show --tree(包之间的依赖关系与层次，一目了然)
展示环境依赖树状结构

6.移除命令
poetry remove package-name

7.退出poetry环境
exit


三、export插件导出requirements.txt文件
**输出requirements.txt(2.0版本以后)**
poetry export -f requirements.txt -o requirements.txt --without-hashes
export插件地址：https://github.com/python-poetry/poetry-plugin-export
使用方法：
在Poetry2.0及以上版本，直接在poetry.toml中声明如下：
[tool.poetry.requires-plugins]
poetry-plugin-export = ">=1.8"

或者 

poetry self add poetry-plugin-export(未尝试)

总结

花了半天时间吧，基本掌握了poetry工具的使用，总体来说还是很方便的，但是学习起来相比pip等工具还是有一定的门槛，不过比起这个，可以解决掉环境包依赖的问题，还是很好，有利于项目的复现！

使用场景QA

1、新建项目

1.poetry init
2.poetry env use python
3.poetry shell # 如未执行步骤2，则会自动建立相应的虚拟环境
4.poetry add package-name
5.poetry remove package-name

2、现有项目改用Poetry进行管理

最好的办法还是重新使用poetry进行管理，避免不必要的麻烦

3、在其他开发环境上复现 Poetry虚拟环境

1.git clone 项目
2.项目中存在Poetry.toml 和 Poetry.lock文件
3.poetry env use python 建立虚拟环境并使用。 # 该命令仅仅是为当前项目选择或创建虚拟环境
4.执行poetry install,会根据poetry.lock记录的包版本安装到虚拟环境中

4、在原项目基础上重建环境

删除.venv文件后，直接执行’poetry env use python’或’poetry shell’建立一个新的即可。