Bump PEP 426 metadata version to 2.0
This commit is contained in:
Nick Coghlan
parent
e549370b98
commit
ff5d03aef4
51
pep-0426.txt
51
pep-0426.txt
|
|
@ -1,5 +1,5 @@
|
|||
PEP: 426
|
||||
Title: Metadata for Python Software Packages 1.3
|
||||
Title: Metadata for Python Software Packages 2.0
|
||||
Version: $Revision$
|
||||
Last-Modified: $Date$
|
||||
Author: Daniel Holth <dholth@fastmail.fm>,
|
||||
|
|
@ -21,12 +21,12 @@ This PEP describes a mechanism for adding metadata to Python distributions.
|
|||
It includes specifics of the field names, and their semantics and
|
||||
usage.
|
||||
|
||||
This document specifies version 1.3 of the metadata format.
|
||||
This document specifies version 2.0 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 1.3 of the metadata format adds fields designed to make
|
||||
Version 2.0 of the metadata format adds fields designed to make
|
||||
third-party packaging of Python Software easier and defines a formal
|
||||
extension mechanism. It also adds support for optional features of
|
||||
distributions and allows the description to be placed into a payload
|
||||
|
|
@ -65,7 +65,7 @@ Other tools involved in Python distribution may also use this format.
|
|||
Encoding
|
||||
========
|
||||
|
||||
Metadata 1.3 files are UTF-8 with the restriction that keys must be
|
||||
Metadata 2.0 files are UTF-8 with the restriction that keys must be
|
||||
ASCII. Parser implementations should be aware that older versions of
|
||||
the Metadata specification do not specify an encoding.
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ Metadata header fields
|
|||
This section specifies the names and semantics of each of the
|
||||
supported fields in the metadata header.
|
||||
|
||||
In a single Metadata 1.3 file, fields marked with "(optional)" may occur
|
||||
In a single Metadata 2.0 file, fields marked with "(optional)" may occur
|
||||
0 or 1 times. Fields marked with "(multiple use)" may be specified
|
||||
0, 1 or more times. Only "Metadata-Version", "Name", "Version", and
|
||||
"Summary" must appear exactly once.
|
||||
|
|
@ -87,11 +87,15 @@ The fields may appear in any order within the header section of the file.
|
|||
Metadata-Version
|
||||
----------------
|
||||
|
||||
Version of the file format; "1.3" is the only legal value.
|
||||
Version of the file format; "2.0" is the only legal value.
|
||||
|
||||
Automated tools should warn if ``Metadata-Version`` is greater than the
|
||||
highest version they support, and must fail if ``Metadata-Version`` has
|
||||
a greater major version than the highest version they support.
|
||||
|
||||
Example::
|
||||
|
||||
Metadata-Version: 1.3
|
||||
Metadata-Version: 2.0
|
||||
|
||||
|
||||
Name
|
||||
|
|
@ -144,7 +148,7 @@ Examples::
|
|||
Description (optional, deprecated)
|
||||
----------------------------------
|
||||
|
||||
Starting with Metadata 1.3, the recommended place for the description is in
|
||||
Starting with Metadata 2.0, the recommended place for the description is in
|
||||
the payload section of the document, after the last header. The description
|
||||
does not need to be reformatted when it is included in the payload.
|
||||
|
||||
|
|
@ -1196,7 +1200,8 @@ defined in a new PEP.
|
|||
Summary of differences from \PEP 345
|
||||
====================================
|
||||
|
||||
* Metadata-Version is now 1.3
|
||||
* Metadata-Version is now 2.0, with semantics specified for handling
|
||||
version changes
|
||||
|
||||
* Most fields are now optional
|
||||
|
||||
|
|
@ -1263,6 +1268,26 @@ Summary of differences from \PEP 345
|
|||
The rationale for major changes is given in the following sections.
|
||||
|
||||
|
||||
Metadata-Version semantics
|
||||
--------------------------
|
||||
|
||||
The semantics of major and minor version increments are now specified,
|
||||
and follow the same model as the format version semantics specified for
|
||||
the wheel format in PEP 427: minor version increments must behave
|
||||
reasonably when processed by a tool that only understand earlier metadata
|
||||
versions with the same major version, while major version increments
|
||||
may include changes that are not compatible with existing tools.
|
||||
|
||||
The major version number of the specification has been incremented
|
||||
accordingly, as interpreting PEP 426 metadata in accordance with earlier
|
||||
metadata specifications is unlikely to give the expected behaviour.
|
||||
|
||||
Whenever the major version number of the specification is incremented, it
|
||||
is expected that deployment will take some time, as metadata consuming tools
|
||||
much be updated before other tools can safely start producing the new
|
||||
format.
|
||||
|
||||
|
||||
Standard encoding and other format clarifications
|
||||
-------------------------------------------------
|
||||
|
||||
|
|
@ -1491,7 +1516,7 @@ format.
|
|||
References
|
||||
==========
|
||||
|
||||
This document specifies version 1.3 of the metadata format.
|
||||
This document specifies version 2.0 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.
|
||||
|
|
@ -1513,10 +1538,10 @@ justifications for needing such a standard can be found in PEP 386.
|
|||
Appendix
|
||||
========
|
||||
|
||||
Parsing and generating the Metadata 1.3 serialization format using
|
||||
Parsing and generating the Metadata 2.0 serialization format using
|
||||
Python 3.3::
|
||||
|
||||
# Metadata 1.3 demo
|
||||
# Metadata 2.0 demo
|
||||
from email.generator import Generator
|
||||
from email import header
|
||||
from email.parser import Parser
|
||||
|
|
@ -1545,7 +1570,7 @@ Python 3.3::
|
|||
import textwrap
|
||||
|
||||
pkg_info = """\
|
||||
Metadata-Version: 1.3
|
||||
Metadata-Version: 2.0
|
||||
Name: package
|
||||
Version: 0.1.0
|
||||
Summary: A package.
|
||||
|
|
|
|||
Loading…
Reference in New Issue