poetry的安装与使用

poetry的安装与使用

---

相关网址

官网：https://python-poetry.org/

github: https://github.com/python-poetry/poetry

参考blog：https://blog.kyomind.tw/python-poetry/

介绍

官网自我介绍：PYTHON PACKAGING AND DEPENDENCY MANAGEMENT MADE EASY

大概的意思是：让python的打包和依赖管理更容易

简单的来说，poetry类似于pip可以进行包管理，但是又比pip强大的多，它还包含以下功能：

虚拟环境管理

包的依赖管理

代码的打包与发布

本文介绍版本为：Poetry (version 1.5.1)

pip的不足

pip在我们第一次接触python就使用到了，但是一些功能的不完善，导致了其他包管理的出现。

pip uninstall 的困境，以Flask为例：

在我们使用pip install flask时，因为flask内部依赖于其他包，如Werkzeug、Jinja2、click等，所以安装的时候pip会连同这些依赖一同安装（这很方便），但是在我们不需要flask的时候，我们需要使用pip uninstall flask从环境中把flask移除时，pip并不会帮助我们把这些依赖包一同移除，而只会移除flask自己本身。

(安装flask)

(卸载flask)

这时候我们就需要自己一步步去卸载flask所依赖的包，但更多的时候，我们并不清楚flask依赖的包有哪些，所以，当我们卸载包的时候就变得很难受。

 

这个时候，poetry出现了，poetry拥有包的依赖性管理功能，我们可以很方便的查看包与包之间的依赖关系，在我们使用poetry移除包的时候，它会自己帮助我们处理包的依赖关系，并一同卸载。

安装

安装方式有两种，一是使用官方提供的脚本安装，二是使用pip安装。

使用官方提供脚本安装

官方话术：We provide a custom installer that will install Poetry in a new virtual environment to isolate it

from the rest of your system. This ensures that dependencies will not be accidentally upgraded or

uninstalled, and allows Poetry to manage its own environment.

意思就是：他们提供了一个安装程序，会在一个新的虚拟环境中安装poetry，以确保poetry的依赖不会被错误的

升级或者删除。

Liunx/MacOS/WSL:

?

1	$ curl -sSL https://install.python-poetry.org | python3 -

Windows:

?

1	$ (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

默认安装目录：

• ~/Library/Application Support/pypoetry on MacOS.
• ~/.local/share/pypoetry on Linux/Unix.
• %APPDATA%\pypoetry on Windows.

也可以使用POETRY_HOME环境变量设置安装目录

?

1	$ curl -sSL https://install.python-poetry.org | POETRY_HOME=/etc/poetry python3 -

• 设置POETRY_HOME后的安装位置为$POETRY_HOME/venv/bin/poetry

设置$PATH环境变量以便更方便的使用poetry

poetry安装的时候，自动帮我们在以下目录创建了软连接，可以将以下目录添加到$PATH中：

• $HOME/.local/bin on Unix.
• %APPDATA%\Python\Scripts on Windows.
• $POETRY_HOME/bin if $POETRY_HOME was set.

或者直接将安装目录的绝对路径添加到$PATH中：

• ~/Library/Application Support/pypoetry/venv/bin/poetry on MacOS.
• ~/.local/share/pypoetry/venv/bin/poetry on Linux/Unix.
• %APPDATA%\pypoetry\venv\Scripts\poetry on Windows.
• $POETRY_HOME/venv/bin/poetry if $POETRY_HOME was set.

使用pip安装

在需要使用的虚拟环境中执行

?

1	$ pip install poetry

卸载

使用脚本安装方式

?

1	$ curl -sSL https://install.python-poetry.org | python3 - --uninstall $ curl -sSL https://install.python-poetry.org | POETRY_UNINSTALL=1 python3 -

使用pip安装方式

?

1	$ pip uninstall poetry

然后再依次卸载依赖包

更新

使用脚本安装方式

# 更新到最新的稳定版
$ poetry self update
# 更新到preview版本
$ poetry self update --preview
# 更新到指定版本
$ poetry self update 1.2.0

使用pip安装方式

$ pip install --upgrade poetry

初次使用

初始化项目

使用poetry new 初始化一个项目

$ poetry new poetry-demo

这将会创建一个名为poetry-demo的目录，目录结构如下

poetry-demo
├── pyproject.toml
├── README.md
├── poetry_demo
│   └── __init__.py
└── tests
    └── __init__.py

已创建的项目改用poetry

类似于git init，poetry也有一个init的命令.

首先建立一个文件夹

$ mkdir poetry_demo
$ cd poetry_demo

执行poe init

$ poe init

会出现一系列选项，可以根据自己的需要修改或使用默认：

Package name [test]:                        # 打包的名字
Version [0.1.0]:                            # 版本
Description []:                             # 描述
Author [test test@163.com, n to skip]:      # 作者信息
License []:                                 # license
Compatible Python versions [^3.10]:         # 兼容的python版本
# 定义依赖，不会安装，只在生成的pyproject.toml中记录，可以选no跳过
Would you like to define your main dependencies interactively? (yes/no) [yes]
　　Package to add or search for (leave blank to skip):        　　　　　　　　　　　　　　　　　　# 要安装的依赖名
　　　　Enter package # to add, or the complete package name if it is not listed []:　　　　　　# 从搜寻到的依赖中选择你要安装的
　　　　Enter the version constraint to require (or leave blank to use the latest version):　　# 依赖版本
　　Add a package (leave blank to skip):　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　# 重复上面搜索步骤
Would you like to define your development dependencies interactively? (yes/no) [yes]　　　　　# 开发环境的依赖，如pytest等
Do you confirm generation? (yes/no) [yes]        　　　　　　　　　　　　　　　　　　　　　　　　　　# 确认生成的pyproject.toml

此时目录结构如下：

poetry-demo
└── pyproject.toml

poetry对于虚拟环境的管理

poetry强制要求所有依赖都安装在虚拟环境中，以避免污染全局环境.

所以在我们执行poetry add 或者poe install 等命令时，它都会先去检查当下是否有虚拟环境：

• 是，则使用当前虚拟环境
• 否，则新建立虚拟环境并使用

使用poetry建立虚拟环境

当然你也可以使用原有的工具进行虚拟环境的管理，如venv, virtualenv或conda等

首先可以修改配置将虚拟环境建立到当前项目文件夹

$ poetry config virtualenvs.in-project true

如果不修改的话，poetry默认会将虚拟环境统一建立在cache-dir的virtualenvs目录下，默认命名方式为{project_name}-py{python_version}.

建立虚拟环境

$ poetry env use python3 Creating virtualenv test in /Users/wender/test/.venv Using virtualenv: /Users/wender/test/.venv

启动与退出虚拟环境

启动

$ poetry shell

退出

$ exit

poetry常用命令

poetry source add

添加pypi源

$ poetry source add --priority=supplemental DataGrand https://repo.datagrand.com/repository/pypi/simple

• --priority: Set the priority of this source. Accepted values are: default, secondary, supplemental, and explicit. （设置该源的优先级。接受的值有:默认值、次要值、补充值和显式值。）

poetry install

安装环境，根据pyprojecy.toml中配置的依赖，进行环境的安装，类似于pip install -r requirements.txt

$ poetry install
Updating dependencies
Resolving dependencies... (2.3s)

Package operations: 7 installs, 0 updates, 0 removals

  • Installing markupsafe (2.1.3)
  • Installing blinker (1.6.2)
  • Installing click (8.1.6)
  • Installing itsdangerous (2.1.2)
  • Installing jinja2 (3.1.2)
  • Installing werkzeug (2.3.6)
  • Installing flask (2.3.2)

Writing lock file

poetry add <package_name>

安装依赖，类似于pip install

$ poetry add black
Using version ^2.31.0 for requests

Updating dependencies
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/70/8e/0e2d847013cb52cd35b38c009bb167a1a26b2ce6cd6965bf26b47bc0bf44/requests-2.31.0-py3-none-any.whl#sha256=58cd2187c01e70e6e26
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/70/8e/0e2d847013cb52cd35b38c009bb167a1a26b2ce6cd6965bf26b47bc0bf44/requests-2.31.0-py3-none-any.whl#sha256=58cd2187c01e70e6e26
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/fc/34/3030de6f1370931b9dbb4dad48f6ab1015ab1d32447850b9fc94e60097be/idna-3.4-py3-none-any.whl#sha256=90b77e79eaa3eba6de819a0c44
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/bf/a0/188f223c7d8b924fb9b554b9d27e0e7506fd5bf9cfb6dbacb2dfd5832b53/charset_normalizer-3.2.0-py3-none-any.whl#sha256=8e098148dd
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/4c/dd/2234eab22353ffc7d94e8d13177aaa050113286e93e7b40eae01fbf7c3d9/certifi-2023.7.22-py3-none-any.whl#sha256=92d6037539857d820
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/4c/dd/2234eab22353ffc7d94e8d13177aaa050113286e93e7b40eae01fbf7c3d9/certifi-2023.7.22-py3-none-any.whl#sha256=92d6037539857d820
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/4c/dd/2234eab22353ffc7d94e8d13177aaa050113286e93e7b40eae01fbf7c3d9/certifi-2023.7.22-py3-none-any.whl#sha256=92d6037539857d820
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/4c/dd/2234eab22353ffc7d94e8d13177aaa050113286e93e7b40eae01fbf7c3d9/certifi-2023.7.22-py3-none-any.whl#sha256=92d6037539857d820
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/9b/81/62fd61001fa4b9d0df6e31d47ff49cfa9de4af03adecf339c7bc30656b37/urllib3-2.0.4-py3-none-any.whl#sha256=de7df1803967d2c2a98e4
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/9b/81/62fd61001fa4b9d0df6e31d47ff49cfa9de4af03adecf339c7bc30656b37/urllib3-2.0.4-py3-none-any.whl#sha256=de7df1803967d2c2a98e4
Resolving dependencies... (2.2s)

Package operations: 5 installs, 0 updates, 0 removals

  • Installing certifi (2023.7.22)
  • Installing charset-normalizer (3.2.0)
  • Installing idna (3.4)
  • Installing urllib3 (2.0.4)
  • Installing requests (2.31.0)

Writing lock file

此时项目中的pyproject.toml和poetry.lock也发生了变化

# pyproject.toml
...

[tool.poetry.dependencies]
python = "^3.10"
Flask = "^2.3.2"
black = "^23.7.0"
requests = "^2.31.0"

...

pyproject.toml中只会记录安装的依赖及其版本，而不会记录依赖的依赖.

# poetry.lock
...

[[package]]
name = "requests"
version = "2.31.0"
description = "Python HTTP for Humans."
optional = false
python-versions = ">=3.7"
files = [
    {file = "requests-2.31.0-py3-none-any.whl", hash = "sha256:58cd2187c01e70e6e26505bca751777aa9f2ee0b7f4300988b709f44e013003f"},
    {file = "requests-2.31.0.tar.gz", hash = "sha256:942c5a758f98d790eaed1a29cb6eefc7ffb0d1cf7af05c3d2791656dbd6ad1e1"},
]

[package.dependencies]
certifi = ">=2017.4.17"
charset-normalizer = ">=2,<4"
idna = ">=2.5,<4"
urllib3 = ">=1.21.1,<3"

[package.extras]
socks = ["PySocks (>=1.5.6,!=1.5.7)"]
use-chardet-on-py3 = ["chardet (>=3.0.2,<6)"]

[package.source]
type = "legacy"
url = "http://mirrors.aliyun.com/pypi/simple"
reference = "pip"

[[package]]
name = "urllib3"
version = "2.0.4"
description = "HTTP library with thread-safe connection pooling, file post, and more."
optional = false
python-versions = ">=3.7"
files = [
    {file = "urllib3-2.0.4-py3-none-any.whl", hash = "sha256:de7df1803967d2c2a98e4b11bb7d6bd9210474c46e8a0401514e3a42a75ebde4"},
    {file = "urllib3-2.0.4.tar.gz", hash = "sha256:8d22f86aae8ef5e410d4f539fde9ce6b2113a001bb4d189e0aed70642d602b11"},
]

[package.extras]
brotli = ["brotli (>=1.0.9)", "brotlicffi (>=0.8.0)"]
secure = ["certifi", "cryptography (>=1.9)", "idna (>=2.0.0)", "pyopenssl (>=17.1.0)", "urllib3-secure-extra"]
socks = ["pysocks (>=1.5.6,!=1.5.7,<2.0)"]
zstd = ["zstandard (>=0.18.0)"]

[package.source]
type = "legacy"
url = "http://mirrors.aliyun.com/pypi/simple"
reference = "pip"

...

poerty.lock中会记录安装的所有依赖信息，包括依赖的依赖及其之间的依赖关系。关于poetry.lock文件的介绍，详见：poetry.lock介绍 部分

为开发环境安装依赖

有些依赖，我们只需要在开发的时候使用，如pytest，black等。poetry允许你区分两者，将依赖安装至dev-dependencies区块。

$ poetry add pytest -D
# 或者使用官方更推荐的方式
$ poetry add pytest -G dev

Using version ^7.4.0 for pytest

Updating dependencies
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/33/b2/741130cbcf2bbfa852ed95a60dc311c9e232c7ed25bac3d9b8880a8df4ae/pytest-7.4.0-py3-none-any.whl#sha256=78bf16451a2eb8c7a2ea98
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/33/b2/741130cbcf2bbfa852ed95a60dc311c9e232c7ed25bac3d9b8880a8df4ae/pytest-7.4.0-py3-none-any.whl#sha256=78bf16451a2eb8c7a2ea98
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/33/b2/741130cbcf2bbfa852ed95a60dc311c9e232c7ed25bac3d9b8880a8df4ae/pytest-7.4.0-py3-none-any.whl#sha256=78bf16451a2eb8c7a2ea98
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/33/b2/741130cbcf2bbfa852ed95a60dc311c9e232c7ed25bac3d9b8880a8df4ae/pytest-7.4.0-py3-none-any.whl#sha256=78bf16451a2eb8c7a2ea98
Resolving dependencies... Downloading http://mirrors.aliyun.com/pypi/packages/33/b2/741130cbcf2bbfa852ed95a60dc311c9e232c7ed25bac3d9b8880a8df4ae/pytest-7.4.0-py3-none-any.whl#sha256=78bf16451a2eb8c7a2ea98
Resolving dependencies... (1.1s)

Package operations: 4 installs, 0 updates, 0 removals

  • Installing exceptiongroup (1.1.2)
  • Installing iniconfig (2.0.0)
  • Installing pluggy (1.2.0)
  • Installing pytest (7.4.0)

Writing lock file

这个时候pyproject.toml和poetry.lock也发生了变化

# pyproject.toml
...

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"

...

poetry update

更新依赖，相当于pip install --upgrade <package_name>

$ poetry update                        # 更新所有能更新的依赖
$ poetry update <package_nmae>         # 更新指定的依赖

poetry remove

卸载依赖，类似于pip uninstall <package_name>，不同的是会一同卸载依赖的依赖

$ poetry remove black

Updating dependencies
Resolving dependencies... (0.1s)

Package operations: 0 installs, 0 updates, 3 removals

  • Removing black (23.7.0)
  • Removing mypy-extensions (1.0.0)
  • Removing pathspec (0.11.2)

Writing lock file

poetry show

查看当前的依赖项，类似于pip list，但功能更加强大，且不是根据环境中的依赖进行输出，而是通过pyproject.toml和poetry.lock进行校验和输出.

$ poetry show

blinker            1.6.2     Fast, simple object-to-object and broadcast signaling
certifi            2023.7.22 Python package for providing Mozilla's CA Bundle.
charset-normalizer 3.2.0     The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet.
click              8.1.6     Composable command line interface toolkit
flask              2.3.2     A simple framework for building complex web applications.
idna               3.4       Internationalized Domain Names in Applications (IDNA)
importlib-metadata 6.8.0     Read metadata from Python packages
itsdangerous       2.1.2     Safely pass data to untrusted environments and back.
jinja2             3.1.2     A very fast and expressive template engine.
markupsafe         2.1.3     Safely add untrusted strings to HTML/XML markup.
platformdirs       3.10.0    A small Python package for determining appropriate platform-specific dirs, e.g. a "user data dir".
requests           2.31.0    Python HTTP for Humans.
tomli              2.0.1     A lil' TOML parser
urllib3            2.0.4     HTTP library with thread-safe connection pooling, file post, and more.
werkzeug           2.3.6     The comprehensive WSGI web application library.
yapf               0.40.1    A formatter for Python code.
zipp               3.16.2    Backport of pathlib-compatible object wrapper for zip files

也可以查看具体某个依赖的信息，可以查看到依赖的版本及依赖依赖的依赖信息等。

 $ poetry show yapf
 
 name         : yapf
 version      : 0.40.1
 description  : A formatter for Python code.

dependencies
 - importlib-metadata >=6.6.0
 - platformdirs >=3.5.1
 - tomli >=2.0.1

亦或者呈树形展示依赖之间的关系

$ poetry show --tree

flask 2.3.2 A simple framework for building complex web applications.
├── blinker >=1.6.2
├── click >=8.1.3
│   └── colorama *
├── itsdangerous >=2.1.2
├── jinja2 >=3.1.2
│   └── markupsafe >=2.0
└── werkzeug >=2.3.3
    └── markupsafe >=2.1.1
requests 2.31.0 Python HTTP for Humans.
├── certifi >=2017.4.17
├── charset-normalizer >=2,<4
├── idna >=2.5,<4
└── urllib3 >=1.21.1,<3
yapf 0.40.1 A formatter for Python code.
├── importlib-metadata >=6.6.0
│   └── zipp >=0.5
├── platformdirs >=3.5.1
└── tomli >=2.0.1

poetry config

展示或修改poetry的配置项

$ poetry config --list

cache-dir = "/Users/wender/Library/Caches/pypoetry"
experimental.system-git-client = false
installer.max-workers = null
installer.modern-installation = true
installer.no-binary = null
installer.parallel = true
repositories.DataGrand.url = "https://repo.datagrand.com/repository/pypi/simple"
repositories.pip.url = "http://mirrors.aliyun.com/pypi/simple/"
virtualenvs.create = true
virtualenvs.in-project = true
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"  # /Users/wender/Library/Caches/pypoetry/virtualenvs
virtualenvs.prefer-active-python = false
virtualenvs.prompt = "{project_name}-py{python_version}"

修改配置项

$ poetry config virtualenvs.in-project true

poetry lock

根据pyproject.toml刷新并锁定poetry.lock文件，当我们不小心修改了poetry.lock或者手动更新了pyproject.toml中依赖的版本，就需要执行此命令进行更新

如：我在pyproject.toml中添加了如下内容

[tool.poetry.group.log.dependencies]
loguru = "^0.7.0"

此时执行 poetry install 失败

$ poe install
Installing dependencies from lock file
Warning: poetry.lock is not consistent with pyproject.toml. You may be getting improper dependencies. Run `poetry lock [--no-update]` to fix it.

Because test depends on loguru (^0.7.0) which doesn't match any versions, version solving failed.

需要先执行 poetry lock 更新修复poetry.lock

$ poetry lock
Updating dependencies
Resolving dependencies... (0.3s)

Writing lock file

再执行poetry install ，成功

$ poetry install
Installing dependencies from lock file

Package operations: 1 install, 0 updates, 0 removals

  • Installing loguru (0.7.0)

poetry export

导出为其他格式的文件，默认只会导出 [tool.poetry.dependencies] 中的内容，可以使用 --with 添加需要一同导出的组，

$ poetry export -f requirements.txt --output requirements.txt --with dev --with log

--format (-f): 导出的格式，目前只支持requirements.txt 和constraints.txt 两种格式

其他命令

其他不常用的命令请参考官方文档：https://python-poetry.org/docs/cli/

poetry.lock介绍

poetry.lock相当于pip的requirements.txt，详细的记录了已安装的依赖信息

当使用poetry add <package_name>安装依赖的时候，poetry会自动帮我们更新pyproject.toml和poetry.lock文件，

当我们单独修改了某一方，导致两个文件不匹配的时候，就需要我们自己去同步两个文件，执行poetry lock 会同步两个文件，并更新poetry.lock，

更新完成后需要执行poetry install 来将更改同步到环境。