Metadata for Python Software Packages 1.3 (#490)
This commit is contained in:
Dustin Ingram
Nick Coghlan
parent
c276a04e3b
commit
7d181dc76d
|
|
@ -0,0 +1,159 @@
|
|||
PEP: 566
|
||||
Title: Metadata for Python Software Packages 1.3
|
||||
Version: $Revision$
|
||||
Last-Modified: $Date$
|
||||
Author: Dustin Ingram <di@di.codes>
|
||||
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 packge 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.
|
||||
|
||||
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.
|
||||
|
||||
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 Colgan for contributing to this PEP.
|
||||
|
||||
|
||||
..
|
||||
Local Variables:
|
||||
mode: indented-text
|
||||
indent-tabs-mode: nil
|
||||
sentence-end-double-space: t
|
||||
fill-column: 80
|
||||
End:
|
||||
Loading…
Reference in New Issue