[Python-Dev] Edits to Metadata 1.2 to add extras (optional dependencies)

[Erik Bray]

On Fri, Sep 14, 2012 at 12:30 PM, Daniel Holth <dholth at gmail.com> wrote:
> Add to metadata 1.3:
>
> Description-File: README(\..+)?
>
> Meaning the description should be read from a file in the same
> directory as PKG-INFO or METADATA (including in the .dist-info
> directories) and we strongly recommend it be named as README.* and be
> utf-8 encoded text.
>
> Description: is the only multi-line field in the metadata. It is
> almost never needed at runtime. It would be great for performance and
> simplify the parser to just put it in another file.
>
> Mutually exclusive with Description.
>
> May beg for a Summary: tag with a one-line description.

Can we make Description-File multiple-use?  The meaning of this would
be that the Description is formed from concatenating each
Description-File in order.  That raises the question: Is ordering
guaranteed for multiple-use fields?

I ask, because distutils2 supports exactly such a feature, and I've
found it useful.  For example, if I have a README.rst and a
CHANGELOG.rst I can specify:

description-file =
    README.rst
    CHANGELOG.rst

Then the full description, contains my readme and my changelog, which
look nice together on PyPI, but I prefer to keep as separate files in
the source.

My only other concern is that if the value of this field can
theoretically be arbitrary, it could conflict with other .dist-info
files.  Does the .dist-info format allow subdirectories?  Placing
description-files in a subdirectory of .dist-info could be a
reasonable workaround.

Erik