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\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.设置一个新的可选仓库

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

版本限制：

尖括号：^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