Skip to content

Deprecation of project_wheel_metadata points only at the CLI; the promised wheel_metadata() (from #1084) never shipped #1131

Closed

Description

@jaraco

Summary

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:

The fact that the tidy fix (#26) just re-inlines build's own non-deprecated internals suggests the capability should stay public.

Request

One of:

  1. Ship the wheel_metadata() described in ⚠️ feat(util): deprecate project_wheel_metadata #1084 (the deprecation message already implies it exists), or
  2. 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.

Activity

  1. gaborbernat commented on Jul 15, 2026

    @gaborbernat
    Contributor

    Done on purpose #1084 (comment)

  2. reopened this on Jul 15, 2026
  3. layday commented on Jul 15, 2026

    @layday
    Member

    I'm gonna go ahead and yank this (undiscussed) patch release as mentioned on Discord. We can revisit the deprecation of this function.

  4. jaraco commented on Jul 15, 2026

    @jaraco
    MemberAuthor

    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.

    Done on purpose #1084 (comment)

    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).

  5. gaborbernat commented on Jul 15, 2026

    @gaborbernat
    Contributor

    I'm +0.1 on keeping the helper (and implementing the requested validation in #557), but I'll defer to other maintainers on this.

  6. henryiii commented on Jul 16, 2026

    @henryiii
    Contributor

    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. :)

  7. layday commented on Jul 25, 2026

    @layday
    Member

    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.

  8. henryiii commented on Jul 25, 2026

    @henryiii
    Contributor

    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.

  9. layday commented on Jul 25, 2026

    @layday
    Member

    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.

  10. henryiii commented on Aug 11, 2026

    @henryiii
    Contributor

    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).
  11. layday commented on Aug 11, 2026

    @layday
    Member

    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.

  12. henryiii commented on Aug 13, 2026

    @henryiii
    Contributor

    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!)

  13. layday commented on Sep 20, 2026

    @layday
    Member

    The deprecation was reverted and won't be performed without a suitable replacement API, closing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions