Metadata producers

This PEP stipulates the following for metadata producers:

• When generating metadata 1.2 or later, producers SHOULD emit only Project-URL, and SHOULD NOT emit Home-page or Download-URL fields.

These stipulations do not change the optionality of URL fields in core metadata. In other words, producers MAY choose to omit Project-URL entirely at their discretion.

This PEP does not propose the outright removal of support for Home-page or Download-URL. However, see Future Considerations for thoughts on how a new (as of yet unspecified) major core metadata version could complete the deprecation cycle via removal of these deprecated fields.

Similarly, this PEP does not propose that metadata producers emit normalized labels. Label normalization is performed solely on the processing and consumption side (i.e. within indices and other consumers of distribution metadata).

Package indices

This PEP stipulates the following for package indices:

• When interpreting a distribution’s metadata of version 1.2 or later (e.g. for rendering on a web page), the index MUST prefer Project-URL fields as a source of URLs over Home-page and Download-URL, even if the latter are explicitly provided.
• If a distribution’s metadata contains only the Home-page and Download-URL fields, the index MAY choose to ignore those fields and behave as though no URLs were provided in the metadata. In this case, the index SHOULD present an appropriate warning or notification to the uploading party.
  • The mechanism for presenting this warning or notification is not specified, since it will vary by index. By way of example, an index may choose to present a warning in the HTTP response to an upload request, or send an email or other notification to the maintainer(s) of the project.
• If a distribution’s metadata contains both sets of fields, the index MAY choose to reject the distribution outright. However, this is NOT RECOMMENDED until a future unspecified major metadata version formally removes support for Home-page and Download-URL.
• Any changes to the interpretation of metadata of version 1.2 or later that result in previously recognized URLs no longer being recognized SHOULD NOT be retroactively applied to previously uploaded packages.

These stipulations do not change the optionality of URL processing by indices. In other words, an index that does not process URLs within uploaded distributions may continue to ignore all URL fields entirely.

Similarly, these stipulations do not imply that the index should persist any normalizations that it performs to a distribution’s metadata. In other words, this PEP stipulates label normalization for the purpose of user presentation, not for the purpose of modifying an uploaded distribution or its “sidecar” PEP 658 metadata file.

Label normalization

The core metadata specification stipulates that Project-URL labels are free text, limited to 32 characters.

This PEP proposes adding the concept of a “normalized” label to the core metadata specification. Label normalization is defined via the following Python function:

import string
def normalize_label(label: str) -> str:
    chars_to_remove = string.punctuation + string.whitespace
    removal_map = str.maketrans("", "", chars_to_remove)
    return label.translate(removal_map).lower()

In plain language: a label is normalized by deleting all ASCII punctuation and whitespace, and then converting the result to lowercase.

The following table shows examples of labels before (raw) and after normalization:

When processing distribution metadata, package indices SHOULD perform label normalization to determine if a given label is well known for subsequent special processing. Labels that are not well-known MUST be processed in their un-normalized form.

Normalization does not change pre-existing semantics around duplicated Project-URL labels. In other words, normalization may result in duplicate labels in the project’s metadata, but only in the same manner that was already permitted (since the core metadata specification does not stipulate that labels are unique).

Excerpted examples of normalized metadata fields are provided in Appendix A.

Well-known labels

In addition to the normalization rules above, this PEP proposes a fixed (but extensible) set of “well-known” Project-URL labels, as well as aliases and human-readable equivalents.

The following table lists these labels, in normalized form:

Indices MAY choose to use the human-readable equivalents suggested above in their UI elements, if appropriate. Alternatively, indices MAY choose their own appropriate human-readable equivalents for UI elements.

Packagers and metadata producers MAY choose to use any label that normalizes to these labels (or their aliases) to communicate specific URL intents to package indices and downstreams.

Similarly, indices MAY choose to specialize their rendering or presentation of URLs with these labels, e.g. by presenting an appropriate icon or tooltip for each label.

Indices MAY also specialize the rendering or presentation of additional labels or URLs, including (but not limited to), labels that start with a well-known label, and URLs that refer to a known service provider domain (e.g. for documentation hosting or issue tracking).

This PEP recognizes that the list of well-known labels is unlikely to remain static, and that subsequent additions to it should not require the overhead associated with a formal PEP process or new metadata version. As such, this PEP proposes that the list above become a “living” list within the PyPA specifications.

Limited Impact

This PEP is expected to have little to no impact on existing packaging tooling or package indices:

• Packaging tooling: no changes to the correctness or well-formedness of the core metadata. This PEP proposes deprecations as well as behavioral refinements, but all currently (and historically) produced metadata will continue to be valid per the rules of its respective version.
• Package indices: indices will continue to expect well-formed core metadata, with no behavioral changes. Indices MAY choose to emit warnings or notifications on the presence of now-deprecated fields, per above.