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?