Poetry:Python的依赖项管理工具

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

Poetry支持Python 2.7 和3.4。

安装

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,

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,

在这时,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,

通过分析oslo.i18n的发布版本,它会发现oslo.i18n==2.1.0需要pbr (>=0.11,

安装命令

当你为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,

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

译者:任宇は神様

  • 发表于:
  • 原文链接https://kuaibao.qq.com/s/20180725A1NSL100?refer=cp_1026
  • 腾讯「云+社区」是腾讯内容开放平台帐号(企鹅号)传播渠道之一,根据《腾讯内容开放平台服务协议》转载发布内容。

扫码关注云+社区

领取腾讯云代金券