Set homepage in pyproject.toml

[JakobDev]

Problem description

How can I set a Homepage in a pyproject.toml? The guide shows this:

[project.urls]
"Homepage" = "https://github.com/pypa/sampleproject"
"Bug Tracker" = "https://github.com/pypa/sampleproject/issues"

But this is just recognized as a normal URL field by PyPI and not as the homepage as the url argument from the old setup.py.

[henryiii]

See https://peps.python.org/pep-0621/#have-a-separate-url-home-page-field

It was considered redundant and isn’t included. Some backends try to fill it from the urls if there’s a matching name (setuptools 61+ does, I think). I think others just ignore it entirely as no longer needed.

[mara004]

The thing is, then no homepage is shown by pip:

[project.urls]
homepage = "https://github.com/pypdfium2-team/pypdfium2"  # FIXME not shown by pip
documentation = "https://pypdfium2.readthedocs.io/"
changelog = "https://pypdfium2.readthedocs.io/en/stable/changelog.html"

$ python3 -m pip show pypdfium2
Name: pypdfium2
Version: 4.0.0b1
Summary: Python bindings to PDFium
Home-page: 
Author: pypdfium2-team
Author-email: geisserml <[email protected]>
License: Apache-2.0 or BSD-3-Clause
Location: /home/me/.local/lib/python3.11/site-packages
Editable project location: /home/me/projects/pypdfium2
Requires: 
Required-by: 

[Pablo1990]

Hi,

I have the same problem that you had. For now, I've just created a setup.cfg file with the following fields:

[metadata]
url = URL1
author = Person1
author_email = AuthorEmail

Meanwhile, I have everything else in the pyproject.toml file.

It worked for me! Hope it helps you! Pablo

[mara004]

Of course you can work around the issue with the old setup files. But that doesn't fix the problem.

I think pip should look for a homepage entry in [project.urls]. See https://github.com/pypa/pip/issues/11138, https://github.com/pypa/pip/issues/11221, https://github.com/pypa/packaging-problems/issues/670

[bulletmark]

I started to port one of my projects from setup.py to pyproject.toml but then found this issue which has put me off. Question to the participants here which is not clear from the discussion - the second response from @henryiii implies that if I set a homepage in [project.urls] and I use setuptools >= 61 for the build then I will at least get a homepage link on the PyPI project page (which is important) but just not see a Home-page field in pip show (less important). Is this the case?

If I can't get a PyPi home page link other than by specifying a separate setup.cfg then I won't bother yet.

[GalaxySnail]

IMO the key problem is the relationship between Home-page in the core metadata specification and project.urls.Homepage in pyproject.toml is not clearly specified. Some facts:

1. Home-page: and Project-URL: Homepage, in the core metadata specification are similar in concept.
2. A separate url/home-page field in project table is considered redundant in PEP 621. [1]
3. The Home-page metadata is not deprecated.
4. It is not clearly specified whether project.urls.homepage should be mapped to the Home-page metadata by a build backend.
5. For metadata consumers, the meaning of Home-page: and Project-URL: Homepage is not very clear.
6. PyPI treats Home-page: and Project-URL: Homepage as equivalent. [2] [3] (By the way, Download-URL: and Project-URL: Download are also treated as equivalent.)

There are some potential solutions:

1. Specify that build backends should map project.urls.homepage to the Home-page metadata and map project.urls.download to the Download-URL metadata.
2. Specify that metadata consumers should treat Project-URL: Homepage and Project-URL: Download as equivalent to Home-page and Download-URL, and maybe deprecate Home-page and Download-URL since they are not supported by pyproject.toml.

[henryiii]

The biggest issue with Home-page is projects are not consistent as to what a "Homepage" means; does it mean the GitHub page, or the docs page, or something else? pypa/wheel doesn't want to set any URLs to "Homepage" because it's ambiguous. If it had been Docs-page and Source-page or something like that, it likely would be better, but it isn't. Downstream users can't assume what the Home-page (or a Homepage URL) points at. So I'd say the "solution 2" above looks good to me, except downstream users can't really use Home-page as it is anyway, so not sure there's any need to tell them to look for a Homepage URL, or to ask users to provide it. I'm not sure many projects used Download-URL.

AFAIK, the only issue here is pip show, which displays Home-page by default, but not URLs. PyPI nicely displays all your URLs.

[GalaxySnail]

The biggest issue with Home-page is projects are not consistent as to what a "Homepage" means; does it mean the GitHub page, or the docs page, or something else? Downstream users can't assume what the Home-page (or a Homepage URL) points at.

It doesn't sound like a big problem. "Homepage" seems ambiguous to downstream users, but users hardly care about what "Homepage" exactly means. Users usually want an upstream URL of this library, it can be a source code page, a docs page, or a home page in the narrowest sense (for example, https://cython.org), it's OK. Many Linux package managers have one and only one URL for each package, but I saw few poeple complain about it.

AFAIK, the only issue here is pip show, which displays Home-page by default, but not URLs. PyPI nicely displays all your URLs.

Fair enough. It would be better to show all URLs instead of only one Home-page URL.

[mara004]

It would be better to show all URLs instead of only one Home-page URL.

This is the behavior we get with pip show -v, but it's probably overkill for default pip show.

That said, I agree with @GalaxySnail, nevermind about ambiguity. My understanding of "Homepage" would be the place where a newcomer should go first. This is up to developers to define. If a project has an own website, it would commonly be that. Otherwise, it could be either repository or docs, depending on how the project is laid out.