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

[Daniel Holth]

On Fri, Sep 14, 2012 at 1:43 PM, Erik Bray <erik.m.bray at gmail.com> wrote:
> 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

The .dist-info design asks for every metadata file (the one in all
caps, not any of the other metadata in .dist-info) to be parsed for
many packaging operations that do not require the description, such as
resolving the dependency graph of a package. Description-File would
give an installer the option to pull Description: out into
Description-File:. I would expect the concatenation to happen before
this point.

I would like to forbid subdirectories in .dist-info but I think they
are allowed.

The order of multi-use fields is probably preserved. I don't think it
is required to be by any spec.