Clarify package metadata

[eliegoudout]

OS version

macOS

Python version

3.10.8

Pip version

pip 23.0

Guide link

https://packaging.python.org/en/latest/tutorials/packaging-projects/

Problem description

Hello,

First of all, I want to say that I found the tutorial on building and distributing python packages very well written and helpful. Nevertheless, building my package using hatch as suggested, I just have a few questions regarding pyproject.toml and the metada of the project displayed by pip show.

1. Regarding the authors field, tutorial suggests:

authors = [
  { name="Example Author", email="author@example.com" },
]

which leads to the following pip show:

Author: 
Author-email: Example Author <author@example.com>

when I in fact think that we would like to have

Author: Example Author
Author-email: author@example.com

This is possible by separating the name and email infos as follow:

authors = [
  { name="Example Author"},
  { email="author@example.com" },
]

but it seems a bit unnatural, and breaks the logical link between the name and the mail of the author (especially if there are several authors).

2. My second concern is about the Home-page field. Tutorial suggests:

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

which is well understood by Pypi, but not really by pip in CLI. Indeed, pip show output is blank for this entry

$ python3.10 -m pip show 
Name: MyPackage
Version: 0.0.1
Summary: Short description
Home-page: 
...

and it is only by using pip show --verbose that we have the additional info at the bottom:

Project-URLs:
  Homepage, <url>

I think it's a bit of a shame because lots of users won't use --verbose option and won't have the info they were looking for.

I tried really hard to find a way to fix this without using setuptools (tutorial recommend hatch by default, I figured that there must be a reason, especially since I found online that setuptools apparently suffers from deprecation avoidance issues)

By the way, this problem is also referenced here.

3. Finally, I would like to know the "best practise" for the License field. Tutorial suggests wrting the info in classifiers,

classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",

but that doesn't seem to fill the License field when pip show. I found on this specification that I could also use

license = {text="My pretty license"}

or

license = {file="LICENSE"}

The former outputs My pretty license upon pip show, and the latter pastes the content of the LICENCE file. What would the best practise be? I personally like the second option, but on Pypi.org, it does this funny thing:

Thank you in advance for your help!

Error message

No response

[abravalheri]

Hi @eliegoudout, this behaviour is specified by the pyproject.toml living standard, which describes how pyproject.toml metadata is translated to core metadata.

In your examples I think it seems to be working as intended. Is your request for clarification about this translation mechanism to be added to the tutorials, or are you suggesting the standard should be modified to do something different? In the case you would like to propose changes, I would suggest by starting discussing these changes in the Packaging topic of the Python discourse.

---

Specifically, I can highlight the following parts of the standard:

• urls
  ...

  • Corresponding core metadata field: Project-URL

  Note that the pyproject.toml does not specify correspondence with the Home-page core metadata. Instead everything is delegated to the Project-URL core metadata (in a previous discussion in the Python discourse, I remember this being an intentional design by the spec authors).

• authors/maintainers
  ...
  If both email and name are provided, the value goes in Author-email or Maintainer-email as appropriate, with the format {name} <{email}>.

Regarding the License field, as per now there is no standard requiring information from classifiers to be populated into the License/License-file fields, but my interpretation of the overall sentiment is that the community is moving away from license classifiers.

When using pyproject.toml's license = {file = ...}, the content of the file will be read and used to populate the License core-metadata as a full length, plain string (see discussion). Then, PyPI will read this plain string and dump everything into its interface (which explains what you are seeing).

If you want to avoid that with setuptools I (personally) recommend setting a SPDX identifier in [project] license = {text = ...} and relying on setuptools' default license file recognition (LICEN[CS]E*, COPYING*, NOTICE*, AUTHORS* files at the root of the project), or adding something like the following:

[tool.setuptools]
license-files = ["MYCUSTOM_LICENSE.file"]

[pfmoore]

Instead everything is delegated to the Project-URL core metadata (in a previous discussion in the Python discourse, I remember this being an intentional design by the spec authors).

It would be a reasonable feature request for pip show to display the "Homepage" from Project-URL if Home-Page is not set (as it won't be, as more projects adopt pyproject.toml based metadata).

[eliegoudout]

Thanks for your very thorough answer @abravalheri.

• Ok regarding Home-page. I find that it would be great if it were populated from project.urls, but I guess PEP621 ruled against it.
• Thanks for the reference for author and author-email, I guess it's down to personnal preference whether or not to separate name and email in order to have a nicer pip show.
• Ok for the license and license, but I don't think there is a smiliar option for hatch-built project.

I guess in the end the project will contain the metadata no matter what, but I find it a bit sad that pip doesn't show them "optimally" in CLI. I mean that this (actual output)

$ pip show mypackage
Name: mypackage
Version: 0.0.1
Summary: This is my cool package
Home-page: 
Author: 
Author-email: Example Author <author.email@example.com>
License: MIT License
        | the
        | whole
        | license
Location: /path/to/site-packages
Requires: required packages
Required-by: requiring packages

definitely looks a bit worse than this (desired output)

$ pip show mypackage
Name: mypackage
Version: 0.0.1
Summary: This is my cool package
Home-page: https://www.github.com/author/mypackage
Author: Example Author
Author-email: author.email@example.com
License: MIT License
        | the
        | whole
        | license
Location: /path/to/site-packages
Requires: required packages
Required-by: requiring packages

to me.

Cheers!

[pfmoore]

Feature requests (or even PRs, if you're able to do that!) are welcome to improve pip's output here. We've not adapted yet to the implications of the new structure that having metadata defined in pyproject.toml implies, but IMO we should.

[eliegoudout]

Okay! I would gladly contribute or feature request, but I'm not even sure how the building/installation ecosystem works, so I'm not even sure where the feature should be added. Is it a problem from pip? Or from hatch? I'm not even sure I understand what's the specific role of hatch in the build process. Even more, I don't really know what is the role of pypa in all this! It's a bit new and blurry to me :)

If you could enlighten me, I could probably get more into it!

Thanks

[pfmoore]

Hi @eliegoudout! If you go to pip's issue tracker at https://github.com/pypa/pip/issues/ and create an issue there, describing what you'd like pip show to do that's different, that will get it to the attention of the other pip maintainers. Pick the "feature request" template, as that's the one that will help you describe your request best.

[abravalheri]

• Ok regarding Home-page. I find that it would be great if it were populated from project.urls, but I guess PEP621 ruled against it.

Just a small comment. PEP 621 does not prevent the backend from additionally populating Home-page from the project.urls, but it requires the same information to be added under Project-URL, at least. (In practice PEP 621 only stablishes precedent for a future deprecation of Home-page).

In the initial implementation, setuptools did duplicate the info, but then several users requested the duplication to be removed and submitted a PR for it. This is related to the fact that PyPI was also showing a weird UI...

[pfmoore]

Yeah, the best way to present PEP 621 data mapped onto project metadata is quite unobvious in the case of project homepage (particularly as there's no clear advice on what key to use in urls for the project homepage). And for that matter the author/maintainer data, although in that case I think the PEP 621 form is clearer.

[henryiii]

Couldn't pip show just avoid showing the Homepage and Author (and I assume Maintainer) fields if not present, and additionally add a URLs field? Act least that would help this case, and would be a closer representation of the actual metadata.

Something like:

$ pip show mypackage
Name: mypackage
Version: 0.0.1
Summary: This is my cool package
Project-URL:
- Homepage: https://www.github.com/author/mypackage
Author-email: Example Author <author.email@example.com>
License: MIT License
        | the
        | whole
        | license
Location: /path/to/site-packages
Requires: required packages
Required-by: requiring packages

[WolfgangFahl]

see also https://stackoverflow.com/questions/75570780/pip-show-does-not-show-summary-home-page-author-and-license - i was completly baffled about pip show not showing the fields any more after working on WolfgangFahl/py-3rdparty-mediawiki#92 - i had not expected such a regression when "improving" the project structure.