跳到主要内容

How to Manage Your Python Projects Using Poetry

前段时间在写 tidbcloudy（一个 TiDB Cloud Python SDK）的时候用到了 Poetry 来管理依赖以及发布到 PyPI。经历了五次小版本的迭代，感觉 Poetry 时常让我有一种“写 SDK 也不难，发版也可以很简单”的错觉，所以决定记录一下我是如何使用 Poetry 来完成我的第一个 SDK 的。

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.

Poetry 是一个管理 Python 依赖的工具，它可以帮助你声明你的项目依赖的库，然后帮你管理（安装/更新）它们。Poetry 提供了一个 poetry.lock 文件来确保可复现，也可以将你的项目打包。

安装 Poetry​

下面以在 Ubuntu 20.04 上安装及使用 Poetry 为例。详细的安装方法，请参考 Poetry 官方文档。

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

输出结果示例：

Retrieving Poetry metadata

# Welcome to Poetry!

This will download and install the latest version of Poetry,
a dependency and package manager for Python.

It will add the `poetry` command to Poetry's bin directory, located at:

/home/oreo/.local/bin

You can uninstall at any time by executing this script with the --uninstall option,
and these changes will be reverted.

Installing Poetry (1.2.2): Creating environment
Installing Poetry (1.2.2): Done

Poetry (1.2.2) is installed now. Great!

You can test that everything is set up by executing:

`poetry --version`

查看 Poetry 版本：

poetry --version

输出结果示例：

Poetry (version 1.2.2)

开启 tab 自动补全（可选）​

poetry 命令支持在 Bash、Fish 和 Zsh 中开启 tab 自动补全功能。详细的开启方法，请参考 Poetry 官方文档。

备注

在写这篇文章的时候，测试发现 poetry Bash 自动补全无法正常使用。具体 issue 可以关注 #6835。

提示

查看当前使用的 shell：

echo $SHELL

下面以开启 Zsh 自动补全为例：

poetry completions zsh > ~/.zfunc/_poetry

使用效果：

$ poetry [TAB]
about    -- Shows information about Poetry.
add      -- Adds a new dependency to pyproject.toml.
build    -- Builds a package, as a tarball and a wheel by default.
cache    -- Interact with Poetry's cache
check    -- Checks the validity of the pyproject.toml file.
config   -- Manages configuration settings.
debug    -- Debug various elements of Poetry.
env      -- Interact with Poetry's project environments.
export   -- Exports the lock file to alternative formats.
help     -- Display the manual of a command

初始化项目​

使用 poetry new 命令创建并初始化一个新项目 tidbcloudy：

poetry new tidbcloudy

输出结果示例：

Created package tidbcloudy in tidbcloudy

查看新创建的 tidbcloudy 项目目录结构：

$ tree tidbcloudy
tidbcloudy
├── README.md
├── pyproject.toml
├── tests
│   └── __init__.py
└── tidbcloudy
    └── __init__.py

2 directories, 4 files

文件说明：

  • README.md：项目说明文件

  • pyproject.toml：项目配置文件，包含项目的名称、版本、作者等项目基本信息以及项目的依赖信息等。详细说明可参考 Poetry 官方文档。

    [tool.poetry]
    name = "tidbcloudy"
    version = "0.1.0"
    description = ""
    authors = ["Oreo <[email protected]>"]
    readme = "README.md"

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

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

  • tests：单元测试文件夹

  • tidbcloudy：项目源码文件夹

管理依赖​

在 pyproject.toml 文件中，tool.poetry.dependencies 字段用于管理项目的依赖。你可以通过修改该字段或使用 poetry 命令来管理依赖。

编辑依赖​

tidbcloudy 是一个 TiDB Cloud SDK，需要使用 requests 发送 HTTP 请求。下面提供了直接修改 pyproject.toml 文件和使用 poetry add 命令两种方式：

pyproject.toml
[tool.poetry.dependencies]
requests = "^2.27.1"

安装依赖​

在完成项目依赖的编辑之后，你可以使用 poetry install 命令安装 pyproject.toml 中的依赖：

poetry install

在第一次执行 poetry install 时，该命令会生成 poetry.lock 文件，用于锁定依赖的版本，实现可复现的构建。当项目中已经存在 poetry.lock 文件时，poetry 会根据 pyproject.toml 中的依赖名称和 poetry.lock 中具体的版本及 Hash 等信息来安装依赖。

备注

如果你通过编辑 pyproject.toml 文件来更新依赖，可能会出现 pyproject.toml 与 poetry.lock 文件不一致的情况，你可以通过如下方式解决：

管理项目版本​

你可以通过修改 pyproject.toml 文件或使用 poetry version 来管理项目版本。

pyproject.toml
[tool.poetry]
version = "0.1.1"

发布项目​

下面以发布 tidbcloudy 项目到 PyPI 为例。

配置 token​

参考 PyPI 官方文档 申请你的 PyPI token，然后使用 poetry config 命令配置：

poetry config pypi-token.pypi my-token

打包​

使用 poetry build 命令打包：

poetry build

输出结果示例：

Building tidbcloudy (0.1.1)
  - Building sdist
  - Built tidbcloudy-0.1.1.tar.gz
  - Building wheel
  - Built tidbcloudy-0.1.1-py3-none-any.whl
备注

如果遇到 [Errno 2] No such file or directory: 'python' 错误，可以参考 poetry/issue/6841 执行如下命令：

rm -rf $(poetry config virtualenvs.path)/*

上传​

使用 poetry publish 命令上传：

poetry publish

上传完成后，你可以通过 PyPI 网站查看你的项目，以及使用 pip install 命令进行安装：

pip install tidbcloudy