Add custom metadata to wheel file

Is there any way to add custom pyproject.toml fields to .whl metadata? For example, the uuid field below…

requires = ["hatchling"]
build-backend = ""

name = "test-pkg"
description = "Nothing to see here!"
readme = ""
requires-python = ">=3.8"
license = "MIT"
version = ""
uuid = "82a64458-cf50-4a12-bf2c-66d0169e541d"

Building a .whl file, and then checking test_pkg-0.1.0.dev0.dist-info/METADATA, that project.uuid field was dropped.

To accomplish this, would I have to write my own build backend?

The content of the METADATA file is standardised here. The standard doesn’t allow for custom fields.

What you might be able to do is put custom data in an additional, not standardised, file in the .dist-info directory. I don’t know if any existing build backends allow you to do that, or whether you’d need to write your own.

But why do you even want to do that? How is it any different from putting the custom field (and its value) into the code of your project itself?

Edit: Also, the [project] section of pyproject.toml is standardised here and it doesn’t allow custom fields either. You should put your custom field in the [tool] section, which is reserved for that purpose in PEP 518.

1 Like

Understood, thanks! I’ll add the custom field(s) I want in a new file, and under the “tool” key in the pyproject.toml file.

I am writing a package manager that is registry-focused, an opposed to index-focused. All for fun / learning, I’m somewhat new to Python and this project has really helped me get up to speed quickly. I want to add a UUID field to uniquely identify packages with the same name from two different “registries”.

Hatchling supports this Custom files under `dist-info` as part of a build hook · Issue #620 · pypa/hatch · GitHub

1 Like

One example that I did recently (using additional fields in PKG-INFO) is to cache source URLs for downloadable components.

Essentially, when building the sdist, the correct URLs for that version of the package are calculated, but aren’t used until installing/building the wheel. At that point, I didn’t want to recalculate them, so I just stuffed them into the PKG-INFO (which pymsbuild makes trivial by doing zero validation :wink: and automatically reads them back out for when building wheels).

The METADATA spec doesn’t say what to do with unrecognised fields. Given we have the metadata-version field already, I’d be inclined to say that any fields not defined by that version should just be ignored/copied (by tools that aren’t deliberately looking for them).

That said, using custom files under dist-info is almost as good (has the same name collision risk, though without a version number to mitigate it), and totally agree with [project] not allowing unspecified fields.

1 Like

Would it make sense to amend the metadata spec to explicitly ignore unknown fields? It might be useful to standardise a prefix (e.g. X- like Debian and other projects do) to avoid future name clashes as the metadata spec evolves.

I have a somewhat similar use case, where I want to store native build dependencies linked into the Python extension as provenance data. I think custom fields in PKG-INFO would be the cleanest solution for this, but I’m concerned that because the spec doesn’t say how unknown fields should be handled, it could cause issues with certain tools. Because of this, I plan to go with storing this data in a file under .dist-info, but it would be nice to have a standardised way of handling this kind of custom metadata.