188 lines
6.1 KiB
ReStructuredText
188 lines
6.1 KiB
ReStructuredText
PEP: 566
|
||
Title: Metadata for Python Software Packages 2.1
|
||
Author: Dustin Ingram <di@python.org>
|
||
BDFL-Delegate: Daniel Holth
|
||
Discussions-To: distutils-sig@python.org
|
||
Status: Final
|
||
Type: Standards Track
|
||
Topic: Packaging
|
||
Content-Type: text/x-rst
|
||
Created: 01-Dec-2017
|
||
Python-Version: 3.x
|
||
Post-History:
|
||
Replaces: 345
|
||
Resolution: https://mail.python.org/pipermail/distutils-sig/2018-February/032014.html
|
||
|
||
|
||
.. canonical-pypa-spec:: :ref:`packaging:core-metadata`
|
||
|
||
|
||
Abstract
|
||
========
|
||
|
||
This PEP describes the changes between versions 1.2 and 2.1 of the core
|
||
metadata specification for Python packages. Version 1.2 is specified in
|
||
:pep:`345`.
|
||
|
||
It also changes to the canonical source for field specifications to the `Core
|
||
Metadata Specification`_ reference document, which includes specifics of the
|
||
field names, and their semantics and usage.
|
||
|
||
Fields
|
||
======
|
||
|
||
The canonical source for the names and semantics of each of the supported
|
||
metadata fields is the `Core Metadata Specification`_ document.
|
||
|
||
Fields marked with "(Multiple use)" may be specified multiple times in a single
|
||
PKG-INFO file. Other fields may only occur once in a PKG-INFO file. Fields
|
||
marked with "(optional)" are not required to appear in a valid PKG-INFO file;
|
||
all other fields must be present.
|
||
|
||
New in Version 2.1
|
||
------------------
|
||
|
||
Description-Content-Type (optional)
|
||
:::::::::::::::::::::::::::::::::::
|
||
|
||
A string stating the markup syntax (if any) used in the distribution's
|
||
description, so that tools can intelligently render the description.
|
||
|
||
Historically, tools like PyPI assume that a package's description is formatted
|
||
in `reStructuredText (reST)
|
||
<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_, and
|
||
fall back on plain text if the description is not valid reST.
|
||
|
||
The introduction of this field allows PyPI to support additional types of
|
||
markup syntax, and not need to make this assumption.
|
||
|
||
The full specification for this field is defined in the `Core Metadata
|
||
Specification`_.
|
||
|
||
|
||
Provides-Extra (optional, multiple use)
|
||
:::::::::::::::::::::::::::::::::::::::
|
||
|
||
A string containing the name of an optional feature. Must be a valid Python
|
||
identifier. May be used to make a dependency conditional on whether the
|
||
optional feature has been requested.
|
||
|
||
This introduction of this field allows package installation tools (such as
|
||
``pip``) to determine which extras are provided by a given package, and so that
|
||
package publication tools (such as ``twine``) can check for issues with
|
||
environment markers which use extras.
|
||
|
||
The full specification for this field is defined in the `Core Metadata
|
||
Specification`_.
|
||
|
||
Changed in Version 2.1
|
||
----------------------
|
||
|
||
Name
|
||
::::
|
||
|
||
The specification for the format of this field is now identical to the
|
||
distribution name specification defined in :pep:`508`.
|
||
|
||
Description
|
||
:::::::::::
|
||
|
||
In addition to the ``Description`` header field, the distribution's
|
||
description may instead be provided in the message body (i.e., after a
|
||
completely blank line following the headers, with no indentation or other
|
||
special formatting necessary).
|
||
|
||
Version Specifiers
|
||
==================
|
||
|
||
Version numbering requirements and the semantics for specifying comparisons
|
||
between versions are defined in :pep:`440`. Direct references as defined in
|
||
:pep:`440` are also permitted as an alternative to version specifiers.
|
||
|
||
Following :pep:`508`, version specifiers no longer need to be surrounded by
|
||
parentheses in the fields Requires-Dist, Provides-Dist, Obsoletes-Dist or
|
||
Requires-External, so e.g. ``requests >= 2.8.1`` is now a valid value.
|
||
The recommended format is without parentheses, but tools parsing metadata should
|
||
also be able to handle version specifiers in parentheses. Further, public index
|
||
servers MAY prohibit strict version matching clauses or direct references in
|
||
these fields.
|
||
|
||
Usage of version specifiers is otherwise unchanged from :pep:`345`.
|
||
|
||
Environment markers
|
||
===================
|
||
|
||
An **environment marker** is a marker that can be added at the end of a
|
||
field after a semi-colon (";"), to add a condition about the execution
|
||
environment.
|
||
|
||
The environment marker format used to declare such a condition is defined in
|
||
the environment markers section of :pep:`508`.
|
||
|
||
Usage of environment markers is otherwise unchanged from :pep:`345`.
|
||
|
||
JSON-compatible Metadata
|
||
========================
|
||
|
||
It may be necessary to store metadata in a data structure which does not
|
||
allow for multiple repeated keys, such as JSON.
|
||
|
||
The canonical method to transform metadata fields into such a data structure is
|
||
as follows:
|
||
|
||
#. The original key-value format should be read with
|
||
``email.parser.HeaderParser``;
|
||
#. All transformed keys should be reduced to lower case. Hyphens should be
|
||
replaced with underscores, but otherwise should retain all other characters;
|
||
#. The transformed value for any field marked with "(Multiple-use") should be a
|
||
single list containing all the original values for the given key;
|
||
#. The ``Keywords`` field should be converted to a list by splitting the
|
||
original value on commas;
|
||
#. The message body, if present, should be set to the value of the
|
||
``description`` key.
|
||
#. 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 the `Core Metadata Specification`_.
|
||
|
||
* Added two new fields: ``Description-Content-Type`` and ``Provides-Extra``
|
||
|
||
* Acceptable values for the ``Name`` field are now specified as per :pep:`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 in :pep:`241`.
|
||
Version 1.1 is specified in :pep:`314`.
|
||
Version 1.2 is specified in :pep:`345`.
|
||
Version 2.0, while not formally accepted, was specified in :pep:`426`.
|
||
|
||
.. _`Core Metadata Specification`:
|
||
https://packaging.python.org/specifications/core-metadata/
|
||
|
||
Copyright
|
||
=========
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
Acknowledgements
|
||
================
|
||
|
||
Thanks to Alyssa Coghlan and Thomas Kluyver for contributing to this PEP.
|
||
|
||
|
||
..
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
sentence-end-double-space: t
|
||
fill-column: 80
|
||
End:
|