Document recommended keys for project_urls

[brettcannon]

What's the problem this feature will solve?

Help standardize on the names people use for project_urls while also helping to get more URLs with nice icons.

Describe the solution you'd like

Document somewhere (maybe https://packaging.python.org/guides/distributing-packages-using-setuptools/#project-urls) the recommended URL labels projects should consider using.

Additional context
Since https://github.com/pypa/warehouse/blob/master/warehouse/templates/packaging/detail.html has special logic to add appropriate icons based on the label provided for these URLs, it might be nice to help guide people towards a set of labels. That way more people get the nice icons and it helps standardize the labels implicitly.

[brettcannon]

BTW I'm willing to write up the PR to document this if that's the way to go, I just need to be told where you would like it and what to standardize on (and the problem with the link I provided is that doesn't generically work for other project builders like flit). 😄

And I'm willing to kick off a discussion on this if that's the way people want to go.

[hugovk]

Here's the list of the most-used project_uls keys in the top 4,000 downloaded packages (August 2020), which could be used to inform what is commonly used and what to standardise on:

• Investigation into "canonical" link for a PyPI repo link hugovk/pypi-tools#11 (comment)

For example, the top 10 are:

1. Homepage (3916)
2. Download (778)
3. Documentation (240)
4. Source (152)
5. Changelog (70)
6. Repository (63)
7. Bug Tracker (62)
8. Source Code (60)
9. Tracker (55)
10. Issue tracker (39)

And grouping some variants, we can see some popular choices:

• Source (152)
• Repository (63)
• Source Code (60)
• GitHub (28)
• Code (26)
• Source-Code (7)
• GitHub: repo (6)
• Source code (6)
• repository (6)

And:

• Documentation (240)
• Docs (6)
• Docs: RTD (5)
• Read the Docs (1)

And:

• Changelog (70)
• Change log (2)

[brettcannon]

Thanks for the analysis, @hugovk !

The popularity of the "Download" link is a bit interesting to have on PyPI. 😆

[dstufft]

If this is reading the HTML on Warehouse, I'm pretty sure we surface the dedicated links for home page and download URLs in the metadata as a Project URL named Homepage and Download. So I suspect the popularity comes from the fact that those are dedicate keywords in python metadata (and IIRC distutils warns if you don't have it?).

[hugovk]

If this is reading the HTML on Warehouse, I'm pretty sure we surface the dedicated links for home page and download URLs in the metadata as a Project URL named Homepage and Download. So I suspect the popularity comes from the fact that those are dedicate keywords in python metadata (and IIRC distutils warns if you don't have it?).

Yes, that data comes from the JSON API, and Homepage and Download are special cases:

https://github.com/pypa/warehouse/blob/bd2b3a22f4f84072eb03abb771a88ddab1489e7a/warehouse/packaging/models.py#L455-L458

---

Aside:

Here's a table of the 778 Download links and their projects:

• download_urls.txt

And just the sorted URLs:

• urls_sorted.txt

299 are UNKNOWN
186 contain tar
128 contain pypi
34 contain zip
25 contain tag

One package with UNKNOWN is retrying. It's an old one (2014) and doesn't show a download link at https://pypi.org/project/retrying/. It's JSON at https://pypi.org/pypi/termcolor/json shows:

"download_url": "UNKNOWN",
"home_page": "http://pypi.python.org/pypi/termcolor",
"project_urls": {
  "Download": "UNKNOWN",
  "Homepage": "http://pypi.python.org/pypi/termcolor"
},

Anyway, whether UNKNOWN should be shown in the JSON is another issue, and Warehouse is correctly not displaying it.

[alex-orange]

I found this while looking for such a specification myself. One thing I'd like to add to the conversation is that https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#urls provides an examples with specifically:

• Homepage
• Documentation
• Repository
• Issues
• Changelog
  These seem reasonable, maybe the thing to do is just specify that these are the norm?

[ncoghlan]

The sample PyPA project has a different set of URLs:

[project.urls]
"Homepage" = "https://github.com/pypa/sampleproject"
"Bug Reports" = "https://github.com/pypa/sampleproject/issues"
"Funding" = "https://donate.pypi.org"
"Say Thanks!" = "http://saythanks.io/to/example"
"Source" = "https://github.com/pypa/sampleproject/"

I ended up here while trying to work out whether my preferred "Issue Tracker" name for the issue tracker link would get the bug icon on PyPI (it will, but I only confirmed that by following the code link above), so one possible way to organise these docs would be to list the categories that PyPI defines, and the associated criteria for picking that category (with a general note that all string comparisons are case insensitive).

Docs sketch based on translating the current icon selection code into English prose (I haven't kept the exact same order, so Mastodon is listed with the other primarily name-based checks. This shouldn't matter in practice, since you're not going to get a fediverse host domain that collides with the cloud service domains that have their own icon categories):

---

• Download URL (cloud icon): set via explicit metadata field, or "Download" URL name (legacy metadata, so maybe document separately?)
• Home page URL (house icon): set via explicit metadata field, or URL name in "Home", "Homepage", or "Home"
• Changelog URL (scroll icon): URL name in "Changelog", "Change Log", "Changes", "Release Notes", "News", "What's New", "History"]
• Documentation URL (book icon): URL name starts with "Docs" or "Documentation, link target hostname is "docs" or "documentation", or link target domain is a known ReadTheDocs hosting domain
• Issue tracking URL (bug icon): URL name starts with "Bug", "Issue", "Tracker", or "Report"
• Funding URL (donation icon): URL name starts with "Funding", "Donate", "Donation", or "Sponsor"
• Fediverse URL (Mastodon icon): URL name is "Mastodon"
• Cloud service URLs (service specific branded icons): identified based on link targets, see list of known cloud services below
• Continuous Integration URL (tasks icon): identified based on link targets, see list of known CI services below
• PyPI URL (PyPI icon): identified based on link targets
• Python URL (Python logo icon): identified based on link targets
• Other external URL (generic external link icon): any URL name and link target that doesn't fall into at least one of the above categories

Cloud services with known domains associated with specifically branded PyPI Project Link icons:

• GitHub (code hosting)
• GitLab (code hosting)
• BitBucket (code hosting)
• Gitter (chat service)
• Discord (chat service)
• Google (!? Is this a legacy feature from when code.google.com was still a thing?)
• Reddit (discussion boards)
• Slack (chat service, also used for any URL name starting with "Slack")
• Twitter/X (social media)
• YouTube (social media)

Continuous services with known domains associated with the PyPI Project Link "Tasks" category icon:

• Appveyor
• CircleCI
• CodeCov
• Coveralls
• Shippable
• Travis-CI

(actual docs would likely be able to include the FontAwesome icons themselves, but I couldn't see an obvious way to get them to appear inline in GitHub markdown)

[di]

This is now resolved: https://docs.pypi.org/project_metadata/