Important
This PEP is a historical document. The up-to-date, canonical spec,Core metadata specifications, is maintained on thePyPA specs page.
×
See thePyPA specification update process for how to propose changes.
This PEP describes a mechanism for adding metadata to Python distributions.It includes specifics of the field names, and their semantics andusage.
This document specifies version 1.2 of the metadata format.Version 1.0 is specified inPEP 241.Version 1.1 is specified inPEP 314.
Version 1.2 of the metadata format adds a number of optional fieldsdesigned to make third-party packaging of Python Software easier.These fields are “Requires-Python”, “Requires-External”, “Requires-Dist”,“Provides-Dist”, and “Obsoletes-Dist”. This version also changes the“Platform” field. Three new fields were also added: “Maintainer”,“Maintainer-email” and “Project-URL”.
Last, this new version also addsenvironmentmarkers.
This section specifies the names and semantics of each of thesupported metadata fields.
Fields marked with “(Multiple use)” may be specified multipletimes in a single PKG-INFO file. Other fields may only occuronce in a PKG-INFO file. Fields marked with “(optional)” arenot required to appear in a valid PKG-INFO file; all otherfields must be present.
Version of the file format; “1.2” is the only legal value.
Example:
Metadata-Version:1.2
The name of the distributions.
Example:
Name:BeagleVote
A string containing the distribution’s version number. Thisfield must be in the format specified inPEP 440.
Example:
Version:1.0a2
A Platform specification describing an operating system supported bythe distribution which is not listed in the “Operating System” Trove classifiers.See “Classifier” below.
Examples:
Platform:ObscureUnixPlatform:RareDOS
Binary distributions containing a PKG-INFO file will use theSupported-Platform field in their metadata to specify the OS andCPU for which the binary distribution was compiled. The semantics ofthe Supported-Platform field are not specified in this PEP.
Example:
Supported-Platform:RedHat7.2Supported-Platform:i386-win32-2791
A one-line summary of what the distribution does.
Example:
Summary:Amoduleforcollectingvotesfrombeagles.
A longer description of the distribution that can run to severalparagraphs. Software that deals with metadata should not assumeany maximum size for this field, though people shouldn’t includetheir instruction manual as the description.
The contents of this field can be written using reStructuredTextmarkup[1]. For programs that work with the metadata, supportingmarkup is optional; programs can also display the contents of thefield as-is. This means that authors should be conservative inthe markup they use.
To support empty lines and lines with indentation with respect totheRFC 822 format, any CRLF character has to be suffixed by 7 spacesfollowed by a pipe (“|”) char. As a result, the Description field isencoded into a folded field that can be interpreted byRFC 822#section-3.1.1parser.
Example:
Description: This project provides powerful math functions |For example, you can use ``sum()`` to sum numbers: | |Example:: | | >>> sum(1, 2) | 3 |
This encoding implies that any occurrences of a CRLF followed by 7 spacesand a pipe char have to be replaced by a single CRLF when the field is unfoldedusing aRFC 822 reader.
A list of additional keywords to be used to assist searchingfor the distribution in a larger catalog.
Example:
Keywords:dogpuppyvotingelection
A string containing the URL for the distribution’s home page.
Example:
Home-page:http://www.example.com/~cschultz/bvote/
A string containing the URL from which this version of the distributioncan be downloaded. (This means that the URL can’t be something like“…/BeagleVote-latest.tgz”, but instead must be “…/BeagleVote-0.45.tgz”.)
A string containing the author’s name at a minimum; additionalcontact information may be provided.
Example:
Author:C.Schultz,UniversalFeaturesSyndicate,LosAngeles,CA<cschultz@peanuts.example.com>
A string containing the author’s e-mail address. It can containa name and e-mail address in the legal forms for aRFC 822From: header.
Example:
Author-email:"C. Schultz"<cschultz@example.com>
A string containing the maintainer’s name at a minimum; additionalcontact information may be provided.
Note that this field is intended for use when a project is beingmaintained by someone other than the original author: it should beomitted if it is identical toAuthor.
Example:
Maintainer:C.Schultz,UniversalFeaturesSyndicate,LosAngeles,CA<cschultz@peanuts.example.com>
A string containing the maintainer’s e-mail address. It can containa name and e-mail address in the legal forms for aRFC 822From: header.
Note that this field is intended for use when a project is beingmaintained by someone other than the original author: it should beomitted if it is identical toAuthor-email.
Example:
Maintainer-email:"C. Schultz"<cschultz@example.com>
Text indicating the license covering the distribution where the licenseis not a selection from the “License” Trove classifiers. See“Classifier” below. This field may also be used to specify aparticular version of a license which is named via theClassifierfield, or to indicate a variation or exception to such a license.
Examples:
License:Thissoftwaremayonlybeobtainedbysendingtheauthorapostcard,andthentheuserpromisesnottoredistributeit.License:GPLversion3,excludingDRMprovisions
Each entry is a string giving a single classification valuefor the distribution. Classifiers are described inPEP 301.
Examples:
Classifier:DevelopmentStatus::4-BetaClassifier:Environment::Console(TextBased)
Each entry contains a string naming some other distutilsproject required by this distribution.
The format of a requirement string is identical to that of adistutils project name (e.g., as found in theName: field.optionally followed by a version declaration within parentheses.
The distutils project names should correspond to names as foundon thePython Package Index.
Version declarations must follow the rules described inVersion Specifiers
Examples:
Requires-Dist:pkginfoRequires-Dist:PasteDeployRequires-Dist:zope.interface(>3.5.0)
Each entry contains a string naming a Distutils project whichis contained within this distribution. This fieldmust includethe project identified in theName field, followed by theversion : Name (Version).
A distribution may provide additional names, e.g. to indicate thatmultiple projects have been bundled together. For instance, sourcedistributions of theZODB project have historically includedthetransaction project, which is now available as a separatedistribution. Installing such a source distribution satisfiesrequirements for bothZODB andtransaction.
A distribution may also provide a “virtual” project name, which doesnot correspond to any separately-distributed project: such a namemight be used to indicate an abstract capability which could be suppliedby one of multiple projects. E.g., multiple projects might supplyRDBMS bindings for use by a given ORM: each project might declarethat it providesORM-bindings, allowing other projects to dependonly on having at most one of them installed.
A version declaration may be supplied and must follow the rules describedinVersion Specifiers. The distribution’s version number will be impliedif none is specified.
Examples:
Provides-Dist:OtherProjectProvides-Dist:AnotherProject(3.4)Provides-Dist:virtual_package
Each entry contains a string describing a distutils project’s distributionwhich this distribution renders obsolete, meaning that the two projectsshould not be installed at the same time.
Version declarations can be supplied. Version numbers must be in theformat specified inVersion Specifiers.
The most common use of this field will be in case a project namechanges, e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0.When you install Torqued Python, the Gorgon distribution should beremoved.
Examples:
Obsoletes-Dist:GorgonObsoletes-Dist:OtherProject(<3.0)
This field specifies the Python version(s) that the distribution isguaranteed to be compatible with.
Version numbers must be in the format specified inVersion Specifiers.
Examples:
Requires-Python:2.5Requires-Python:>2.1Requires-Python:>=2.3.4Requires-Python:>=2.5,<2.7
Each entry contains a string describing some dependency in thesystem that the distribution is to be used. This field is intended toserve as a hint to downstream project maintainers, and has nosemantics which are meaningful to thedistutils distribution.
The format of a requirement string is a name of an externaldependency, optionally followed by a version declaration withinparentheses.
Because they refer to non-Python software releases, version numbersfor this field arenot required to conform to the formatspecified inPEP 440: they should correspond to theversion scheme used by the external dependency.
Notice that there’s is no particular rule on the strings to be used.
Examples:
Requires-External:CRequires-External:libpng(>=1.5)
A string containing an extra URL for the project and a label for it,separated by a comma. This should be used when there are other URLsto list in the metadata in addition to the “Home-page” field.
Examples:
Project-URL:BugTracker,https://github.com/pypa/setuptools/issuesProject-URL:Documentation,https://setuptools.readthedocs.io/Project-URL:Funding,https://donate.pypi.org
The label is free text, with a maximum length of 32 characters. Noticethat distributions uploaded to PyPI will have these extra entriesdisplayed under the “Project links” section of their landing page.
Version specifiers are a series of conditional operators andversion numbers, separated by commas. Conditional operatorsmust be one of “<”, “>”, “<=”, “>=”, “==” and “!=”.
Any number of conditional operators can be specified, e.g.the string “>1.0, !=1.3.4, <2.0” is a legal version declaration.The comma (“,”) is equivalent to theand operator.
Each version number must be in the format specified inPEP 440.
When a version is provided, it always includes all versions thatstarts with the same value. For example, the “2.5” version of Pythonwill include versions like “2.5.2” or “2.5.3”. Pre and post releasesin that case are excluded. So in our example, versions like “2.5a1” arenot included when “2.5” is used. If the first version of the range isrequired, it has to be explicitly given. In our example, it will be“2.5.0”.
Notice that some projects might omit the “.0” suffix for the first releaseof the “2.5.x” series:
In that case, “2.5.0” will have to be explicitly used to avoid any confusionbetween the “2.5” notation that represents the full range. It is a recommendedpractice to use schemes of the same length for a series to completely avoidthis problem.
Some Examples:
Requires-Dist:zope.interface(3.1): any version that starts with 3.1,excluding post or pre-releases.Requires-Dist:zope.interface(3.1.0): any version that starts with3.1.0, excluding post or pre-releases. Since that particular project doesn’tuse more than 3 digits, it also means “only the 3.1.0 release”.Requires-Python:3: Any Python 3 version, no matter which one, excludingpost or pre-releases.Requires-Python:>=2.6,<3: Any version of Python 2.6 or 2.7, includingpost releases of 2.6, pre and post releases of 2.7. It excludes pre releasesof Python 3.Requires-Python:2.6.2: Equivalent to “>=2.6.2,<2.6.3”. So this includesonly Python 2.6.2. Of course, if Python was numbered with 4 digits, it wouldhave include all versions of the 2.6.2 series.Requires-Python:2.5.0: Equivalent to “>=2.5.0,<2.5.1”.Requires-Dist:zope.interface(3.1,!=3.1.3): any version that starts with3.1, excluding post or pre-releases of 3.1and excluding any version thatstarts with “3.1.3”. For this particular project, this means: “any versionof the 3.1 series but not 3.1.3”. This is equivalent to:“>=3.1,!=3.1.3,<3.2”.Anenvironment marker is a marker that can be added at the end of afield after a semi-colon (“;”), to add a condition about the executionenvironment.
Here are some example of fields using such markers:
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'orpython_version=='2.5'Requires-External:libxslt;'linux'insys.platform
The micro-language behind this is the simplest possible: it compares onlystrings, with the== andin operators (and their opposites), andwith the ability to combine expressions. It makes it also easy to understandto non-pythoneers.
The pseudo-grammar is
EXPR[in|==|!=|notin] EXPR[or|and]...
whereEXPR belongs to any of those:
'2.4', or'win32'Notice thatin is restricted to strings, meaning that it is not possibleto use other sequences like tuples or lists on the right side.
The fields that benefit from this marker are:
This document specifies version 1.2 of the metadata format.Version 1.0 is specified inPEP 241.Version 1.1 is specified inPEP 314.
This document has been placed in the public domain.
Fred Drake, Anthony Baxter and Matthias Klose have all contributed tothe ideas presented in this PEP.
Tres Seaver, Jim Fulton, Marc-André Lemburg, Martin von Löwis, Tarek Ziadé,David Lyon and other people at the Distutils-SIG have contributed to thenew updated version.
Source:https://github.com/python/peps/blob/main/peps/pep-0345.rst
Last modified:2025-02-01 08:55:40 GMT