[Python-Dev] Proposing PEP 345 : Metadata for Python Software Packages 1.2

[Tarek Ziadé]

On Wed, Dec 23, 2009 at 3:31 AM, Tres Seaver <tseaver at palladion.com> wrote:
[..]
>>
>> The deprecation of the existing Requires/Provides/Obsoletes fields
>> should be more prominent - tucked away below the examples, I missed
>> these notices on the first read through (I only noticed that they
>> actually had been formally deprecated when I got to the summary of
>> differences at the end). I suggest placing the deprecation notice
>> immediately after the relevant field headers.
>
> Good point.  I thought I had done so in the initial editing pass.

I've done it yesterday.

>
>> There also needs to be an explanation in the PEP as to whether or not it
>> is legal to use both Requires and Requires-Dist (etc) in the same
>> PKG-INFO file. (i.e. what is the use case for allowing the old fields to
>> be used in a metadata v1.2 PKG-INFO file? Should PEP 345 aware packaging
>> tools just ignore the old fields, while v1.1 tools ignore the new ones?
>> Or should new tools attempt to handle both?)
>
> No tools that I know of currently use 'Requires' / 'Provides' /
> 'Obsoletes' at all:  their contents have never been informative enough
> to allow for useful automation.  For completeness sake, we can document
> that tools should ignore any 'Requires', 'Provides', or 'Obsoletes'
> fields when any of the '-Dist' versions are present.

Although some (a small number) distributions use these, so one way to
handle it is
to do a little bit like what was done when 1.1 came out:

if a "1.2" field is found and no "1.1" field is found:
    metadata 1.2 is used
if a "1.1" field is found and no "1.2" field is found:
    metadata 1.1 is used + a warning is displayed
if a "1.1" field is found and a "1.2" field is found:
    a warning is displayed and 1.2 is used, 1.1 fields are ignored
if no 1.1 field or 1.2 fields are found:
    metadata 1.2 is used

>> The various lines about there being no standards or canonical
>> definitions for particular fields also seem to run counter to the spirit
>> of the detailed guidelines in the description of each field (which imply
>> that some standards have already been adopted by convention). Perhaps
>> these comments could be softened to say that although the metadata
>> specification formally allows arbitrary strings in these fields, the
>> descriptions are recommended guidelines for creating field entries that
>> automated tools will handle correctly?
>
> That language is left over from PEP 314, which introduced those
> "advisory" fields.  The expectation of PEP 345 is that developers who
> want their packages to be easily consumable by automated tools will
> avoid the deprecated fields and use the more usefully-specifiied new ones.
>

Notice that I now provide in 2.7/3.2 a way to read *and* write
PKG-INFO from an API:

http://docs.python.org/dev/distutils/examples.html#reading-the-metadata

meaning that whatever fields a developer use, this API will let the installers
and other automated tool gets the metadata.

It might be a good thing to inform about that API in the PEP I guess,

>> Finally, as a general formatting request - some blank space between the
>> end of the previous example and the header for the next field
>> description would make the field descriptions much easier to read.
>
> Hmm, I thought we were following stock ReST formats:  perhaps the CSS
> should be adjusted to give a larger leading space to headings?

I've changed the layout yesterday, so its easier to read.

Regards
Tarek

-- 
Tarek Ziadé | http://ziade.org