PEP 751: Purpose of packages.sdist.name & packages.wheels.name?

[jsirois]

I'm looking for clarity on the purpose of packages.sdist.name & packages.wheels.name. They lead to the same question. Here's the example for packages.wheels.name:

peps/peps/pep-0751.rst

Lines 646 to 653 in 5625a11

	``packages.wheels.name``
	''''''''''''''''''''''''
	- **Type**: string
	- **Required?**: no, not when the last component of ``path``/ ``url`` would be
	the same value
	- **Inspiration**: PDM_, Poetry_, uv_
	- The file name of the :ref:`packaging:binary-distribution-format` file.

Focusing on:

Required?: no, not when the last component of path/ url would be
the same value

Under what scenario does the "would be" derive from? I ask because when I initially implemented PEP-751 "installer" support in Pex I took the presence of such a name to trump the basename of the associated path or URL. I didn't think about the path case, but for the URL case I assumed a scenario like this:

sdist = {name = "foo-1.2.3.tar.gz", url = "https://my.index/foo-1.2.3.tar.gz/content" ...}

In other words I assumed the context was universal; e.g.: anyone accessing the artifact URL https://my.index/foo-1.2.3.tar.gz/content would get a content disposition header like Content-Disposition: attachment; filename="foo-1.2.3.tar.gz" such that a typical agent implementation would save the file as "foo-1.2.3.tar.gz" and not as "content".

I ran across uv's use, which appears to be to place the name it happens to store the wheel file as (a normalized wheel name) when the index URL basename was a non-normalized version of the name. For example:

wheels = [{ name = "pyyaml-6.0.2-cp310-cp310-macosx_10_9_x86_64.whl", url = "https://files.pythonhosted.org/packages/9b/95/a3fac87cb7158e231b5a6012e438c647e1a87f09f8e0d123acec8ab8bf71/PyYAML-6.0.2-cp310-cp310-macosx_10_9_x86_64.whl" ...}]

The response served up by https://files.pythonhosted.org/packages/9b/95/a3fac87cb7158e231b5a6012e438c647e1a87f09f8e0d123acec8ab8bf71/PyYAML-6.0.2-cp310-cp310-macosx_10_9_x86_64.whl does not, in fact use a Content-Disposition header to suggest an alternate filename; so my initial implementation suffered a bug as a result.

As a result I now just ignore the name field, but I'm uneasy about this. I feel like I'm missing the intent. Do either of @brettcannon or @charliermarsh have insight on this?

Any help understanding this is appreciated. I'm willing to take what I learn and send up a PR to clarify either this PEP or that other location this info is stored now.

C.F:

• Processing pylock.toml fails to acknowledge downloaded dependency files with unusual characters pex-tool/pex#2772
• Processing pylock.toml fails to acknowledge downloaded dependency files with unusual characters pex-tool/pex#2772 (comment)

[charliermarsh]

IIRC, the intent is just to save some space and make the format more concise by not requiring you to repeat the name if name exactly matches the last segment of the URL. (That looks like a bug in uv?)

[jsirois]

I'm not sure it's a bug because I'm unsure why you'd ever use the field at all. Basically it seems like a bug in the spec itself unless it was intended to cover the sort of esoteric case I outlined. @brettcannon what is the intention for this field?

[AA-Turner]

For substantive questions about a PEP or PyPA standard, use Discourse.

A

[jsirois]

@AA-Turner I'll have to bow out then. I don't wish to join the discourse and I am offering a spec edit. It would seem to me asking and discussing where the spec actually lives would make sense, but I'll desist if that's the way this has to be and the issue can be closed.

[AA-Turner]

The current specification is kept at https://github.com/pypa/packaging.python.org/blob/main/source/specifications/pylock-toml.rst, as it is a PyPA specification.

The idea with using Discourse is to increase the visibility of discussions (many of those interested in packaging standards do not follow the PEPs repo closely), but I respect your preference not to join. Perhaps you could open a PR to the specification document in the PyPA repo.

A

[jsirois]

Thanks @AA-Turner, done.