Python 包管理利器 -Poetry

一、简介

Poetry 是一个Python 中的好用的包管理工具。在 Python 中，打包系统和依赖管理非常复杂：一个项目经常要同时创建多个文件，例如：

• setup.py
• requirements.txt
• setup.cfg
• MANIFEST.in
• Pipfile

基于此， poetry 将所有的配置都放置在一个 toml 文件中，包括：依赖管理、构建、打包、发布等，可谓是简单方便。

二、安装

Poetry 要求 Python 版本为 2.7 或者 3.5+。Poetry 官方提供了一个脚本，可以快速方便地进行安装。

osx / linux / bashonwindows 安装：

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py | python -

windows powershell 安装：

(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -UseBasicParsing).Content | python -

Poetry 会被安装在系统中的如下位置：

• $HOME/.local/bin Unix系统
• %APPDATA%\Python\Scripts Windows系统

然后把路径添加到系统变量 PATH 中，即可使用 poetry 命令调用：

poetry --version

卸载：

python install-poetry.py --uninstall
POETRY_UNINSTALL=1 python install-poetry.py

如果你想要改变安装的默认路径，可以设置 POETRY_HOME ：

POETRY_HOME=/etc/poetry python install-poetry.py

除了官方的安装脚本，也可以使用 pipx 或者 pip 进行安装：

pipx install poetry
pipx upgrade poetry
pipx uninstall poetry
pip install --user poetry

更新：

poetry self update

三、基础使用

在已有项目中执行：

poetry init

该命令创建了一个pyproject.toml 文件。你可以手动修改 pyproject.toml 文件添加依赖，然后运行：

poetry install

也可以执行 add 命令安装具体某个模块并自动添加到 pyproject.toml：

$ poetry add xxxx

默认情况下，poetry会在 {cache-dir}/virtualenvs 下创建虚拟环境，你也可以手动修改该配置项，或者在 pyproject.toml 配置[virtualenvs.in-project] 在你的项目目录中创建虚拟环境。

你可以使用 run 命令在虚拟环境中运行脚本：

poetry run python your_script.py

或者直接激活你的虚拟环境，新建一个 shell 运行：

poetry shell

只安装dependencies ：

poetry install --no-root

更新所有锁定版本的依赖：

poetry update

四、命令选项

全局选项：

• --verbose (-v|vv|vvv): "-v" 正常输出, "-vv" 详细输出 "-vvv" debug

• --help (-h) : 帮助信息

• --quiet (-q) : 不输出任何信息

• --ansi: 强制 ANSI 输出

• --no-ansi: 禁止ANSI 输出

• --version (-V): 显示版本

• --no-interaction (-n): 禁止交互询问

NEW：

poetry new my-package

创建项目模板，项目结构如下所示：

my-package
├── pyproject.toml
├── README.md
├── my_package
│   └── __init__.py
└── tests
    └── __init__.py

init: 创建pyproject.toml文件 。

install：读取pyproject.toml并安装依赖，它具有如下这些选项：

• --without: 忽略依赖

• --with: 安装可选的依赖

• --only: 只安装指定的依赖

• --default: 只安装默认的依赖

• --sync: 同步锁定的版本至环境中

• --no-root: 不安装根依赖包

• --dry-run: 输出操作但不执行

• --extras (-E): 安装额外的包

update：升级包

poetry update

不指定任何包时，更新所有，也可以指定升级包：

poetry update requests toml

它具有如下选项：

• --dry-run : 输出操作但不执行

• --no-dev : 不按照开发依赖

• --lock : 只更新锁定不安装

add： 添加依赖并安装

限制范围：

poetry add pendulum@^2.0.5
poetry add "pendulum>=2.0.5"

它具有如下选项：

• --group (-D): 分组

• --editable (-e): 添加到编辑模式

• --extras (-E): 添加额外的依赖

• --optional: 添加至可选依赖

• --python: 指定python版本

• --platform: 指定操作系统

• --source: 使用源名称安装

• ---allow-prereleases: 接受 prereleases 安装

• --dry-run: 输出操作但不执行

• --lock: 只更新锁定不安装

**remove：**移除依赖

它具有如下选项：

• --group (-D): 分组

• --dry-run : 输出操作但不执行

**show：**列出所有的可安装的包

如果你想看具体某个包的信息：

poetry show pendulum

name        : pendulum
version     : 1.4.2
description : Python datetimes made easy

dependencies:
 - python-dateutil >=2.6.1
 - tzlocal >=1.4
 - pytzdata >=2017.2.2

它具有如下这些选项：

• --without: 忽略依赖

• --with: 同时显示

• --only: 只显示指定的依赖

• --default: 只显示默认的

• --no-dev: 不显示开发的依赖

• --tree: 以树状形式显示

• --latest (-l): 展示最新的版本

• --outdated (-o): 显示最新版本，但仅适用于过时的软件包

build：构建

publish：发布

**config：**配置项

使用方法：

poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]

它具有如下选项：

• --unset: 删除配置项

• --list: 展示现在的配置

**run：**在虚拟环境中执行命令

shell：激活虚拟环境

check：检查pyproject.toml文件

search：搜索远程包

**lock：**锁定版本

version：显示版本

**export：**导出锁定的文件为其他的格式

poetry export -f requirements.txt --output requirements.txt

它具有如下选项：

• --format (-f): 转换的格式，暂时只支持requirements.txt

• --output (-o): 输出文件名字

• --dev: 包括开发的依赖

• --extras (-E): 额外的依赖

• --without-hashes: 忽略哈希

• --with-credentials: 包括合格证书

env：与虚拟环境进行交互

**cache：**缓存

显示缓存列表：

poetry cache list

清除缓存：

poetry cache clear pypi --all

**plugin：**插件

安装插件：

poetry plugin add poetry-plugin

显示插件列表：

poetry plugin show

移除插件：

poetry plugin remove poetry-plugin

source： 仓库源

添加源：

poetry source add pypi-test https://test.pypi.org/simple/

显示仓库源列表：

poetry source show

移除：

poetry source remove pypi-test

五、配置

你可以运行config命令进行配置，或者直接修改config.toml文件，这个文件通常位于：

• macOS: ~/Library/Application Support/pypoetry
• Windows: C:\Users\<username>\AppData\Roaming\pypoetry
• Unix~/.config/pypoetry

可以使用--local命令对具体项目进行配置：

poetry config virtualenvs.create false --local 

配置项：

• cache-dir缓存目录

• installer.parallel并行安装

• virtualenvs.create如果不存在，则新建一个虚拟环境

• virtualenvs.in-project在项目根目录创建虚拟环境

• virtualenvs.path虚拟环境路径

• virtualenvs.options.always-copy复制源文件还是创建链接到虚拟环境

• virtualenvs.options.system-site-packages虚拟环境获得系统包的权限

• repositories.<name>设置一个新的可选仓库

六、依赖配置

依赖的配置有很多种写法：

版本限制：

• 尖括号：^1.2 代表 >=1.2.0 <2.0.0

• 波浪号：~1.2.3 代表 >=1.2.3 <1.3.0

• 星号：1.* 代表 >=1.0.0 <2.0.0

使用git仓库：

[tool.poetry.dependencies]
requests = { git = "https://github.com/requests/requests.git" }

使用本地路径：

[tool.poetry.dependencies]
# directory
my-package = { path = "../my-package/", develop = false }

# file
my-package = { path = "../my-package/dist/my-package-0.1.0.tar.gz" }

使用URL：

[tool.poetry.dependencies]
# directory
my-package = { url = "https://example.com/my-package-0.1.0.tar.gz" }

python限制：

[tool.poetry.dependencies]
pathlib2 = { version = "^2.2", python = "~2.7" }

环境限制：

[tool.poetry.dependencies]
pathlib2 = { version = "^2.2", markers = "python_version ~= '2.7' or sys_platform == 'win32'" }

组合：

[tool.poetry.dependencies]
foo = [
    {version = "<=1.9", python = "^2.7"},
    {version = "^2.0", python = "^3.4"}
]

如果限制很多，写成一行不方便阅读，可以写成多行：

[tool.poetry.group.dev.dependencies]
black = {version = "19.10b0", allow-prereleases = true, python = "^3.6", markers = "platform_python_implementation == 'CPython'"}

写成多行后：

[tool.poetry.group.dev.dependencies.black]
version = "19.10b0"
allow-prereleases = true
python = "^3.6"
markers = "platform_python_implementation == 'CPython'"

分组功能：

[tool.poetry.group.test.dependencies]
pytest = "^6.0.0"
pytest-mock = "*"

例如以上，就建立了一个test的组合的依赖。

下面这两种写法是等价的：

[tool.poetry.dev-dependencies]
pytest = "^6.0.0"
pytest-mock = "*"

或者：

[tool.poetry.group.dev.dependencies]
pytest = "^6.0.0"
pytest-mock = "*"

以上两种写法都声明了一个dev的组的依赖。

声明组合是可选的，这在具体的环境中有的特定的用途时很有用：

[tool.poetry.group.docs]
optional = true

[tool.poetry.group.docs.dependencies]
mkdocs = "*"

添加依赖到组中：

poetry add pytest --group test

同步依赖，只使用poetry.lock中的依赖，移除其他不是必须的依赖：

poetry install --sync 

七、环境管理

Poetry可以为项目使用独立的虚拟环境，而不是使用系统安装的。

切换环境：

poetry env use /full/path/to/python
poetry env use python3.7
poetry env use system

显示当前激活的环境信息：

poetry env info

运行命令会输出如下信息：

Virtual environment
Python:         3.7.1
Implementation: CPython
Path:           /path/to/poetry/cache/virtualenvs/test-O3eWbxRl-py3.7
Valid:          True

System
Platform: darwin
OS:       posix
Python:   /path/to/main/python

列出所有的虚拟环境列表：

poetry env list

删除环境：

poetry env remove /full/path/to/python
poetry env remove python3.7
poetry env remove 3.7
poetry env remove test-O3eWbxRl-py3.7