search

pypi / warehouse

The Python Package Index
https://pypi.org
Apache License 2.0
3.54k stars 952 forks source link

Document recommended keys for project_urls #5947

Closed brettcannon closed 2 weeks ago

brettcannon commented 5 years ago

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 commented 5 years 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.

hugovk commented 3 years ago

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:

  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:

And:

And:

brettcannon commented 3 years ago

Thanks for the analysis, @hugovk !

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

dstufft commented 3 years ago

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 commented 3 years ago

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:

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.

alex-orange commented 6 months ago

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:

ncoghlan commented 2 months ago

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)

di commented 2 weeks ago

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