Core metadata: should `Home-page` and `Download-URL` be deprecated?

Packaging
1

Hey all! I tried looking for a previous conversation about this, but couldn’t find one. Apologies if I’ve missed it; if there is one, I’d be happy to close this and follow up there instead.

The Core metadata specifications is the living (PyPA) spec for distribution metadata. Within the living spec, there are two different ways to express a project’s URLs:

  • Project-URL is present in metadata 1.2 and newer, and is a multi-use field for specifying arbitary URLs.
  • Home-page and Download-URL are present in 1.0 and 1.1 (respectively) and are single use fields for specifying the release’s homepage and (non-index) download URL, respectively.

To the best of my understanding, Home-page and Download-URL are intentionally not exposed in the standard pyproject.toml representation of project metadata, with the expectation that users fill in the project.urls table with appropriately tagged URLs to signify equivalency with the old fields. For example, empirically, the following project.urls table is treated by PyPI as supplying the homepage and download URLs:

[project.urls]
homepage = "https://..."
download = "https://..."

So, my actual question: should the Home-page and Download-URL fields be deprecated, at least in newer versions of the core metadata? It seems as though standard project metadata representations are moving away from having separate fields for these URLs and indices are expected to extract their equivalents from the Project-URLs instead, so having these be explicitly marked as deprecated/not preferred might reduce some confusion around what role they play.

CC @facutuesca, since he noticed this originally.

Other references:

6 Likes
2

I agree that they should be deprecated, I opened a similar issue here: Support pyproject metadata in JSON API · Issue #12585 · pypi/warehouse · GitHub

I think when this work happens we should also take the time to support PEP 639 in the API.

2 Likes
3

Thanks @ofek! I knew I was missing some context/previous discussions here.

The metadata "homepage" link rendered twice on PyPI · Issue #11220 · pypi/warehouse · GitHub looks like it also has some related discussion, linked from #12585.

Based on those GitHub threads, it seems like there’s broad consensus that Home-page and Download-URL should be deprecated (and that PyPI is waiting on normative language around “which” URLs are authoritative before making more changes to its URL handling).

Given that, I’m curious what you and others think the best path forwards here is. The PyPA specs suggest writing a PEP for updates to living specifications; I’m happy to look into that if that sounds right.

4

Yup, sounds about right to me!

1 Like
5

I also think deprecation makes sense, however I’d like for the Project-URL description in the packaging guide to be a little more opinionated:

The label is free text limited to 32 characters.

I think there are clearly a set of common conventions that folks[1] cargo cult to new projects. Does it make sense to at least enumerate those common conventions and their meanings?

  1. well, me at least :smile: ↩︎

3 Likes
6

Yep, completely agreed! From PyPI’s issues it looks like normalization of the label has also been a source of (mild) confusion, so I’ll likely propose the following in the PEP:

  • Labels should be normalized via lower().replace("-", "").replace("_", ""), meaning that Homepage, homepage, home-page, and home_page all refer to the same label. As a corrollary, duplicate labels should be warned on (or cause an outright failure?)
  • The homepage project URL corresponds directly to the Home-page field’s semantics
  • The download project URL corresponds directly to the Download-URL field’s semantics

There are others that might make sense to stipulate as well, but I’m mildly concerned that enumerating more of them might push the PEP outside of the orbit of uncontroversial metadata fixes. But perhaps I’m being overly conservative there!

1 Like
7

+1 but I’d add .replace(' ', '') so project.urls like Home Page also get translated to homepage.

Others that make some sense to enumerate include:

  • documentation
  • source (and/or repository)
  • bugtracker (and/or issues)
  • changelog (and/or history)
2 Likes
8

The PyPI docs were recently updated to list the URL categories that get dedicated icons: Project Metadata - PyPI Docs

A deprecation PEP should reference that, since affecting how your project gets displayed on PyPI is the main immediate benefit of sticking with conventional URL labels.

Those docs were added following the discussion in Document recommended keys for project_urls · Issue #5947 · pypi/warehouse · GitHub

(although checking them against the issue, not all of the aliases for the categories are covered yet)

3 Likes
9

The list displayed in the documentation was built by looking at PyPI source code.

From the issue list, shippable.com was removed from the recognized services in 16512 because it has been acquired and discontinued.

10

The two (minor!) issues I noticed were that the change log aliases haven’t been added yet, and the wildcard aliases aren’t clearly distinguished from the exact aliases (so someone reading the table might mistakenly think “Issue Tracker” isn’t supported).

What’s there is still a major improvement from where we were before the addition of those tables, though.

1 Like
11

Thanks for catching these! Update icons reference in doc metadata docs by DarkaMaul · Pull Request #16584 · pypi/warehouse · GitHub should clarify the matching behavior there.

1 Like
12

I’ve created an initial draft PEP here: PEP: Uniform URLs in core metadata by woodruffw · Pull Request #1 · woodruffw-forks/peps · GitHub

If anybody is so inclined, please give it a look! I’m also hereby requesting volunteers for Sponsor and PEP-Delegate before I formally open this on the upstream PEPs repo :slightly_smiling_face:

2 Likes
13

LGTM! I’m happy to be PEP delegate for this (I think it comes under my remit) unless someone else wants to volunteer.

One thought - maybe it would be a good idea if the PEP explicitly said that additional well-known labels can be added without needing a new metadata version, or a formal PEP? I don’t see any reason to require a lot of ceremony to add new labels, and being explicit about that now might save some debate later.

2 Likes
14

Thanks! I’ve added you tentatively as the PEP delegate.

Sounds good, adding!

15

I’m happy to sponsor.

3 Likes
16

Thanks, I greatly appreciate it! I’ll add you and move this over to the PEPs repo once I’m in front of a computer.

2 Likes
17

I’ve opened an upstream PEPs PR here: New PEP: Uniform URLs in core metadata by woodruffw · Pull Request #3936 · python/peps · GitHub

3 Likes
18

Apologies for any confusion I caused. I’ve created the formal PEP discussion thread here: PEP 753: Uniform URLs in core metadata

1 Like