165 lines
5.0 KiB
Plaintext
165 lines
5.0 KiB
Plaintext
PEP: 566
|
||
Title: Metadata for Python Software Packages 1.3
|
||
Version: $Revision$
|
||
Last-Modified: $Date$
|
||
Author: Dustin Ingram <di@di.codes>
|
||
BDFL-Delegate: Daniel Holth
|
||
Discussions-To: distutils-sig <distutils-sig at python.org>
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Content-Type: text/x-rst
|
||
Created: 1-Dec-2017
|
||
Python-Version: 3.x
|
||
Post-History:
|
||
Replaces: 345
|
||
|
||
|
||
Abstract
|
||
========
|
||
|
||
This PEP describes the changes between versions 1.2 and 1.3 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 1.3
|
||
------------------
|
||
|
||
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 1.3
|
||
----------------------
|
||
|
||
Name
|
||
::::
|
||
|
||
The specification for the format of this field is now identical to the
|
||
distribution name specification defined in PEP 508.
|
||
|
||
Version Specifiers
|
||
==================
|
||
|
||
Version numbering requirements and the semantics for specifying comparisons
|
||
between versions are defined in PEP 440.
|
||
|
||
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, 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 whitespace characters;
|
||
#. The result should be stored as a string-keyed dictionary.
|
||
|
||
Summary of Differences From PEP 345
|
||
===================================
|
||
|
||
* Metadata-Version is now 1.3.
|
||
|
||
* 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 1.3 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.
|
||
|
||
.. _`Core Metadata Specification`:
|
||
https://packaging.python.org/specifications/core-metadata/
|
||
|
||
Copyright
|
||
=========
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
Acknowledgements
|
||
================
|
||
|
||
Thanks to Nick Coghlan for contributing to this PEP.
|
||
|
||
|
||
..
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
sentence-end-double-space: t
|
||
fill-column: 80
|
||
End:
|