跳转至

poetry 管理Python项目

概要: 利用poetry工具和pyproject.toml配置文件，管理Python项目的依赖，测试以及构建环境

创建时间: 2023.03.21 23:10:55

更新时间: 2023.11.10 00:00:25

安装配置poetry

参考 Introduction

安装二进制文件

macOS，Linux，Windows均适用，下面以macOS为例进行配置

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

配置镜像源

以清华大学镜像源为例

Bash
1
poetry source add --priority=default mirrors https://pypi.tuna.tsinghua.edu.cn/simple/

添加到PATH

以zsh环境为例

Bash
1
echo 'export "PATH=$HOME/.local/bin:$PATH"' >> ~/.zshrc

常用命令

查看poetry版本

Bash
1
poetry --version

更新poetry

Bash
1
poetry self update

卸载poetry

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

配置poetry自动补全

实现tab键命令提示的效果，如下
image.png

bash环境

Bash
1
poetry completions bash >> ~/.bash_completion

zsh环境

Bash
1
poetry completions zsh > ~/.zfunc/_poetry
此外需要确认下面两行在 ~/.zshrc 配置文件中已存在，如果不存在则需要手动添加进去
Bash
1
2
fpath+=~/.zfunc
autoload -Uz compinit && compinit
如果在使用OhMyZsh，那么可以启用poetry插件
首先执行
Bash
1
2
mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry
然后添加插件到 ~/.zshrc 配置文件中
Bash
1
plugins=(poetry ...)
image.png

使用poetry

参考 Basic usage | Documentation | Poetry - Python dependency management and packaging made easy

管理项目

全新项目

Bash
1
poetry new poetry-demo

已有项目

Bash
1
2
cd pre-existing-project
poetry init

项目结构

在利用poetry管理Python项目后，其目录结构一般如下

Bash
1
2
3
4
5
6
7
.
├── README.md
├── poetry_demo
│   └── __init__.py
├── pyproject.toml
└── tests
    └── __init__.py
image.png
其中 pyproject.toml 为当前流行的Python项目配置文件，目前许多主流的Python工具已支持此配置文件，此配置文件的详细介绍详见 pyproject.toml ，此处仅介绍与poetry工具相关部分。
使用poetry初始化项目后，pyproject.toml文件如下，十分清晰不再赘述
TOML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[tool.poetry]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = ["lzwang <xxxyyy@gmail.com>"]
readme = "README.md"
packages = [{include = "poetry_demo"}]

[tool.poetry.dependencies]
python = "^3.10"


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

添加包

配置加速镜像

为加速下载pypi包，国内考虑使用镜像加速，在poetry管理的Python项目目录下，执行如下命令添加清华大学源为首选source

Bash
1
poetry source add --default mirrors https://pypi.tuna.tsinghua.edu.cn/simple/
此外还可以添加次选source
Bash
1
poetry source add --secondary mirrors https://mirrors.ustc.edu.cn/pypi/web/simple
更多pypi源配置，可参考Python Pip包管理 - Cloud Notes

添加包

与pip工具类似，目前部分pypi包支持使用poetry直接安装

Bash
1
poetry add pendulum
此命令将自动同步依赖到 poetry.lock 中
如果需要将包添加到独立的开发环境模式，需要增加 -D 参数
Bash
1
poetry add ruff -D

同步 poetry.lock

如果在 pyproject.toml 中手动添加了包依赖，可以使用下面的命令同步到 poetry.lock 中

Bash
1
poetry lock

更新包

更新当前项目的所有依赖包，使用 pip 工具很难做到这一点，但 poetry 可以

Bash
1
poetry update
如果需要更新指定的包
Bash
1
poetry update pendulum

导出包到 requirements.txt

Bash
1
poetry export --output requirements.txt

项目结构变更

执行完上述操作后，对比发现pyproject.toml文件已经增加了对poetry源和项目依赖包的描述
image.png
可以看到项目依赖自动增加，如果迁移到其他机器，执行下面的命令即可还原项目包配置

Bash
1
poetry install
备注，使用poetry管理项目后，会在项目根目录生成 poetry.lock 文件（不要手动更改，poetry会自动更新）
image.png

管理虚拟环境

在利用poetry管理项后，poetry会默认会在 ~/Library/Caches/pypoetry 目录下（macOS）创建一个虚拟环境，有两种方式可以在虚拟环境中进行交互
当前shell

Bash
1
2
3
4
5
# activate
source $(poetry env info --path)/bin/activate

# deactivate
deactivate
sub-shell
Bash
1
2
3
4
5
# activate
poetry shell

# deactivate
exit
image.png

更多

限于篇幅，以下poetry内容待研究，即通过阅读官方文档输出自己的理解

  • 管理项目依赖，即poetry如何管理项目的包依赖以及版本：Managing dependencies 以及 Dependency specification
  • 管理发布包，即poetry如何发布包到pypi或自定义仓库：Libraries
  • poetry命令行，即poetry的各个命令用法：Commands
  • poetry配置，即如何查看和管理poetry自身的配置：Configuration
  • 管理库，即如何通过poetry连接库添加、更新或发布包：Repositories
  • 管理Python环境，即如何通过poetry管理项目的Python环境，pyenv工具值得关注：Managing environments
  • 插件系统，即如何通过插件增强poetry的能力：Plugins
  • pyproject.toml，即poetry管理的项目如何在pyproject.toml配置文件中体现，The pyproject.toml file

参考