python依赖管理和打包工具poetry

poetry是一个python的依赖管理和打包工具，类似于nodejs的npm和java的maven，可以用来管理python项目的依赖和打包发布。

安装

正常安装

poetry需要python3.8以上的版本，这里实验使用官方安装程序安装，安装平台是ubuntu系统，其他安装方式可以参考官方文档

如果没有python3.8以上的版本，可以使用以下命令安装

$ sudo apt install build-essential zlib1g-dev libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libreadline-dev libffi-dev libsqlite3-dev wget libbz2-dev
$ wget https://www.python.org/ftp/python/3.12.1/Python-3.12.1.tar.xz
$ tar -xf Python-3.12.1.tar.xz
$ cd Python-3.12.1
$ ./configure --enable-optimizations --prefix=/usr/local/python3.12
$ make -j 8
$ sudo make install
$ sudo ln -s /usr/local/python3.12/bin/python3.12 /usr/bin/python3.12
$ sudo ln -s /usr/local/python3.12/bin/pip3.12 /usr/bin/pip3.12

有了python环境后，就可以安装poetry了。我目前登录的用户是ubuntu，因此下面的用户家目录是/home/ubuntu，如果是其他用户，需要替换成对应的用户家目录。

# 通过命令安装
$ curl -sSL https://install.python-poetry.org | python3.12 -

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/ubuntu/.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.7.1): Done

Poetry (1.7.1) is installed now. Great!

To get started you need Poetry's bin directory (/home/ubuntu/.local/bin) in your `PATH`
environment variable.

Add `export PATH="/home/ubuntu/.local/bin:$PATH"` to your shell configuration file.

Alternatively, you can call Poetry explicitly with `/home/ubuntu/.local/bin/poetry`.

You can test that everything is set up by executing:

`poetry --version`

# 查看poetry二进制命令的位置
$ ls -l ~/.local/bin/poetry
lrwxrwxrwx 1 ubuntu ubuntu 50 Jan  4 14:08 /home/ubuntu/.local/bin/poetry -> /home/ubuntu/.local/share/pypoetry/venv/bin/poetry
$ ls -l ~/.local/share/pypoetry/venv/bin/poetry
-rwxrwxr-x 1 ubuntu ubuntu 259 Jan  4 14:08 /home/ubuntu/.local/share/pypoetry/venv/bin/poetry

# 查看poetry版本，因为路径已经添加到PATH中，因此可以直接执行poetry命令
$ poetry --version
Poetry (version 1.7.1)

指定安装目录

默认情况下，Linux系统会安装到~/.local/share/pypoetry目录下，如果需要修改安装目录，可以使用POETRY_HOME环境变量，例如：

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

指定发行版本

如果安装预发行版本，可以使用--preview选项或者使用POETRY_PREVIEW环境变量，例如：

$ curl -sSL https://install.python-poetry.org | python3.12 - --preview
$ curl -sSL https://install.python-poetry.org | POETRY_PREVIEW=1 python3.12 -

如果安装特定版本，可以使用--version选项或者使用POETRY_VERSION环境变量，例如：

$ curl -sSL https://install.python-poetry.org | python3.12 - --version=1.2.0
$ curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.2.0 python3.12 -

从git仓库安装

还可以使用git从git仓库安装，例如：

$ curl -sSL https://install.python-poetry.org | python3.12 - --git https://github.com/python-poetry/poetry.git@master

更新

使用self update命令可以更新poetry，例如：

$ poetry self update
Updating Poetry version ...

Using version ^1.7.1 for poetry

Updating dependencies
Resolving dependencies... (270.5s)

No dependencies to install or update

Writing lock file

如果需要更新到预发行版本，可以使用--preview选项，例如：

$ poetry self update --preview

如果需要更新到特定版本，可以使用--version选项，例如：

$ poetry self update --version=1.2.0

卸载

如果不想要poetry了，可以使用--uninstall选项或者使用POETRY_UNINSTALL环境变量，例如：

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

自动补全

poetry 支持为Bash、Fish和Zsh提供自动补全，获取更详细的信息可以使用poetry help completions命令，这里只说Bash的自动补全。

# 生成自动补全脚本
$ vim ~/.profile
......
source <(poetry completions bash)

$ source ~/.profile

基本用法

这里我们使用poetry创建一个fastapi的项目，然后添加依赖，最后打包发布。

fastapi是一个python的web库，可以用来快速构建web服务，使用starlette作为web框架，使用pydantic作为数据验证框架，使用uvicorn作为web服务器。

创建项目

我们先创建一个叫做thousand-sunny的项目，使用poetry new命令可以创建一个新的项目，例如：

$ poetry new thousand-sunny
Created package thousand-sunny in thousand-sunny

创建的项目结构如下：

$ tree thousand-sunny/
thousand-sunny/
├── README.md
├── pyproject.toml
├── tests
│   └── __init__.py
└── thousand_sunny
    └── __init__.py

2 directories, 4 files

其中pyproject.toml是项目的配置文件，thousand_sunny是项目的python包，tests是项目的测试目录。

$ cd thousand-sunny/
$ cat README.md
$ cat pyproject.toml
[tool.poetry]
name = "thousand-sunny"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
readme = "README.md"

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


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

• tool.poetry.name是项目的名称
• tool.poetry.version是项目的版本
• tool.poetry.description是项目的描述
• tool.poetry.authors是项目的作者
• tool.poetry.readme是项目的README文件
• tool.poetry.dependencies是项目的依赖
  • python是python的版本，poetry要求显示的指定python的版本
• build-system是项目的构建系统。

已存在项目初始化

和git类似，如果已经有了一个项目，可以使用poetry init命令初始化，例如：

$ mkdir going-merry
$ cd going-merry/
$ poetry init
This command will guide you through creating your pyproject.toml config.

Package name [going-merry]:
Version [0.1.0]:
Description []:
Author [None, n to skip]:  n
License []:
Compatible Python versions [^3.12]:

Would you like to define your main dependencies interactively? (yes/no) [yes]
You can specify a package in the following forms:
  - A single name (requests): this will search for matches on PyPI
  - A name and a constraint (requests@^2.23.0)
  - A git url (git+https://github.com/python-poetry/poetry.git)
  - A git url with a revision (git+https://github.com/python-poetry/poetry.git#develop)
  - A file path (../my-package/my-package.whl)
  - A directory (../my-package/)
  - A url (https://example.com/packages/my-package-0.1.0.tar.gz)

Package to add or search for (leave blank to skip):

Would you like to define your development dependencies interactively? (yes/no) [yes]
Package to add or search for (leave blank to skip):

Generated file

[tool.poetry]
name = "going-merry"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
readme = "README.md"

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


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


Do you confirm generation? (yes/no) [yes]

# 查看当前目录
$ tree .
.
└── pyproject.toml

0 directories, 1 file

添加依赖

如果向项目中添加依赖，可以使用两种方式，一种是直接编辑pyproject.toml文件，另一种是使用poetry add命令。

直接编辑pyproject.toml

编辑pyproject.toml文件，添加依赖，例如：

$ vim pyproject.toml
......
[tool.poetry.dependencies]
python = "^3.12"
fastapi = "^0.70.0"
uvicorn = "^0.15.0"
......

可以看到，依赖项需要进行包名称和版本的指定，版本可以使用^、~、>、>=、<、<=等符号，也可以使用*表示任意版本。

poetry会根据tool.poetry.dependencies中的依赖项，在tool.poetry.source中的源或者PyPI中查找、安装。

使用poetry add命令

使用poetry add命令也可以添加依赖，例如：

# 添加fastapi依赖
$ poetry add fastapi
Creating virtualenv thousand-sunny-mMs6oAD9-py3.12 in /home/ubuntu/.cache/pypoetry/virtualenvs
Using version ^0.108.0 for fastapi

Updating dependencies
Resolving dependencies... (3.3s)

Package operations: 9 installs, 0 updates, 0 removals

  • Installing idna (3.6)
  • Installing sniffio (1.3.0)
  • Installing typing-extensions (4.9.0)
  • Installing annotated-types (0.6.0)
  • Installing anyio (4.2.0)
  • Installing pydantic-core (2.14.6)
  • Installing pydantic (2.5.3)
  • Installing starlette (0.32.0.post1)
  • Installing fastapi (0.108.0)

Writing lock file

# 添加uvicorn依赖
$ poetry add "uvicorn[standard]"
Using version ^0.25.0 for uvicorn

Updating dependencies
Resolving dependencies... (3.1s)

Package operations: 9 installs, 0 updates, 0 removals

  • Installing click (8.1.7)
  • Installing h11 (0.14.0)
  • Installing httptools (0.6.1)
  • Installing python-dotenv (1.0.0)
  • Installing pyyaml (6.0.1)
  • Installing uvloop (0.19.0)
  • Installing watchfiles (0.21.0)
  • Installing websockets (12.0)
  • Installing uvicorn (0.25.0)

Writing lock file

# 添加开发依赖
$ poetry add pytest -G dev
Using version ^7.4.4 for pytest

Updating dependencies
Resolving dependencies... (2.9s)

Package operations: 4 installs, 0 updates, 0 removals

  • Installing iniconfig (2.0.0)
  • Installing packaging (23.2)
  • Installing pluggy (1.3.0)
  • Installing pytest (7.4.4)

Writing lock file

# 查看pyproject.toml文件
$ cat pyproject.toml
[tool.poetry]
name = "thousand-sunny"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.12"
fastapi = "^0.108.0"
uvicorn = {extras = ["standard"], version = "^0.25.0"}

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

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

可以看到，poetry add命令会自动更新pyproject.toml文件。同时，安装过后会创建一个poetry.lock文件，用来锁定依赖的版本。

使用虚拟环境

poetry会为每个项目创建一个虚拟环境，这样可以避免依赖冲突，也可以避免污染全局环境。

默认情况下，poetry会在{cache-dir}/virtualenvs中创建虚拟环境，可以通过修改cache-dir来修改虚拟环境的位置。另外，可以使用virtualenvs.in-project来指定虚拟环境是否在项目中，如果设置为true，则会在项目的.venv目录中创建虚拟环境。

$ poetry config --list
cache-dir = "/home/ubuntu/.cache/pypoetry"
experimental.system-git-client = false
installer.max-workers = null
installer.modern-installation = true
installer.no-binary = null
installer.parallel = true
virtualenvs.create = true
virtualenvs.in-project = null
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"  # /home/ubuntu/.cache/pypoetry/virtualenvs
virtualenvs.prefer-active-python = false
virtualenvs.prompt = "{project_name}-py{python_version}"
warnings.export = true

可以看到，virtualenvs.create默认为true，virtualenvs.in-project默认为null，virtualenvs.path默认为{cache-dir}/virtualenvs。

要想运行Poetry创建的虚拟环境，可以有多种方式。

run命令

使用poetry run命令可以在虚拟环境中运行命令，例如：

$ poetry run python --version
Python 3.12.1

$ vim main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"Hello": "World"}
$ poetry run uvicorn main:app --reload

shell命令

激活虚拟环境最简单的方式是使用poetry shell命令，例如：

$ poetry shell
Spawning shell within /home/ubuntu/.cache/pypoetry/virtualenvs/thousand-sunny-mMs6oAD9-py3.12

$ python --version
Python 3.12.1

如果要退出虚拟环境并退出shell，可以使用exit命令，如果只是退出虚拟环境，可以使用deactivate命令。

如果想要防止进入虚拟环境修改shell提示符，可以使用环境变量VIRTUAL_ENV_DISABLE_PROMPT=1。

如果不想要创建新shell，可以手动激活虚拟环境，激活命令为：source {path_to_venv}-{python_version}/bin/activate，停用命令相似，为：deactivate。获取虚拟环境的路径可以使用poetry env info --path命令

也可以使用一行命令source "$(poetry env info --path)/bin/activate"激活虚拟环境。

为项目安装依赖

安装全部依赖

如果一个已经存在的项目，它是通过poetry创建的，那么可以使用poetry install命令安装依赖，例如：

$ poetry install

运行此命令的时候有两种情况：

1. poetry.lock文件不存在

   • 如果您以前从未运行过该命令并且也不存在任何poetry.lock文件，Poetry只会解析pyproject.toml文件中列出的所有依赖项并下载其文件的最新版本。
   • 当Poetry完成安装后，它将下载的所有包及其确切版本写入文件中poetry.lock，从而将项目锁定到这些特定版本。
   • Poetry建议应该将该poetry.lock文件提交到项目存储库，以便所有本项目的人员都被锁定到相同版本的依赖项。

2. poetry.lock文件存在

   • 如果您以前运行过该命令并且存在poetry.lock文件，Poetry将使用该文件中列出的确切版本来安装依赖项，尽管依赖有可能不是最新版本。

仅安装依赖

当你当前的项目是一个库，但是又不想安装项目本身，只想安装依赖时，可以使用poetry install --no-root命令，例如：

$ poetry install --no-root

仅安装生产依赖

如果只想安装生产依赖，可以使用--no-dev选项，例如：

$ poetry install --no-dev

仅安装开发依赖

如果只想安装开发依赖，可以使用--dev选项，例如：

$ poetry install --dev

仅安装指定依赖

如果只想安装指定依赖，可以使用--package选项，例如：

$ poetry install --package requests

依赖更新

如果想要更新依赖，可以使用poetry update命令，例如：

$ poetry update

这相当于删除poetry.lock文件并重新运行poetry install命令。

删除依赖

如果想要删除依赖，则只需要执行命令remove，例如：

$ poetry remove requests

依赖导出为其他格式

如果想用其他格式的文件管理依赖，poetry提供了命令可以直接导出。

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

命令的参数如下：

• -f或--format：导出的文件格式，默认为requirements.txt，目前仅支持requirements.txt和constraints.txt两种格式。
• --output：导出的文件路径，默认为stdout。
• --without-hashes：不导出哈希值，默认为false。
• --with-credentials：导出私有仓库的凭证，默认为false。
• --without：不导出指定的依赖组
• --with：导出指定的依赖组

添加仓库源

poetry默认使用PyPI作为仓库源，如果想要添加其他仓库源，可以使用source add命令，例如：

$ poetry source add aliyun https://mirrors.aliyun.com/pypi/simple --priority default

priority参数表示优先级，可接受的值为default、secondary、supplementary和explicit。

如果删除源可以使用source remove命令，例如：

$ poetry source remove aliyun

添加poetry自身的依赖

poetry自身也可以添加依赖和插件，例如：

$ poetry self add poetry-plugin-export

依赖关系管理

依赖组

Poetry提供了一种按组安装依赖关系的方法。例如，您可能具有仅测试项目或构建文档所需的依赖项。

要声明新的依赖项组，可以使用一个tool.poetry.group.<group>部分，其中<group>是依赖项组的名称（例如，test）：

[tool.poetry.group.test]  # This part can be left out

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

• 所有依赖项必须跨组相互兼容，因为无论安装是否需要它们，它们都会被解析。
• tool.poetry.dependencies隐式组main的一部分
• 自poetry 1.2.0以后，tool.poetry.dev-dependencies已经修改为tool.poetry.group.dev.dependencies，tool.poetry.dev-dependencies仍然可以使用，但是会有警告。

可选组

Poetry还提供了一种安装可选依赖项的方法。例如，您可能具有一个依赖项，它只能在某些平台上使用，或者您可能具有一个依赖项，它只能在某些Python版本上使用。

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

使用安装命令时，可以使用--with选项来安装可选组，例如：

$ poetry install --with docs

使用命令向组内添加依赖

通过使用--group(-G)选项，可以将依赖项添加到特定的组中，例如：

$ poetry add pytest -G test

如果该组不存在，会自动创建。

安装依赖

默认情况下，Poetry会安装所有非可选组的依赖项。

如果想要排除几个组，可以使用--without选项，例如：

$ poetry install --without test,docs

如果--without和--with选项同时使用，--without选项会优先--with选项。

如果只是想安装特定的依赖组，可以使用--only选项，例如：

$ poetry install --only test,docs

打包发布

打包

实际发布库之前需要对项目进行打包，使用poetry build命令可以打包项目，例如：

$ poetry build
$ poetry build
Building thousand-sunny (0.1.0)
  - Building sdist
fatal: not a git repository (or any of the parent directories): .git
  - Built thousand_sunny-0.1.0.tar.gz
  - Building wheel
fatal: not a git repository (or any of the parent directories): .git
  - Built thousand_sunny-0.1.0-py3-none-any.whl

打包完成后，会在dist目录下生成打包文件，例如：

$ tree dist/
dist/
├── thousand_sunny-0.1.0-py3-none-any.whl
└── thousand_sunny-0.1.0.tar.gz

0 directories, 2 files

此命令将以两种不同的格式打包您的库：sdist这是源格式，wheel这是compiled包。

Poetry 在构建包时会自动包含一些元数据。

构建wheel时，以下文件会放到.dist-info目录中：

• LICENSE
• LICENSE.*
• COPYING
• COPYING.*
• LICENSES/**

构建sdist时，根文件夹中将包含以下文件：

• LICENSE*

构建完成后，就可以发布库了。

发布

默认情况下，Poetry会将库发布到PyPI，但是您可以配置它以发布到其他地方。

使用poetry发布十分简单，只需要使用poetry publish命令即可，例如：

$ poetry publish

注意：发布的包的名称和版本是通过pyproject.toml文件中的name和version字段来确定的。同时，publish命令不会自动执行build命令，如果想要一起执行，可以添加--build选项

但是，很多时候需要使用到私有仓库，这时候就需要配置私有仓库，然后指定发布到私有仓库。

$ poetry publish -r my-repository

配置

本地配置

有时候需要在本地配置一些内容，例如，配置仓库源、配置虚拟环境的位置等。

$ poetry config virtualenvs.create true --local
$ poetry config virtualenvs.in-project true --local

此时，会在项目的根目录下生成一个poetry.toml文件，例如：

$ cat poetry.toml
[virtualenvs]
create = true
in-project = true

环境变量

有时，特别是在将Poetry与CI工具一起使用时，使用环境变量更容易，而不必执行配置命令。

Poetry支持这一点，任何设置都可以通过使用环境变量来设置。

环境变量必须以设置POETRY_的大写名称为前缀，并由下划线替换点和破折号组成。

export POETRY_VIRTUALENVS_PATH=/path/to/virtualenvs/directory

这也适用于secret设置，例如凭据：

export POETRY_HTTP_BASIC_MY_REPOSITORY_PASSWORD=secret

可用配置

Poetry支持的配置可以参考官方文档

管理环境

poeotry提供了一些命令来管理环境，例如：

# 列出所有的虚拟环境
$ poetry env list
# 列出当前虚拟环境信息
$ poetry env info
# 删除虚拟环境
$ poetry env remove test-a test-b test-c

指定python版本

使用poetry可以直接指定你需要的python版本，例如：

$ poetry env use /usr/bin/python3.12

如果要禁用虚拟环境，可以使用system选项查找默认行为，例如：

$ poetry env use system

显示环境信息

使用info命令可以显示当前虚拟环境的信息，例如：

$ poetry env info

Virtualenv
Python:         3.12.1
Implementation: CPython
Path:           /home/ubuntu/.cache/pypoetry/virtualenvs/thousand-sunny-mMs6oAD9-py3.12
Executable:     /home/ubuntu/.cache/pypoetry/virtualenvs/thousand-sunny-mMs6oAD9-py3.12/bin/python
Valid:          True

System
Platform:   linux
OS:         posix
Python:     3.12.1
Path:       /opt/python312
Executable: /opt/python312/bin/python3.12

如果只想知道路径信息，可以使用--path选项，入股执行知道可执行文件的路径，可以使用--executable选项。

$ poetry env info --path
/home/ubuntu/.cache/pypoetry/virtualenvs/thousand-sunny-mMs6oAD9-py3.12
$ poetry env info --executable
/home/ubuntu/.cache/pypoetry/virtualenvs/thousand-sunny-mMs6oAD9-py3.12/bin/python

依赖规范

项目的依赖项可以以各种形式指定，这取决于依赖项的类型以及安装它可能需要的可选约束。

具体的显示可以参考官方文档 Dependency specification

pyproject.toml 文件

pyproject.toml文件是Poetry项目的核心，它包含了项目的元数据和依赖项。

name

name字段是项目的名称，必需项。

version

version字段是项目的版本，必需项。

description

description字段是项目的简短描述，必需项。

license

license字段是项目的许可证，可选项。

常见的许可证有以下几种：

• Apache-2.0
• BSD-2-Clause
• BSD-3-Clause
• BSD-4-Clause
• GPL-2.0-only
• GPL-2.0-or-later
• GPL-3.0-only
• GPL-3.0-or-later
• LGPL-2.1-only
• LGPL-2.1-or-later
• LGPL-3.0-only
• LGPL-3.0-or-later
• MIT

强烈建议添加，更多的许可证可以参考SPDX 开源许可证注册表

如果项目是专有的并且不使用特定许可证，则可以将此值设置为Proprietary。

authors

authors字段是项目的作者，必需项。

是作者列表，应至少包含一名作者。作者必须采用name <email>的形式。

authors = [
    "Sébastien Eustace <sebastien@eustace.io>",
]

maintainers

maintainers字段是项目的维护者，可选项。

这是维护者列表，应与作者区分开来。维护者可能包含电子邮件并采用表格形式name <email>。

maintainers = [
    "John Smith <johnsmith@example.org>",
    "Jane Smith <janesmith@example.org>",
]

readme

包的readme文件的路径，可选项。路径相对于pyproject.toml文件。

homepage

项目的主页，可选项。

repository

项目的仓库，可选项。

classifiers

描述该项目的PyPI分类器列表，可选项。

packages

最终发行版中包含的包和模块的列表，可选项。

include and exclude

将包含在最终包中的模式列表。

dependencies and dependency groups

项目的依赖项，可选项。

scripts

安装包时将安装的脚本或可执行文件，可选项。

[tool.poetry.scripts]
my_package_cli = 'my_package.console:run'

在这里，我们将声明my_package_cli安装脚本，该脚本将执行my_package包中模块console中的函数run。

添加完本地脚本后，可以使用poetry run或者poetry install命令安装脚本。

extras

额外的依赖项，可选项。

• 可选依赖项，可增强包，但不是必需的
• 可选依赖项的集群。