Abstract

This PEP describes the changes between versions 1.2 and 2.1 of the coremetadata specification for Python packages. Version 1.2 is specified inPEP 345.

It also changes to the canonical source for field specifications to theCoreMetadata Specification reference document, which includes specifics of thefield names, and their semantics and usage.

Fields

The canonical source for the names and semantics of each of the supportedmetadata fields is theCore Metadata Specification document.

Fields marked with “(Multiple use)” may be specified multiple times in a singlePKG-INFO file. Other fields may only occur once in a PKG-INFO file. Fieldsmarked with “(optional)” are not required to appear in a valid PKG-INFO file;all other fields must be present.

Version Specifiers

Version numbering requirements and the semantics for specifying comparisonsbetween versions are defined inPEP 440. Direct references as defined inPEP 440 are also permitted as an alternative to version specifiers.

FollowingPEP 508, version specifiers no longer need to be surrounded byparentheses in the fields Requires-Dist, Provides-Dist, Obsoletes-Dist orRequires-External, so e.g.requests>=2.8.1 is now a valid value.The recommended format is without parentheses, but tools parsing metadata shouldalso be able to handle version specifiers in parentheses. Further, public indexservers MAY prohibit strict version matching clauses or direct references inthese fields.

Usage of version specifiers is otherwise unchanged fromPEP 345.

Environment markers

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.

The environment marker format used to declare such a condition is defined inthe environment markers section ofPEP 508.

Usage of environment markers is otherwise unchanged fromPEP 345.

JSON-compatible Metadata

It may be necessary to store metadata in a data structure which does notallow for multiple repeated keys, such as JSON.

The canonical method to transform metadata fields into such a data structure isas follows:

1. The original key-value format should be read withemail.parser.HeaderParser;
2. All transformed keys should be reduced to lower case. Hyphens should bereplaced with underscores, but otherwise should retain all other characters;
3. The transformed value for any field marked with “(Multiple-use”) should be asingle list containing all the original values for the given key;
4. TheKeywords field should be converted to a list by splitting theoriginal value on commas;
5. The message body, if present, should be set to the value of thedescription key.
6. The result should be stored as a string-keyed dictionary.

Summary of Differences From PEP 345

• Metadata-Version is now 2.1.
• Fields are now specified via theCore Metadata Specification.
• Added two new fields:Description-Content-Type andProvides-Extra
• Acceptable values for theName field are now specified as perPEP 508.
• Added canonical method of transformation into JSON-compatible data structure.

References

This document specifies version 2.1 of the metadata format.Version 1.0 is specified inPEP 241.Version 1.1 is specified inPEP 314.Version 1.2 is specified inPEP 345.Version 2.0, while not formally accepted, was specified inPEP 426.

Copyright

This document has been placed in the public domain.

Acknowledgements

Thanks to Alyssa Coghlan and Thomas Kluyver for contributing to this PEP.