pypa / pypa/packaging

Handling of the `Description` metadata field

Open
#867 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement packaging.metadata
Dominant language
Python
Stars
751
Forks
324
Avg merge
12h 58m
Merged PRs (30d)
3

Description

Since metadata version 2.1, the package description can go into the body of the RFC822 metadata serialization format. Before then, it was encoded in the Description header with custom multi-line serialization involving continuation lines to be prefixed with 7 spaces and a |, see https://packaging.python.org/en/latest/specifications/core-metadata/#description

packaging.metadata.RawMetadata and packaging.metadara.Metadata do not interpret the continuation lines prefix, thus consumers of the description fields of these objects need to implement it themselves. This is a bit inconvenient and it may result in different tools interpreting the metadata differently. Would it be desirable to add continuation lines interpretation to packaging.metadata?

One twist on this is that setuptools (at least in version 45.2.0, which is still used in the wild, see https://github.com/pypa/twine/issues/1218) generates continuation lines with the wrong prefix: the | is missing. How would this need to be treated?

The same applies also to the License field which in some projects is used to store the whole text of the license as a multi-line field, although with a different format which does not use the | character. Fixing the leading space there would also be nice. The License field will be slowly be replaced by the License-Expression and License-File field, but parsing metadata from existing distributions still applied, and the tail of packages building with outdated build backends is very long.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the packaging.metadata.RawMetadata and Metadata entry points alongside the core metadata Description specification. Compare the legacy Description and License continuation formats, including setuptools 45.2.0 output, and clarify the intended parsing behavior before adding tests that define the accepted results.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.