pypi: Enhance guidance on how to reconstruct a "file_name" qualifier from inspecting installed Python packages

[pombredanne]

As a follow up to:

• Add filename qualifier to pypi. #170 (comment)
  we should provide guidance to tools authors on how to reconstruct a file_name when inspecting an installed Python package.

So to recap, I think we can use the existing file_name qualifier as-is, but we would need to provide guidance on how a tool can reconstruct this from an installed distribution. Can you update this PR along these lines, using file_name and providing some guidance on its usage, including pointers on how to reconstruct a filename from an installed PyPI wheel? This would be wonderful! (Sorry for it taking so long!)

[matt-phylum]

The formats are:

• source distributions: https://packaging.python.org/en/latest/specifications/source-distribution-format/#source-distribution-file-name
• binary distributions: https://packaging.python.org/en/latest/specifications/binary-distribution-format/#file-name-convention

I don't know if pip keeps a record of where the package came from so it may be difficult to figure out the appropriate name from an install package. Packages that were downloaded as a source distribution may appear to have been installed from a binary distribution.

[jkowalleck]

I don't know if pip keeps a record of where the package came from [...]

modern pip does. see https://packaging.python.org/en/latest/specifications/direct-url/
and other env/package managers for python do it also, based on PEP610.

[...] so it may be difficult to figure out the appropriate name from an install package.

it is pretty easy. see https://github.com/CycloneDX/cyclonedx-python/blob/8228cbb65070008279859579b6149e6f6e6f0404/cyclonedx_py/_internal/utils/pep610.py#L101-L119

[matt-phylum]

I don't think so.

Commands that do not generate a direct_url.json

• pip install app

pip install app is the usual case.

[matt-phylum]

For example, if you create a virtualenv and then install botocore==0.21.0 (a random old version I selected that doesn't have a binary distribution):

• Even though there is no wheel on pypi, lib/python3.13/site-packages/botocore-0.21.0.dist-info/WHEEL exists and in my case contains Generator: setuptools (75.6.0). setuptools 75.6.0 is a very recent version of setuptools that happens to be installed on my system. pip created a wheel as part of installing the source distribution and the dist-info WHEEL file is describing that wheel instead of the source distribution that was downloaded.
• There is no direct_url.json file.

[di]

The general sentiment in pypa/pip#10736 is that this should happen at install time by adding the --report flag, and that pip is unable to support this happening after install time.

For example, installing with --report will produce a JSON document with all the URLs (and filenames) of the artifacts that will be installed:

$ pip install sampleproject --report - | grep '"url":'
        "url": "https://files.pythonhosted.org/packages/d7/73/c16e5f3f0d37c60947e70865c255a58dc408780a6474de0523afd0ec553a/sampleproject-4.0.0-py3-none-any.whl",
        "url": "https://files.pythonhosted.org/packages/14/84/d8d9c3f17bda2b6f49406982546d6f6bc0fa188a43d4e3ba9169a457ee04/peppercorn-0.6-py3-none-any.whl",