摘要

本 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”。

最后，此新版本还添加了 environment markers。

字段

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

标有“(可多次使用)”的字段可以在单个 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
  • 所需 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 的其他人员为新更新版本做出了贡献。