Package metadata: which fields are optional
The core metadata specification (https://packaging.python.org/specifications/core-metadata/ ) notes whether each field is optional. However there are some discrepancies with my understanding: - Download-URL is not marked as optional, but in practice it's obsolete (since PEP 470) and not very helpful (there may be different places to download the same package). Flit has never set this, and I have had no bug reports about it, so in practice it definitely is optional. - Requires-Python is not marked as optional, though I'm pretty sure it also is in practice. - Only one of the multiple use fields is explicitly marked as optional, but my understanding is that 'multiple use' includes using them zero times, so they are all optional. I propose that we remove 'optional' from all the headings, and note at the top of the specification that the required fields are: - Metadata-Version - Name - Version - Summary (And we should check if Summary is really required) Thomas
On Apr 15, 2018, at 3:31 AM, Thomas Kluyver <thomas@kluyver.me.uk> wrote:
The core metadata specification (https://packaging.python.org/specifications/core-metadata/ ) notes whether each field is optional. However there are some discrepancies with my understanding:
- Download-URL is not marked as optional, but in practice it's obsolete (since PEP 470) and not very helpful (there may be different places to download the same package). Flit has never set this, and I have had no bug reports about it, so in practice it definitely is optional. - Requires-Python is not marked as optional, though I'm pretty sure it also is in practice. - Only one of the multiple use fields is explicitly marked as optional, but my understanding is that 'multiple use' includes using them zero times, so they are all optional.
I propose that we remove 'optional' from all the headings, and note at the top of the specification that the required fields are: - Metadata-Version - Name - Version - Summary
In PyPI, basically only Metadata-Version, Name, and Version are required. I’m +1 on this, in practice what distutils does is for any “mandatory” field that wasn’t filled out, it would give it an implicit value of “UNKNOWN” (this include Name and Version amusingly enough, but Unknown is already taken on PyPI and Unknown isn’t a valid version anymore). So while it was *technically* set, it was set to a garbage value and thus, for all intents and purposes, optional anyways. We just had a funny way of saying that it didn’t exist.
On 15 April 2018 at 17:31, Thomas Kluyver <thomas@kluyver.me.uk> wrote:
The core metadata specification (https://packaging.python.org/specifications/core-metadata/ ) notes whether each field is optional. However there are some discrepancies with my understanding:
- Download-URL is not marked as optional, but in practice it's obsolete (since PEP 470) and not very helpful (there may be different places to download the same package). Flit has never set this, and I have had no bug reports about it, so in practice it definitely is optional. - Requires-Python is not marked as optional, though I'm pretty sure it also is in practice. - Only one of the multiple use fields is explicitly marked as optional, but my understanding is that 'multiple use' includes using them zero times, so they are all optional.
I propose that we remove 'optional' from all the headings, and note at the top of the specification that the required fields are: - Metadata-Version - Name - Version - Summary
(And we should check if Summary is really required)
That all sounds like a good idea to me. With the heading adjustments, it would be worth adding the relevant Sphinx labels so that the current anchors still resolve to the right place. For example, the current Keywords anchor is https://packaging.python.org/specifications/core-metadata/#keywords-optional. With this change, it will become https://packaging.python.org/specifications/core-metadata/#keywords. Adding a ".. _keywords-optional:" label before the heading will preserve the old links. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Thanks. I've opened a PR for it: https://github.com/pypa/python-packaging-user-guide/pull/469 For now, I haven't listed 'Summary' as a required field, but I'm not 100% sure of this. Donald says PyPI doesn't check that it's there, but if all (or almost all) distributions have it anyway, maybe we should enforce that it's always there. Thomas On Sun, Apr 15, 2018, at 8:57 AM, Nick Coghlan wrote:
On 15 April 2018 at 17:31, Thomas Kluyver <thomas@kluyver.me.uk> wrote:
The core metadata specification (https://packaging.python.org/specifications/core-metadata/ ) notes whether each field is optional. However there are some discrepancies with my understanding:
- Download-URL is not marked as optional, but in practice it's obsolete (since PEP 470) and not very helpful (there may be different places to download the same package). Flit has never set this, and I have had no bug reports about it, so in practice it definitely is optional. - Requires-Python is not marked as optional, though I'm pretty sure it also is in practice. - Only one of the multiple use fields is explicitly marked as optional, but my understanding is that 'multiple use' includes using them zero times, so they are all optional.
I propose that we remove 'optional' from all the headings, and note at the top of the specification that the required fields are: - Metadata-Version - Name - Version - Summary
(And we should check if Summary is really required)
That all sounds like a good idea to me.
With the heading adjustments, it would be worth adding the relevant Sphinx labels so that the current anchors still resolve to the right place. For example, the current Keywords anchor is https://packaging.python.org/specifications/core-metadata/#keywords-optional. With this change, it will become https://packaging.python.org/specifications/core-metadata/#keywords. Adding a ".. _keywords-optional:" label before the heading will preserve the old links.
Cheers, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 16 April 2018 at 02:44, Thomas Kluyver <thomas@kluyver.me.uk> wrote:
Thanks. I've opened a PR for it:
https://github.com/pypa/python-packaging-user-guide/pull/469
For now, I haven't listed 'Summary' as a required field, but I'm not 100% sure of this. Donald says PyPI doesn't check that it's there, but if all (or almost all) distributions have it anyway, maybe we should enforce that it's always there.
It's easy enough for consuming tools to default Summary to being the same as Name, so I'm OK with making it officially optional. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
participants (3)
-
Donald Stufft -
Nick Coghlan -
Thomas Kluyver