You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Deprecation of project_wheel_metadata points only at the CLI; the promised wheel_metadata() (from #1084) never shipped #1131
build.util.project_wheel_metadata was deprecated in 1.5.1, but the deprecation points only at the python -m build --metadata CLI. The programmatic replacement described in #1084 — build.util.wheel_metadata() with a check_dependencies flag — does not exist in 1.5.1 or on main. The merged diff for #1084 (cd56622) added the deprecation warning but not the new function.
Net effect: consumers of a supported, in-process Python API are being told to migrate to a subprocess, with no supported programmatic path offered.
Why this matters
project_wheel_metadata returns a live importlib.metadata.PackageMetadata object. python -m build --metadata instead emits a JSON core-metadata mapping (snake_case keys, project_urls as a mapping) over stdout. For a library that reads metadata programmatically, the recommended migration therefore means: spawn a child interpreter, capture stdout, parse JSON, and rewrite every consumer that relied on the Message interface — losing the object and the runner customization point.
To make the trade-off concrete, I put up two alternative PRs downstream:
Keep a supported in-process entry point (un-deprecate, or expose the _project_wheel_metadata core), and only then point the deprecation at it.
Until a supported programmatic replacement lands, the deprecation message recommending a CLI leaves library consumers without a like-for-like path. Refs #557, #619, #1084.
I'm gonna go ahead and yank this (undiscussed) patch release as mentioned on Discord. We can revisit the deprecation of this function.
Reading discord, it sounds like it's being yanked due to an improper version number, not due to the consternation it caused, so probably not particularly relevant to this discussion, as a re-release of the deprecated functionality under a 0.1 or 1.0 bump doesn't affect the reported concerns.
I get that it was done on purpose, but I'm raising an issue now that I've become aware of the change. I'm arguing that this functionality was particularly useful and shouldn't be deprecated.
From the PR.
No, I think if we aren't committing to providing utility functions on top of the builder and env, we shouldn't have one just for metadata. Now that the CLI can generate metadata, there isn't anything special about this function when compared to the other CLI command functions. Perhaps they should all have programmatic equivalents, but that'd probably take quite a bit of refactoring so that we don't end up letting the implementations drift again.
I particularly advocated for the creation of this utility function, and my packages rely on it heavily. I don't think just because there aren't utility functions for other behaviors justifies removing a useful utility function where users have specifically requested it.
project_wheel_metadata is deprecated in favour of [a proposed replacement]. As noted in review, it returns an email.message.Message-style object and had fallen behind the CLI, which already parses metadata into the friendlier JSON structure; rather than grow a second function the right move was to expose that capability and retire the old one. 📦
The Message format is useful in that it's largely compatible with what importlib.metadata returns. By changing the format and the shape of the metadata, you're asking all downstream consumers to adapt to these changes. That's a big ask. Just see jaraco/jaraco.packaging#27 for how much the interface changes.
I feel like my concerns were summarily dismissed. (I see now the issue was re-opened).
I'm really reluctant to adopt a new API that requires me to shell out to that API just for it to shell out to another API just to parse some metadata. The build process is already opaque enough that it makes troubleshooting difficult. It would be nice if we didn't add yet another layer of subprocess.
If you're unwilling to consider supporting the API that jaraco.packaging needs, I'll probably end up adopting the functionality in jaraco/jaraco.packaging#26, which doesn't solve the issues mentioned in the PR, but instead will just push them into jaraco.packaging.
Please reconsider providing a helper function. If that function isn't going to supply a Metadata structure, please consider providing migration guidance on how to migrate from Metadata to the JSON format and possibly supplying a compatibility shim (something that wraps the JSON shape but provides the Metadata interface).
Reading discord, it sounds like it's being yanked due to an improper version number, not due to the consternation it caused, so probably not particularly relevant to this discussion, as a re-release of the deprecated functionality under a 0.1 or 1.0 bump doesn't affect the reported concerns.
It's also an opportunity for us to listen to these concerns. Invoking "consternation" is not helpful, and thumbing down maintainers you disagree with - as you've done on the PR - is simply annoying.
The Message format is useful in that it's largely compatible with what importlib.metadata returns. By changing the format and the shape of the metadata, you're asking all downstream consumers to adapt to these changes. That's a big ask. Just see jaraco/jaraco.packaging#27 for how much the interface changes.
It would be a balancing act between a legacy format, stability and conformity with importlib.metadata, and a friendlier, standards-compliant exchange format, and internal consistency within build. If this function were to be restored, I'd still personally consider deprecating it in favour of one which returns PEP 566 JSON metadata. (I don't feel like that's a huge ask - it's mostly just changing the key casing and the accompanying documentation in your case.) The team also has to consider the maintenance burden of utility wrappers and diverging interfaces in general, and we've got to weigh these things against the time we've got available to us (and our willingness) to work on an open-source library pro bono, indefinitely.
I would not add PEP 566 JSON to anything. I was told not to when I tried to add it to packaging. If PEP 819 gets accepted, we could add that, but we should not add it before that PEP goes in; currently email metadata is the only stable format, and everyone seems to try to ignore that there every was a mention of JSON in PEP 566. Also, regardless of PEP 819, email metadata will be stable for a long time, so I don't think there's harm in it, even though I don't like it very much and would love to move to JSON eventually.
How would our CLI interface work with email metadata? packaging.metadata is stable and produces JSON-encodable metadata, which, to my knowledge, follows the transformation rules of PEP 566. PEP 819 is about producing the original metadata in JSON - not re-encoding it.
If we make a change now, and have to make a change later, that's a much higher maintenance burden than not doing anything until we need to. I think we should drop the deprecation in 1.6, and then investigate deprecation in 1.7.
packaging.metadata is stable and produces JSON-encodable metadata
packaging.metadata explicitly choses not to have a from_json or as_json until it is standardized properly. I added the current conversion back to email metadata in pypa/packaging#846 a year ago, and I actually had PEP 566 JSON support in the first version, was told "I don't know if I'm comfortable with the JSON support. I actually almost had it in the first version of the module, but decided against it until we had a standard around it." so I pulled it out. This is one of the things that helped push PEP 819 forward, I think.
From a programatic standpoint, until JSON support gets more properly standardized, I don't think we should replace an email format with JSON one; I want to follow packaging here. If you want to use packaging.metadata on the output, you have to have the email format anyway (it has a from_email, but not a from_json). I think this should remain, undeprecated, until we have a new JSON format that packaging is willing to adopt.
What about returning Metadata or RawMetadata from packaging? Then we could rely on its conversions, and not worry about formats. I'd also be okay with RawMetadata... Which... is the JSON format? It's a different framing (packaging.metadata compatibility, rather than PEP 566 JSON). Yes, verified it is the JSON format.
As for the CLI, I think keeping the current JSON is fine regardless. Reparsing the not-quite-email format is unreasonable, you can't use it. JSON is a standard you can use from any language.
Okay, after writing all that, RawMetadata kind of changed things; here's my proposal:
1.6: Restore build.util.project_wheel_metadata with no visible warning yet.
1.6 or later: Add build.util.wheel_metadata that returns RawMetadata. It can also validate deps (opt in or opt out or required option, haven't looked at it yet. I'm not a huge fan of dep validation on by default, but in a new API it's fine as long as there's an opt-out.)
Even later: Re-deprecate build.util.project_wheel_metadata in favor of build.util.wheel_metadata. This gives people using it a path forward (>=1.6 and use the new function).
Perhaps there's something I'm missing, but what is the difference between packaging.metadata.RawMetadata and the transformation described under §JSON-compatible Metadata? This is a one-way transformation, in order to display or manipulate data in a JSON-compatible structure, such as a Python dictionary. RawMetadata is what the CLI uses, and what I was suggesting to use here a few comments up.
I basically agreed with you by the end after I realized that's what packaging.metadata.RawMetadata is. My proposal is build.util.wheel_metadata with RawMetadata return, then eventually phase out build.util.project_wheel_metadata (but give them some overlap as we obviously have users!)
Activity
gaborbernat commentedon Jul 15, 2026
Done on purpose #1084 (comment)
layday commentedon Jul 15, 2026
I'm gonna go ahead and yank this (undiscussed) patch release as mentioned on Discord. We can revisit the deprecation of this function.
jaraco commentedon Jul 15, 2026
Reading discord, it sounds like it's being yanked due to an improper version number, not due to the consternation it caused, so probably not particularly relevant to this discussion, as a re-release of the deprecated functionality under a 0.1 or 1.0 bump doesn't affect the reported concerns.
I get that it was done on purpose, but I'm raising an issue now that I've become aware of the change. I'm arguing that this functionality was particularly useful and shouldn't be deprecated.
From the PR.
I particularly advocated for the creation of this utility function, and my packages rely on it heavily. I don't think just because there aren't utility functions for other behaviors justifies removing a useful utility function where users have specifically requested it.
The
Messageformat is useful in that it's largely compatible with whatimportlib.metadatareturns. By changing the format and the shape of the metadata, you're asking all downstream consumers to adapt to these changes. That's a big ask. Just see jaraco/jaraco.packaging#27 for how much the interface changes.I feel like my concerns were summarily dismissed.(I see now the issue was re-opened).I'm really reluctant to adopt a new API that requires me to shell out to that API just for it to shell out to another API just to parse some metadata. The build process is already opaque enough that it makes troubleshooting difficult. It would be nice if we didn't add yet another layer of subprocess.
If you're unwilling to consider supporting the API that jaraco.packaging needs, I'll probably end up adopting the functionality in jaraco/jaraco.packaging#26, which doesn't solve the issues mentioned in the PR, but instead will just push them into
jaraco.packaging.Please reconsider providing a helper function. If that function isn't going to supply a Metadata structure, please consider providing migration guidance on how to migrate from Metadata to the JSON format and possibly supplying a compatibility shim (something that wraps the JSON shape but provides the Metadata interface).
gaborbernat commentedon Jul 15, 2026
I'm +0.1 on keeping the helper (and implementing the requested validation in #557), but I'll defer to other maintainers on this.
henryiii commentedon Jul 16, 2026
I need to spend some time to understand the issue, and I probably won't have time till after SciPy. I'll vote once I do. :)
layday commentedon Jul 25, 2026
It's also an opportunity for us to listen to these concerns. Invoking "consternation" is not helpful, and thumbing down maintainers you disagree with - as you've done on the PR - is simply annoying.
It would be a balancing act between a legacy format, stability and conformity with
importlib.metadata, and a friendlier, standards-compliant exchange format, and internal consistency within build. If this function were to be restored, I'd still personally consider deprecating it in favour of one which returns PEP 566 JSON metadata. (I don't feel like that's a huge ask - it's mostly just changing the key casing and the accompanying documentation in your case.) The team also has to consider the maintenance burden of utility wrappers and diverging interfaces in general, and we've got to weigh these things against the time we've got available to us (and our willingness) to work on an open-source library pro bono, indefinitely.henryiii commentedon Jul 25, 2026
I would not add PEP 566 JSON to anything. I was told not to when I tried to add it to packaging. If PEP 819 gets accepted, we could add that, but we should not add it before that PEP goes in; currently email metadata is the only stable format, and everyone seems to try to ignore that there every was a mention of JSON in PEP 566. Also, regardless of PEP 819, email metadata will be stable for a long time, so I don't think there's harm in it, even though I don't like it very much and would love to move to JSON eventually.
layday commentedon Jul 25, 2026
How would our CLI interface work with email metadata?
packaging.metadatais stable and produces JSON-encodable metadata, which, to my knowledge, follows the transformation rules of PEP 566. PEP 819 is about producing the original metadata in JSON - not re-encoding it.henryiii commentedon Aug 11, 2026
If we make a change now, and have to make a change later, that's a much higher maintenance burden than not doing anything until we need to. I think we should drop the deprecation in 1.6, and then investigate deprecation in 1.7.
packaging.metadataexplicitly choses not to have afrom_jsonoras_jsonuntil it is standardized properly. I added the current conversion back to email metadata in pypa/packaging#846 a year ago, and I actually had PEP 566 JSON support in the first version, was told "I don't know if I'm comfortable with the JSON support. I actually almost had it in the first version of the module, but decided against it until we had a standard around it." so I pulled it out. This is one of the things that helped push PEP 819 forward, I think.From a programatic standpoint, until JSON support gets more properly standardized, I don't think we should replace an email format with JSON one; I want to follow packaging here. If you want to use
packaging.metadataon the output, you have to have the email format anyway (it has afrom_email, but not afrom_json). I think this should remain, undeprecated, until we have a new JSON format that packaging is willing to adopt.What about returning
MetadataorRawMetadatafrom packaging? Then we could rely on its conversions, and not worry about formats. I'd also be okay withRawMetadata... Which... is the JSON format? It's a different framing (packaging.metadata compatibility, rather than PEP 566 JSON). Yes, verified it is the JSON format.As for the CLI, I think keeping the current JSON is fine regardless. Reparsing the not-quite-email format is unreasonable, you can't use it. JSON is a standard you can use from any language.
Okay, after writing all that, RawMetadata kind of changed things; here's my proposal:
build.util.project_wheel_metadatawith no visible warning yet.build.util.wheel_metadatathat returns RawMetadata. It can also validate deps (opt in or opt out or required option, haven't looked at it yet. I'm not a huge fan of dep validation on by default, but in a new API it's fine as long as there's an opt-out.)build.util.project_wheel_metadatain favor ofbuild.util.wheel_metadata. This gives people using it a path forward (>=1.6 and use the new function).layday commentedon Aug 11, 2026
Perhaps there's something I'm missing, but what is the difference between
packaging.metadata.RawMetadataand the transformation described under §JSON-compatible Metadata? This is a one-way transformation, in order to display or manipulate data in a JSON-compatible structure, such as a Python dictionary.RawMetadatais what the CLI uses, and what I was suggesting to use here a few comments up.henryiii commentedon Aug 13, 2026
I basically agreed with you by the end after I realized that's what
packaging.metadata.RawMetadatais. My proposal isbuild.util.wheel_metadatawith RawMetadata return, then eventually phase outbuild.util.project_wheel_metadata(but give them some overlap as we obviously have users!)layday commentedon Sep 20, 2026
The deprecation was reverted and won't be performed without a suitable replacement API, closing.