`py_wheel`: Summary, Description, Description-Content-Type

[vonschultz]

🚀 feature request and documentation 🐞 bug report

Relevant Rules

py_wheel

Description

The documentation of the description_file attribute of py_wheel describes the attribute as "A file containing text describing the package in a single line."

This directly contradicts the core metadata specifications, https://packaging.python.org/en/latest/specifications/core-metadata/#description, which states

A longer description of the distribution that can run to several paragraphs. Software that deals with metadata should not assume any maximum size for this field, though people shouldn’t include their instruction manual as the description.

There is, however, another field in the core metadata specifications that actually matches the description, https://packaging.python.org/en/latest/specifications/core-metadata/#summary:

Summary
A one-line summary of what the distribution does.

I'm not entirely sure if this should be a bug report or a feature request, because both "Description" and "Summary" would be nice to have. I'm assuming that compliance with the PyPA specifications is intended, in which case it is at least a documentation bug. The description_file attribute ends up as the "Description", and can be several paragraphs. But it would be nice to also support the "Summary" field using a different attribute, and it would also be nice to be able to set the "Description-Content-Type field, https://packaging.python.org/en/latest/specifications/core-metadata/#description-content-type, so at least in those parts it's a feature request as well.

Describe the solution you'd like

1. Documentation of description_file updated to support more than one line of description.
2. New attribute summary for the one-line description, setting Summary
3. New attribute description_content_type for specifying markup syntax, setting Description-Content-Type

[pstradomski]

1. Is indeed a documentation bug, should be fixed.
2. Is omission, should be fixed.
3. Is already on my list, should be fixed soon.

[aignas]

#4065 might make it easier to specify custom attributes. So this is only about fixing docs.