Closed brettcannon closed 2 weeks ago
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.
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:
For example, the top 10 are:
Homepage
(3916)Download
(778)Documentation
(240)Source
(152)Changelog
(70)Repository
(63)Bug Tracker
(62)Source Code
(60)Tracker
(55)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)Thanks for the analysis, @hugovk !
The popularity of the "Download" link is a bit interesting to have on PyPI. 😆
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?).
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:
Aside:
Here's a table of the 778 Download links and their projects:
And just the sorted URLs:
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.
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:
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):
Cloud services with known domains associated with specifically branded PyPI Project Link icons:
Continuous services with known domains associated with the PyPI Project Link "Tasks" category icon:
(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)
This is now resolved: https://docs.pypi.org/project_metadata/
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.