跳到主要内容

PEP 440 - Version Identification and Dependency Specification

· 阅读需 7 分钟

原文链接：https://peps.python.org/pep-0440/#version-specifiers

仅挑选部分说明，忽略了预发布、后发布与本地版本等内容。大部分机翻，少部分有语义调整。

摘要​

此 PEP 描述了一种用于识别 Python 软件发行版本并声明对特定版本的依赖关系的方案。

如 PEP 345 和 PEP 386 中所述，本文档解决了先前尝试标准化版本控制方法的几个限制。

版本格式​

公共版本标识符​

规范的公共版本标识符必须符合以下格式:

[N!]N(.N)*[{a|b|rc}N][.postN][.devN]

公共版本标识符不得包含前导或尾随空格。

公共版本标识符在给定的发行版中必须是唯一的。

公共版本标识符最多分为五个部分：

  • Epoch segment: N!
  • Release segment: N(.N)*
  • Pre-release segment: {a|b|rc}N
  • Post-release segment: .postN
  • Development release segment: .devN

任何给定的版本都将是以下部分中定义的 “final release”, “pre-release”, “post-release” 或者 “developmental release”。

所有数字组件必须是非负整数，表示为 ASCII 数字序列。

所有数字组件必须根据其数值进行解释和排序，而不是作为文本字符串。

所有数字分量可能为零。 除了下面对发布部分的描述之外，零的数字分量除了始终是版本排序中可能的最低值之外没有特殊意义。

最终发布​

仅由发布段和可选的时代标识符组成的版本标识符称为“最终版本”。

Release segment 由一个或多个非负整数值组成，以点分隔：

N(.N)*

项目中的最终版本必须以不断增加的方式编号，否则自动化工具将无法正确升级它们。

发布段的比较和排序依次考虑发布段的每个组成部分的数值。 当比较具有不同数量的组件的发布段时，较短的段会根据需要用额外的零填充。

虽然在此方案下允许在第一个组件之后添加任意数量的附加组件，但最常见的变体是使用两个组件（“major.minor”）或三个组件（“major.minor.micro”）。

版本说明符​

版本说明符由一系列以逗号分隔的版本条件组成。 例如：

~= 0.9, >= 1.0, != 1.3.4.*, < 2.0

比较运算符确定版本条件的类型：

  • ~=: 兼容发布条件
  • ==: 版本匹配条件
  • !=: 版本排除条件
  • <=, >=: 包含有序比较条件
  • <, >: 排除有序比较条件
  • ===: 任意相等条件

逗号 (“,”) 等效于逻辑与运算符：候选版本必须匹配所有给定的版本子句才能匹配整个说明符。

当多个候选版本与版本说明符匹配时，首选版本应该是由标准版本方案定义的一致排序确定的最新版本。

兼容发布​

匹配预期与指定版本兼容的任何候选版本。

指定的版本标识符必须采用版本格式中描述的标准格式。

对于给定的发布标识符 V.N，兼容的发布子句大致等价于如下两个比较子句：

>= V.N, == V.*

此运算符不得与单个段版本号（例如 ~=1）一起使用。

例如，以下几组版本条件是等价的：

~= 2.2
>= 2.2, == 2.*

~=1.4.5
>= 1.4.5, == 1.4.*

版本匹配​

指定的版本标识符必须采用版本格式中描述的标准格式，但在公共版本标识符上允许使用尾随 .*，如下所述。

通过在版本匹配条件中的版本标识符后面附加一个尾随 .* ，可以请求前缀匹配而不是严格比较。这意味着在确定版本标识符是否与子句匹配时，将忽略附加的尾随段。如果指定的版本仅包含发布段，则发布段中的尾随组件（或缺少的组件）也将被忽略。

版本排除​

与版本匹配正相反。

包含有序比较​

包含有序比较条件包括比较运算符和版本标识符，并且将根据标准版本方案定义的一致顺序，根据候选版本和指定版本的相对位置匹配比较正确的任何版本。

排除有序比较​

排除有序比较 > 和 < 类似于包含排序比较，因为它们依赖于候选版本和指定版本的相对位置，给定标准版本方案定义的一致排序。

例如，>1.7 将允许 1.7.1 但不允许 1.7.0。

任意相等​

任意相等比较是简单的字符串相等操作，它不考虑任何语义信息，例如零填充或本地版本。该运算符也不像 == 运算符那样支持前缀匹配。

任意相等的主要用例是允许指定一个不能由这个 PEP 表示的版本。 这个操作符是特殊的，它充当一个逃生舱口，允许使用实现此 PEP 的工具的人仍然安装与此 PEP 不兼容的旧版本。

一个例子是 ===foobar，它会匹配名为 foobar 的一个版本。

强烈建议不要使用此运算符，并且工具在使用时可能会显示警告。