摘要

本PEP描述了一种向Python发行版添加元数据的机制。它包括字段名称的细节，以及它们的语义和用法。

本文档指定元数据格式的1.2版本。1.0版本在PEP 241中指定。1.1版本在PEP 314中指定。

元数据格式的1.2版本增加了一些可选字段，旨在使Python软件的第三方打包更容易。这些字段是“Requires-Python”、“Requires-External”、“Requires-Dist”、“Provides-Dist”和“Obsoletes-Dist”。此版本还更改了“Platform”字段。还添加了三个新字段：“Maintainer”、“Maintainer-email”和“Project-URL”。

最后，这个新版本还添加了环境 标记。

字段

本节规定了每个支持的元数据字段的名称和语义。

标有“(多次使用)”的字段可以在单个 PKG-INFO 文件中多次指定。其他字段在 PKG-INFO 文件中只能出现一次。标有“(可选)”的字段在有效的 PKG-INFO 文件中不是必需的；所有其他字段都必须存在。

Metadata-Version: 1.2

Name: BeagleVote

Version: 1.0a2

Platform: ObscureUnix
Platform: RareDOS

Supported-Platform: RedHat 7.2
Supported-Platform: i386-win32-2791

Summary: A module for collecting votes from beagles.

Description: This project provides powerful math functions
        |For example, you can use ``sum()`` to sum numbers:
        |
        |Example::
        |
        |    >>> sum(1, 2)
        |    3
        |

Keywords: dog puppy voting election

Home-page: http://www.example.com/~cschultz/bvote/

Author: C. Schultz, Universal Features Syndicate,
        Los Angeles, CA <cschultz@peanuts.example.com>

Author-email: "C. Schultz" <cschultz@example.com>

Maintainer: C. Schultz, Universal Features Syndicate,
        Los Angeles, CA <cschultz@peanuts.example.com>

Maintainer-email: "C. Schultz" <cschultz@example.com>

License: This software may only be obtained by sending the
        author a postcard, and then the user promises not
        to redistribute it.

License: GPL version 3, excluding DRM provisions

Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console (Text Based)

Requires-Dist: pkginfo
Requires-Dist: PasteDeploy
Requires-Dist: zope.interface (>3.5.0)

Provides-Dist: OtherProject
Provides-Dist: AnotherProject (3.4)
Provides-Dist: virtual_package

Obsoletes-Dist: Gorgon
Obsoletes-Dist: OtherProject (<3.0)

Requires-Python: 2.5
Requires-Python: >2.1
Requires-Python: >=2.3.4
Requires-Python: >=2.5,<2.7

Requires-External: C
Requires-External: libpng (>=1.5)

Project-URL: Bug Tracker, https://github.com/pypa/setuptools/issues
Project-URL: Documentation, https://setuptools.readthedocs.io/
Project-URL: Funding, https://donate.pypi.org

版本说明符

版本说明符是一系列条件运算符和版本号，用逗号分隔。条件运算符必须是“<”、“>”、“<=”、“>=”、“==”和“!=”之一。

可以指定任意数量的条件运算符，例如，字符串“>1.0, !=1.3.4, <2.0”是合法的版本声明。逗号（“,”）等同于and运算符。

每个版本号必须采用PEP 440中指定的格式。

当提供版本时，它总是包含所有以相同值开头的版本。例如，Python的“2.5”版本将包括“2.5.2”或“2.5.3”等版本。在这种情况下，预发布和发布后版本被排除。因此，在我们的示例中，当使用“2.5”时，不包括“2.5a1”等版本。如果需要范围的第一个版本，则必须明确给出。在我们的示例中，它将是“2.5.0”。

请注意，某些项目可能会省略“2.5.x”系列第一个版本的“.0”后缀。

• 2.5
• 2.5.1
• 2.5.2
• 等等。

在这种情况下，必须明确使用“2.5.0”以避免“2.5”表示完整范围的符号之间的任何混淆。建议对一个系列使用相同长度的方案以完全避免此问题。

一些例子

• Requires-Dist: zope.interface (3.1)：任何以3.1开头的版本，不包括发布后或预发布版本。
• Requires-Dist: zope.interface (3.1.0)：任何以3.1.0开头的版本，不包括发布后或预发布版本。由于该特定项目不使用超过3位数字，因此这也意味着“仅3.1.0发布”。
• Requires-Python: 3：任何Python 3版本，无论哪个，不包括发布后或预发布版本。
• Requires-Python: >=2.6,<3：任何Python 2.6或2.7版本，包括2.6的发布后版本，2.7的预发布和发布后版本。它不包括Python 3的预发布版本。
• Requires-Python: 2.6.2：等同于“>=2.6.2,<2.6.3”。因此这只包括Python 2.6.2。当然，如果Python用4位数字编号，它将包括2.6.2系列的所有版本。
• Requires-Python: 2.5.0：等同于“>=2.5.0,<2.5.1”。
• Requires-Dist: zope.interface (3.1,!=3.1.3)：任何以3.1开头的版本，不包括3.1的发布后或预发布版本，并且不包括任何以“3.1.3”开头的版本。对于此特定项目，这意味着：“3.1系列的任何版本但不是3.1.3”。这等同于：“>=3.1,!=3.1.3,<3.2”。

环境标记

环境标记是一种可以在字段末尾、分号（“;”）之后添加的标记，用于添加关于执行环境的条件。

以下是一些使用此类标记的字段示例

Requires-Dist: pywin32 (>1.0); sys.platform == 'win32'
Obsoletes-Dist: pywin31; sys.platform == 'win32'
Requires-Dist: foo (1,!=1.3); platform.machine == 'i386'
Requires-Dist: bar; python_version == '2.4' or python_version == '2.5'
Requires-External: libxslt; 'linux' in sys.platform

这背后的微语言尽可能简单：它只比较字符串，使用==和in运算符（以及它们的相反），并且能够组合表达式。这也使非Python程序员易于理解。

伪语法是

EXPR [in|==|!=|not in] EXPR [or|and] ...

其中EXPR属于以下任何一种

• python_version = ‘%s.%s’ % (sys.version_info[0], sys.version_info[1])
• python_full_version = sys.version.split()[0]
• os.name = os.name
• sys.platform = sys.platform
• platform.version = platform.version()
• platform.machine = platform.machine()
• platform.python_implementation = platform.python_implementation()
• 一个自由字符串，如'2.4'，或'win32'

请注意，in仅限于字符串，这意味着不可能在右侧使用元组或列表等其他序列。

受益于此标记的字段是

• Requires-External
• Requires-Dist
• Provides-Dist
• Obsoletes-Dist
• Classifier

与PEP 314的差异总结

• Metadata-Version现在是1.2。
• 添加了环境标记。
• 更改的字段
  • Platform（语法更改）
  • Author-email（更改为可选字段）
• 新增字段
  • Maintainer
  • Maintainer-email
  • Requires-Python
  • Requires-External
  • Requires-Dist
  • Provides-Dist
  • Obsoletes-Dist
  • Project-URL
• 已弃用字段
  • Requires（改为Requires-Dist）
  • Provides（改为Provides-Dist）
  • Obsoletes（改为Obsoletes-Dist）

参考资料

本文档指定元数据格式的1.2版本。1.0版本在PEP 241中指定。1.1版本在PEP 314中指定。

版权

本文档已置于公共领域。

致谢

Fred Drake、Anthony Baxter和Matthias Klose都为本PEP中提出的想法做出了贡献。

Tres Seaver、Jim Fulton、Marc-André Lemburg、Martin von Löwis、Tarek Ziadé、David Lyon以及Distutils-SIG的其他成员都为新更新版本做出了贡献。