Poetry可以帮助你声明、管理和安装Python项目的依赖项，确保你可以在任何地方都拥有正确的堆栈。

Poetry支持Python 2.7 和Python 3以上

安装

Poetry提供了一个自定义安装程序，它通过打包自己依赖项的方式来确保Poetry与系统其他部分隔离。本文推荐通过这种方法来安装Poetry。

或者，你也可以下载并单独执行get-poetry.py文件。

如果你想要安装预发布版本，你可以执行get-poetry.py –preview命令：

类似地，如果你想要安装一个特定的版本，你可以使用命令 --version：

也可以使用pip来安装poetry。

然而请注意，它还将继续安装Poetry的依赖，而这很可能会引起冲突。

升级 poetry

将poetry升级到最新的稳定版本只需要简单的调用self:update命令。

如果你想安装预发布版本，你可以使用--preview选项。

最后，如果你想要安装一个特定的版本，你可以把版本号作为一个参数传递给self:update。

为Bash、Fish或Zsh启用tab补全功能

Poetry支持生成Bash、Fish和Zsh的自动补全脚本。完整细节请参阅poetry help completions，要点非常简单，只要使用以下命令中的某一个：

注意：为了使更改生效，您可能需要重新启动shell。

对于zsh，您必须在compinit之前，在~/.zshrc中添加以下行。:

简介

poetry是一款用来处理依赖项的安装、构建和打包成Python包的工具。只需要一个标准的pyproject.toml文件就可以完成以上所有任务。

换句话说，poetry用pyproject.toml取代了setup.py, requirements.txt, setup.cfg, MANIFEST.in 以及最新加入的Pipfile。

这里有一些我们需要注意的事情:

l  它将尝试将语义版本控制作为版本命名的最佳实践。

l  你可以指定自述文件、需要包含和排除的文件：不再需要使用MANIFEST.in。Poetry也会使用VCS的忽略文件（如gitignore）来填充exclude部分。

l  可以指定（最多5个）关键字，并将它们作为包装站点上的标签。

l  依赖项部分支持插入符、波浪符、通配符、不等式和多重需求。

l  你必须指定与包兼容的python版本。

Poetry同样也会检测出你是否处在一个虚拟环境中并安装相应的软件包。这就是说，poetry可以在任何范围内被安装和使用。

受益于Molinillo的启发，poetry也有一个完整的依赖项解析库。

为什么使用它？

在Python中，打包系统和依赖项管理是相当复杂的，对于新手来说很难理解。即使对于经验丰富的开发人员来说，在Python项目中创建所需的所有文件有时也很麻烦：setup.py, requirements.txt, setup.cfg, MANIFEST.in以及新添加的Pipfile。

因此，我想要一个工具，它可以将所有东西限制在一个配置文件中：依赖项管理、打包和发布。

它同样也从其他语言的工具中获得了灵感，比如composer（PHP）或cargo（Rust）。

最后，没有可靠的工具可以妥当地解决Python中的依赖性，所以我开发了poetry，为了给Python社区带来一个详尽的依赖项解析器。

Pipenv呢?

简而言之：我不喜欢它提供的命令行界面，也不喜欢它做的一些决定，我认为我们可以做一个更好、更直观的。下面就是pipenv里面一些我不喜欢的东西。

依赖项解析

依赖项解析是不稳定的，即使有解决办法但还是会失败。让我们举一个例子:

将会报出这样的错误:

然而Poetry就会给你带来各组正确的包：

结果是:

这要归功于Poetry中心的高效依赖项解析器。

下面是以上命令的具体实现情况：

oslo.utils (1.4.0) 依赖于:

l  pbr (>=0.6,!=0.7,<1.0)

l  Babel (>=1.3)

l  six (>=1.9.0)

l  iso8601 (>=0.1.9)

l  oslo.i18n (>=1.3.0)

l  netaddr (>=0.7.12)

l  netifaces (>=0.10.4)

我们真正感兴趣的是pbr (>=0.6,!=0.7,<1.0)。

在这时，poetry将选择pbr==0.11.1，这是与约束相匹配的最新版本。

接下来，它将尝试选择oslo.i18n==3.20.0，这是与oslo.i18n (>=1.3.0)匹配的最新版本。

然而，这个版本需要pbr (!=2.1.0,>=2.0.0)，这与pbr==0.11.1不兼容，所以poetry试图找到某个版本的oslo.i18n来满足pbr (>=0.6,!=0.7,<1.0)。

通过分析oslo.i18n的发布版本，它会发现oslo.i18n==2.1.0需要pbr (>=0.11,<2.0)。到这时，因为没有了更多的冲突，其余部分的解决方法直截了当。

安装命令

当你为install命令指定一个包时，它将被添加为一个通配符依赖项。这意味着可以安装该软件包的任何版本，而这很有可能导致兼容性问题。

而且，您必须显式地告诉它，当你安装新的软件包时，不要升级已经被锁定的包。这些应该是默认的。

删除命令

如果不再需要指定的包，remove命令只会删除包，不会删除包的依赖项。

想要解决这个问题，你需要使用sync或clean。

有限的范围

还有，Pipfile只是requirements.txt的替代品。到最后，你仍需要按照与你在Pipfile文件中完全相同的依赖项声明来填充setup.py文件（或setup.cfg）。因此最终为了正确地设置项目，你还是需要管理一些配置文件。

指令

new

这个命令将以创建适合大多数项目的目录结构的方式来启动你的新Python项目。

将创建一个如下的文件夹：

如果您想要重命名文件夹，您可以通过输入--name选项来实现：

init

这个命令提示你提供关于包的基本信息，这些将帮助你交互式的创建一个pyproject.toml文件。

它会交互式地要求您填充字段，同时使用一些智能默认值。

选项

--name：包的名称。

--description：包的描述。

--author: 包的作者。

--dependency：包需要有一个版本约束。应该按照下面格式foo:1.0.0。

--dev-dependency：开发需求，更多请参阅--require。

Install

install命令会从当前目录中读取pyproject.toml文件，解析依赖项并安装。

如果当前目录中有pyproject.lock文件，它将使用来自那里的指定版本。这确保每个使用库的人都能得到相同版本的依赖项。

如果没有pyproject.lock文件，Poetry将在依赖项解析后创建一个。

您可以指定no-dev选项来禁止安装开发依赖项。

您还可以通过传递--E|--extras附加选项来指定您想要安装的附加功能（请参阅附加信息以获得更多信息）

选项

--no-dev：不要安装开发依赖项。

-E|--extras：特性安装（允许多值）。

Update

为了获得依赖项的最新版本，并更新pyproject.lock文件，你应该使用update命令。

这将解决项目的所有依赖项，并将确切的版本写入pyproject.lock。

如果你只是想更新某些软件包，而不是全部，你可以将它们列出如下：

选项

--dry-run：输出操作，但不会执行任何操作（隐式启用--verbose）。

Add

add命令向pyproject.toml中添加所需的软件包并安装它们。

如果你没有指定一个版本约束，那么poetry将根据可用的包版本选择一个合适的版本。

选项

--D|dev：添加包作为开发依赖项。

--optional：添加作为可选的依赖项。

--dry-run：输出操作，但不会执行任何操作（隐式启用--verbose）。

Remove

remove命令会从当前安装的包列表中删除一个包。

选项

--D|dev：从开发依赖项中删除一个包。

--dry-run：输出操作，但不会执行任何操作（隐式启用--verbose）。

Show

要想列出所有可用的软件包，你可以使用show指令。

如果你想要查看某个包的详细信息，你可以把包的名称作为参数传递。

选项

--tree：树形展示依赖项。

-l|--latest：展示最新版本。

-o|--outdated：显示最新版本，但只针对过时的软件包。

Build

build命令会构建源和wheels档案。

请注意，目前只支持纯python wheels。

选项

-F|--format：将格式限制为wheel或sdist。

Publish

这个命令构建（如果还没有构建）并将包发布到远程存储库。

如果这是第一次提交，它会自动注册这个包。

选项

-r|--repository：将包注册到（默认：pypi）的存储库。它应该与配置命令设置的存储库名称相匹配。

--username (-u)：访问存储库的用户名。

--password (-p)：访问存储库的密码。

Config

config命令允许你编辑poetry的配置和存储库。

用法

setting-key是一个配置选项名，setting-value1则是一个配置值。

修改存储库

除了修改配置部分之外，config命令还支持对存储库部分进行更改，方法如下：

这会把存储库foo指定的url地址设置为https://foo.bar/simple/.。

你也可以很轻松的将凭据存储到特定的存储库中：

如果你没有指定密码，会提示你必须指定。

选项

--unset：删除由setting-key命名的配置元素。

--list：显示当前配置变量的列表。

Search

这个命令会在远程索引上搜索包。

选项

-N|--only-name：只在名字中搜索。

Lock

这个命令会锁定（而且不安装）在pyproject.toml中指定的依赖项。

pyproject.toml文件

pyproject.toml中的tool.poetry部分由多个部分组成。

名字

包的名字。必须

版本

包的版本。必须

这里应该遵循语义版本控制。然而它不会被强制执行，你可以自由地遵循其他规范。

描述

对包的简短描述。必须

许可证

包的许可证。

最常见的许可证的推荐符号是（按字母排列）：

l  Apache-2.0

l  BSD-2-Clause

l  BSD-3-Clause

l  BSD-4-Clause

l  GPL-2.0

l  GPL-2.0+

l  GPL-3.0

l  GPL-3.0+

l  LGPL-2.1

l  LGPL-2.1+

l  LGPL-3.0

l  LGPL-3.0+

l  MIT

可选，但强烈建议提供。更多的标识符在SPDX开放源码许可注册表中列出。

作者

这个包的作者。这是一个作者列表，应该包含至少一个作者。

作者必须以名字 <邮箱地址>的形式出现。

自述

包的自述文件。必须

文件可以是README.rst或README.md。

主页

一个到项目网站的URL地址。可选

存储库

一个到项目存储库的URL地址。可选

文档

一个指向项目文档的URL地址。可选

关键字

与包相关的关键字列表（最多5个）。可选

应用和排除

这是一个在最终包中会被应用的模式列表。

为了更好地打包，你可以显式地指定poetry应该忽略或应用的一组globs。在排除字段中指定的globs会标识出一组文件，而这些文件在构建包时不会被包含在内。

如果一个包应用了VCS，那么排除字段将被写入到VCS的忽略文件（例如，git中的gitignore）。

依赖项和开发依赖项

在默认配置情况下，Poetry会去寻找PyPi上的依赖关系。在这时，只需要提供名称和版本的字符串。

如果想使用私有存储库，你可以把它添加到pyproject.toml文件,如下所示:

请注意，必须要声明与你的包兼容的python版本：

插入符号需求

插入符号需求允许对指定版本进行语义版本兼容性的更新。如果新版本号没有修改主要的、次要的、补丁组中最左边的数字，则会被允许更新。在这种情况下，如果我们运行poetry update requests，而且如果它是可用的，那么poetry将会更新到版本2.14.0，但是不会更新到3.0.0。如果我们把版本字符串指定为^0.1.13，那么诗歌就会更新到0.1.14，而不是0.2.0。一般认为0.0.x不会与其他任何版本兼容。

下面是一些关于插入符号需求的例子，以及它们可以使用的版本：

波浪符需求

波浪符需求会指定一个具有更新功能的最小版本。如果你指定了一个主要的、次要的和补丁的版本，或者只是一个主要的和次要的版本，那么只允许进行补丁级别的更改。如果您只指定一个主要版本，那么就允许进行次要的和补丁级别的更改。

~1.2.3是一个波浪符需求的例子。

通配符需求

通配符需求会允许使用任意已被通配符定位的版本。

*, 1.*和1.2.*是通配符需求的示例。

不等式需求

不等式需求允许手动指定依赖的版本范围或一个确切的版本。

下面是不等式需求的一些例子:

多重需求

多个版本需求也可以用逗号分隔，例如：=1.2，<1.5。

git的依赖

为了依赖一个位于git存储库中的库，你只需要指定一个带有git键的存储库的位置：

由于我们没有指定任何其他信息，所以Poetry假设我们打算使用主分支上的最新提交来构建我们的项目。您可以将git键与rev、tag或branch键组合在一起，用来指定其他东西。这里有个例子，说明您想要使用一个名为next的分支上最新的提交：

Python限制的依赖

您还可以指定只针对特定的Python版本安装的依赖项：

脚本

本节描述在安装包时将要安装的脚本或可执行文件

在安装了一个带有上述toml的包之后，poetry将在命令行中成为一个通用命令，它将等同于在poetry包中执行console.run命令。

附加项

Poetry通过额外的表达式来支持附加项：

l  可选的依赖项，它可以增强包的功能，但不是必需安装的;

l  集群的可选依赖项。

在安装包时，您可以通过使用-E|--extras附加选项来指定获取额外功能：

插件

Poetry支持任何插件，它们的工作原理类似于setuptools的入口点。为了匹配setuptools文档中的示例，您需要使用以下命令：

英文原文：https://github.com/sdispater/poetry