AFAICT the only missing feature from old-Metadata-2.0 is "description as message body", which places readable description text after the key/value pairs. On Wed, Jan 10, 2018 at 8:45 AM Thomas Kluyver wrote:

I hope everyone has had a good break. :-)

I'd like to see PEP 566 move forwards. From the last thread, I think people were mostly happy with it as stands, but there were some proposals to introduce further metadata changes. I'd suggest that we finalise the PEP as it currently stands, and save up other changes for a future metadata revision.

One change I would like to the current text is to make more explicit that the format of several fields allowing version specifiers (Requires-Dist, Provides-Dist, Obsoletes-Dist, Requires-External) has changed, as PEP 508 removes the need for parentheses around the version specifier.

The section on version specifiers currently refers to PEP 440, which doesn't mention the parentheses at all, and says they are otherwise unchanged from PEP 345, which says parentheses are required. I would like to add some text to that section, such as:

"Following PEP 508, version specifiers no longer need to be surrounded by parentheses in the fields Requires-Dist, Provides-Dist, Obsoletes-Dist or Requires-External, so e.g. `requests >= 2.8.1` is now a valid value. The recommended format is without parentheses, but tools parsing metadata should also be able to handle version specifiers in parentheses."

Thanks, Thomas

_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig

On Wed, Jan 10, 2018, at 11:42 PM, Nick Coghlan wrote:

On 11 January 2018 at 00:54, Daniel Holth wrote:

...

AFAICT the only missing feature from old-Metadata-2.0 is "description as message body", which places readable description text after the key/value pairs.

Do pip/PyPI/et al currently support that?

It looks like twine supports it, at least for wheels: https://github.com/pypa/twine/blob/f74eae5506300387572c65c9dbfe240d927788c2/... I don't think pip needs to support it (does pip do anything with descriptions?). I haven't looked at PyPI's code, but I'd guess it uses the metadata sent with the upload by tools like twine and flit. Thomas

Yes, after the PEP is prep'd. On Fri, Jan 12, 2018 at 11:00 AM Alex Grönholm wrote:

On the same note, wheel currently writes "2.0" as its metadata version. Shouldn't this be changed into 1.3 (along with ditching metadata.json)?

Thomas Kluyver kirjoitti 12.01.2018 klo 17:26:

...

On Wed, Jan 10, 2018, at 11:42 PM, Nick Coghlan wrote:

...

On 11 January 2018 at 00:54, Daniel Holth wrote:

...

AFAICT the only missing feature from old-Metadata-2.0 is "description as message body", which places readable description text after the key/value pairs. Do pip/PyPI/et al currently support that? It looks like twine supports it, at least for wheels:

https://github.com/pypa/twine/blob/f74eae5506300387572c65c9dbfe240d927788c2/...

...

I don't think pip needs to support it (does pip do anything with

descriptions?). I haven't looked at PyPI's code, but I'd guess it uses the metadata sent with the upload by tools like twine and flit.

...

Thomas _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig

_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig

This is the old text. Describing the distribution =========================== The distribution metadata should include a longer description of the distribution that may run to several paragraphs. Software that deals with metadata should not assume any maximum size for the description. The recommended location for the description is in the metadata payload, separated from the header fields by at least one completely blank line (that is, two successive line separators with no other characters between them, not even whitespace). Alternatively, the description may be provided in the `Description`__ metadata header field. Providing both a ``Description`` field and a payload is an error. __ `Description (optional, deprecated)`_ The distribution description can be written using reStructuredText markup [1]_. For programs that work with the metadata, supporting markup is optional; programs may also display the contents of the field as plain text without any special formatting. This means that authors should be conservative in the markup they use. On Tue, Jan 16, 2018 at 6:44 AM Thomas Kluyver wrote:

Allow me to prod this topic again. ;-)

I'm happy with PEP 566 as it stands.

Do we want to specify 'email body is long description' in this PEP? It appears to have at least some real world support, but I'm not familiar enough with the email metadata format to write a proper description of it.

Thanks, Thomas

On Fri, Jan 12, 2018, at 4:02 PM, Daniel Holth wrote:

Yes, after the PEP is prep'd.

On Fri, Jan 12, 2018 at 11:00 AM Alex Grönholm wrote:

On the same note, wheel currently writes "2.0" as its metadata version. Shouldn't this be changed into 1.3 (along with ditching metadata.json)?

Thomas Kluyver kirjoitti 12.01.2018 klo 17:26:

...

On Wed, Jan 10, 2018, at 11:42 PM, Nick Coghlan wrote:

...

On 11 January 2018 at 00:54, Daniel Holth wrote:

...

AFAICT the only missing feature from old-Metadata-2.0 is "description as message body", which places readable description text after the key/value pairs. Do pip/PyPI/et al currently support that? It looks like twine supports it, at least for wheels:

https://github.com/pypa/twine/blob/f74eae5506300387572c65c9dbfe240d927788c2/...

...

I don't think pip needs to support it (does pip do anything with

descriptions?). I haven't looked at PyPI's code, but I'd guess it uses the metadata sent with the upload by tools like twine and flit.

...

Thomas _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig

_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig

*_______________________________________________* Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig

_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig

Whichever we choose, the metadata version should match the PEP version, which it currently does not. Nathaniel Smith kirjoitti 16.01.2018 klo 18:58:

On Jan 12, 2018 8:00 AM, "Alex Grönholm" mailto:alex.gronholm@nextday.fi> wrote:

On the same note, wheel currently writes "2.0" as its metadata version. Shouldn't this be changed into 1.3 (along with ditching metadata.json)?

Should wheel change to emit 1.3, or should the PEP change to become 2.0? I know there were great hopes for "metadata 2.0", but given that there are bazillions of packages out there with a metadata version of 2.0, we're never going to be able to meaningfully use that version number for anything else, and it's confusing if when reading package metadata the ordering is 1.2 < 2.0 == 1.3 < 1.4. So maybe we should declare that this update is 2.0 or 2.1, the next one will be 2.1 or 2.2, etc., and if anyone asks why the major version bump, well, it's hardly the strangest thing we've done for compatibility :-). (And in the unlikely event that PEP 426 lurches back to life, we can make it 3.0.)

-n

On 17 January 2018 at 02:58, Nathaniel Smith wrote:

Should wheel change to emit 1.3, or should the PEP change to become 2.0? I know there were great hopes for "metadata 2.0", but given that there are bazillions of packages out there with a metadata version of 2.0, we're never going to be able to meaningfully use that version number for anything else, and it's confusing if when reading package metadata the ordering is 1.2 < 2.0 == 1.3 < 1.4. So maybe we should declare that this update is 2.0 or 2.1, the next one will be 2.1 or 2.2, etc., and if anyone asks why the major version bump, well, it's hardly the strangest thing we've done for compatibility :-). (And in the unlikely event that PEP 426 lurches back to life, we can make it 3.0.)

While I never changed the title, PEP 426 actually already specifies 3.0 in https://www.python.org/dev/peps/pep-0426/#metadata-version for exactly this reason :) The reason for *not* making PEP 566 a major version bump is in case anyone actually implemented this draft requirement from PEP 426: "Automated tools consuming metadata SHOULD warn if metadata_version is greater than the highest version they support, and MUST fail if metadata_version has a greater major version than the highest version they support (as described in PEP 440, the major version is the value before the first dot)." Metadata 1.3 is backwards compatible with metadata 1.2, so it should keep the same major version number. It's also an open question at this point whether or not there will ever *be* a metadata 2.0, since we've never worked out a way to resolve the chicken-and-egg adoption problem that arises from proposing to publish metadata in a format that existing client tools don't know how to read (hence the change in PEP 566 to treat the JSON form as something to be *derived* from the line-oriented key/value form, rather than as a replacement for it). Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

Hi all, Thanks very much for all your suggestions and feedback. I want to take a moment to summarize & respond to some outstanding issues from this thread & previous threads. [0][1][2] First, I'd like to reiterate that the goal of this PEP is to: 1. Define the Core Metadata document as the source for the specification; 2. Motivate, describe and formalize any new fields already in this spec; 3. Resolve any differences between this specification and other accepted PEPs. With that in mind:

How should multiple author-email and maintainer-email addresses be specified?

These fields already accept legal RFC-822 style headers, which includes the possibility for multiple comma-separated addresses. Note, however, that Warehouse currently incorrectly rejects such fields. [3]

Should we add security-email and/or security-disclosure-instructions?

Let's defer this to a future version as it is not included in the current spec.

Version specifiers and OR clauses

Let's defer this to a future version as it is not included in the current spec.

Replacing hyphens with underscores when transforming to JSON-compatible metadata

This change was added to the draft.

Differences with parentheses in version specifiers between PEP 345 and PEP 508

This change was added to the draft.

AFAICT the only missing feature from old-Metadata-2.0 is "description as message body", which places readable description text after the key/value pairs.

Since twine does not currently support this for anything other than wheels, and since it wouldn't be backwards-compatible, I'm inclined to defer this to a future version.

Metadata 1.3 vs Metadata 2.0

I agree with Nick here that since this version is backwards-compatible, that it should remain Metadata 1.3. In addition, I think we should avoid overloading the already-in-use "2.0" version as possibly being either a "PEP 566 flavor 2.0" or a "PEP 426 flavor 2.0".

Conclusion

I'm happy with this PEP as it stands, and I think it's ready to be formally submitted for Daniel's review. Thanks, D. [0]: https://mail.python.org/pipermail/distutils-sig/2017-December/031788.html [1]: https://mail.python.org/pipermail/distutils-sig/2017-December/031805.html [2]: https://mail.python.org/pipermail/distutils-sig/2017-December/031814.html [3]: https://github.com/pypa/warehouse/issues/2679

On Thu, Jan 18, 2018 at 5:58 AM, Nick Coghlan wrote:

...

...

Metadata 1.3 vs Metadata 2.0

I agree with Nick here that since this version is backwards-compatible,

On 18 January 2018 at 10:22, Dustin Ingram wrote: that it

...

should remain Metadata 1.3.

In addition, I think we should avoid overloading the already-in-use "2.0" version as possibly being either a "PEP 566 flavor 2.0" or a "PEP 426 flavor 2.0".

Nathaniel raised a good point, which is that client tools have already been accepting "bdist_wheel-flavoured metadata 2.0" for years, so we can be confident no client tools are actually rejecting metadata versions that start with "2.x".

Given that, I think it would be reasonable to finally Withdraw PEP 426 (rather than continuing to defer it), and have PEP 566 define metadata version 2.1, so that it's unambiguously the latest metadata version.

Jump straight to 3.0 to clear out any confusion and/or ambiguity on the next backwards-incompatible one? -- Joni Orponen

1.2 and not 2.0 is correct.

I took a look at pkg_resources. It doesn't read Metadata-Version at all. It only cares about Version, and in wheels Requires-Dist and Provides-Extra. Everything else is ignored. So PEP 566 won't break anything there as long as someone checks that pkg_resources can handle the optional parenthesis which seems likely. On Thu, Jan 18, 2018 at 11:37 AM Dustin Ingram wrote:

...

Given that, I think it would be reasonable to finally Withdraw PEP 426 (rather than continuing to defer it), and have PEP 566 define metadata version 2.1, so that it's unambiguously the latest metadata version.

I'm amenable to any version number that is > 1.2 and not 2.0.

D. _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig

On 19 January 2018 at 00:14, Joni Orponen wrote:

On Thu, Jan 18, 2018 at 5:58 AM, Nick Coghlan wrote:

...

Given that, I think it would be reasonable to finally Withdraw PEP 426 (rather than continuing to defer it), and have PEP 566 define metadata version 2.1, so that it's unambiguously the latest metadata version.

Jump straight to 3.0 to clear out any confusion and/or ambiguity on the next backwards-incompatible one?

While we could do that, wheel's use of "2.0" actually stems from early drafts of PEP 426, and PEP 566 *is* backwards compatible with that. So I like 2.1 - higher than everything previously used, but an incremental update to the early versions of 426 before we/I started imagining a ground up redesign of the metadata definition. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

I've updated the PEP to use "2.1" as the version: https://www.python.org/dev/peps/pep-0566/ D.