[Python-Dev] PEP 426 comment: field order

[Daniel Holth]

Added some notes about the (lack of) ordering.

The email module provides an ordered multidict interface to the data.
The first tag wins (if you improperly define Name: twice for example),
but the order of everything is preserved. We just don't need it,
except that it might be surprising to see your classifiers randomly
re-ordered.

It is also possible to textwrap.dedent(p['Description']) with p =
email.parser.Parser().parsestr(metadata).

I don't really expect anyone to use email.parser.Parser() so I'm
hesitant to mention it, but it seems to work. I say it's read-only
because the 3.2 Parser()/Generator() can't reserialize it due to
Unicode. The improved Python 3.3 email module would be able to under
the right conditions.


diff -r 79e95f487a33 -r 4773b6b3e8f2 pep-0426.txt
--- a/pep-0426.txt      Thu Oct 18 08:31:44 2012 +0100
+++ b/pep-0426.txt      Thu Oct 18 21:10:26 2012 -0400
@@ -33,10 +33,14 @@

 The syntax defined in this PEP is for use with Python distribution
 metadata files. The file format is a simple UTF-8 encoded Key: value
-format with no maximum line length. It is parsable by the ``email``
+format with no maximum line length.  It is parseable by the ``email``
 module with an appropriate ``email.policy.Policy()``.  The field names
 listed in the `Fields`_ section are used as the header names.

+In Python 3.2, a serviceable read-only parser is::
+
+    email.parser.Parser().parsestr(metadata)
+
 There are two standard locations for these metadata files:

 * the ``PKG-INFO`` file included in the base directory of Python
@@ -66,7 +70,8 @@
 times in a single metadata file.  Other fields may only occur
 once in a metadata file.  Fields marked with "(optional)" are
 not required to appear in a valid metadata file; all other
-fields must be present.
+fields must be present.  The fields may appear in any order within
+the file.

 Metadata-Version
 ::::::::::::::::
@@ -480,12 +485,17 @@

 An ASCII string, not containing whitespace or the / character, that
 indicates the presence of extended metadata. Additional tags defined by
-the extension should be of the form string/Name::
+an `Extension: Chili` should be of the form `Chili/Name`::

     Extension: Chili
     Chili/Type: Poblano
     Chili/Heat: Mild

+An implementation might iterate over all the declared `Extension:`
+fields to invoke the processors for those extensions.  As the order of
+the fields is not used, the `Extension: Chili` field may appear before
+or after its declared tags `Chili/Type:` etc.
+