Text of peps.python.org › pep-0753 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 753 – Uniform project URLs in core metadata | peps.python.org

PEP 753 – Uniform project URLs in core metadata PEP 753 – Uniform project URLs in core metadata Author : William Woodruff <william at yossarian.net>, Facundo Tuesca <facundo.tuesca at trailofbits.com> Sponsor : Barry Warsaw <barry at python.org> PEP-Delegate : Paul Moore <p.f.moore at gmail.com> Discussions-To : Discourse thread Status : Final Type : Standards Track Topic : Packaging Created : 29-Aug-2024 Post-History : 26-Aug-2024 , 03-Sep-2024 Resolution : 10-Oct-2024 Table of Contents Abstract Rationale and Motivation Specification Metadata producers Package indices Conventions for Project-URL labels Label normalization Well-known labels Backwards Compatibility Limited Impact Future Considerations Security Implications How To Teach This Appendix A: Label normalization examples Copyright Important This PEP is a historical document.

The up-to-date, canonical spec, Well-known Project URLs in Metadata , is maintained on the PyPA specs page . × See the PyPA specification update process for how to propose changes. Abstract This PEP recommends two discrete changes to the processing of core metadata by indices (such as PyPI) and other core metadata consumers: Deprecation of the Home-page and Download-URL fields in favor of their Project-URL equivalents; A set of conventions for normalizing and assigning semantics to Project-URL labels during consumer-side metadata processing.

Rationale and Motivation Python’s standard core metadata has gone through many years of revisions, with various standardized milestone versions. These revisions of the core metadata have introduced various mechanisms for expressing a package’s relationship to external resources, via URLs: Metadata 1.0 introduced Home-page , a single-use field containing a URL to the distribution’s home page. Home-page: https:// example.com /sampleproject Metadata 1.1 introduced Download-URL , a complementary single-use field containing a URL suitable for downloading the current distribution.

Download-URL: https:// example.com /sampleproject/ sampleproject-1.2.3.tar.gz Metadata 1.2 introduced Project-URL , a multiple-use field containing a label-and-URL pair. Each label is free text conveying the URL’s semantics. Project-URL: Homepage, https:// example.com /sampleproject Project-URL: Download, https:// example.com /sampleproject/ sampleproject-1.2.3.tar.gz Project-URL: Documentation, https:// example.com /sampleproject/docs Metadata 2.1, 2.2, and 2.3 leave the behavior of these fields as originally specified.

Because Project-URL allows free text labels and is multiple-use, informal conventions have arisen for representing the values of Home-page and Download-URL within Project-URL instead. These conventions have seen significant adoption, with PEP 621 explicitly choosing to provide only a project.urls table rather than a project.home-page field. From PEP 621 ’s rejected ideas: While the core metadata supports it, having a single field for a project’s URL while also supporting a full table seemed redundant and confusing.

This PEP exists to formalize the informal conventions that have arisen, as well as explicitly document Home-page and Download-URL as deprecated in favor of equivalent Project-URL representations. Specification This PEP proposes that Home-page and Download-URL be considered deprecated . This deprecation has implications for both package metadata producers (e.g. build backends and packaging tools) and package indices (e.g.

PyPI). 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.

Conventions for Project-URL labels The deprecations proposed above require a formalization of the currently informal relationship between Home-page , Download-URL , and their Project-URL equivalents. This formalization has two parts: A set of rules for normalizing Project-URL labels during index-side processing; A set of “well-known” normalized label values that indices may specialize URL presentation for. 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: Raw Normalized Homepage homepage Home-page homepage Home page homepage Change_Log changelog What's New? whatsnew 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 th

The rest of this page is on the live site.