Skip to content

⚠️ feat(util): deprecate project_wheel_metadata - #1084

Merged
gaborbernat merged 1 commit into
pypa:mainfrom
gaborbernat:557-validate-no-isolation-deps
Jun 9, 2026
Merged

gaborbernat merged 1 commit into
pypa:mainfrom
gaborbernat:557-validate-no-isolation-deps

Conversation

@gaborbernat

@gaborbernat gaborbernat commented Jun 4, 2026 •

Copy link
Copy Markdown
Contributor

Closes #557.

Teams that read a project's metadata without a full isolated build, for example a docs site that needs the current version or a packager pulling the name and dependencies, hit a quiet failure today. When they call project_wheel_metadata with isolated=False, build trusts whatever happens to be in the current environment and runs the backend anyway. If a declared build dependency is absent, the backend does not fail; it returns a wrong answer. The version comes back as 0.0.0 when something like setuptools_scm is not installed, and nobody notices until a release looks broken. 📉

What people do today is pick the lesser of two problems. They either pay for a throwaway virtualenv on every metadata read, which rules out offline and air-gapped machines and slows docs builds, or they switch to isolated=False and accept that the result might be silently wrong. The original report walked through exactly this: a documentation build moved to the non-isolated path to work offline, and the version it recorded dropped from a real value to 0.0.0 with no warning.

This adds build.util.wheel_metadata, which returns a project's metadata as a parsed, JSON-serialisable mapping — the same structure python -m build --metadata prints — and takes a check_dependencies flag. ✅ With isolated=False and check_dependencies=True, build confirms the declared build dependencies are present against the interpreter actually running, and stops with a clear DependencyError when one is missing, instead of returning a misleading result. The command line already runs this check under --no-isolation, so the two now behave the same way.

project_wheel_metadata is deprecated in favour of it. 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. 📦

When a check fails, the message names the interpreter it inspected and, for each requirement, the version that was wanted against the version that was found. That tells a user whether a package is genuinely absent or merely the wrong version, and it points at the common gotcha where a dependency was installed for a different Python than the one running build.

Workarounds people use today

How people cope with silent wrong metadata on the non-isolated path until this lands:

  • jaraco.packaging#9 (comment) — the canonical reproduction: a missing setuptools_scm makes the recorded version collapse from a real value to 0.0.0 with no error.
  • #556 (comment) — set BUILD_ENVIRONMENT=current (jaraco.packaging ≥ 9.5) to read metadata against the current interpreter.
  • #556 (comment) — pre-stage build deps as wheels and force pip offline with PIP_NO_INDEX=1 PIP_FIND_LINKS=..
  • jaraco.packaging#11 (comment) — a per-library env var to bypass isolation, the wrong-layer patch that motivated fixing build itself.
  • #557 (comment) / clarification — pass --no-isolation -x, accepting that project_wheel_metadata does no dependency check at all.
  • pytest-checkdocs#19 (comment) — a downstream consumer left broken by the per-project patch, showing why the fix belongs in build.

Seen in the wild on GitHub

Packagers reading metadata or building without isolation pre-provide the build deps by hand:

@gaborbernat gaborbernat added the enhancement New feature or request label Jun 4, 2026
@gaborbernat
gaborbernat force-pushed the 557-validate-no-isolation-deps branch from 94f425c to 20b44d2 Compare June 4, 2026 00:41
@gaborbernat
gaborbernat marked this pull request as ready for review June 4, 2026 00:45
@gaborbernat
gaborbernat force-pushed the 557-validate-no-isolation-deps branch from 20b44d2 to 4c5bb7d Compare June 4, 2026 22:37
@layday

layday commented Jun 5, 2026 •

Copy link
Copy Markdown
Member

My preference would be to deprecate and eventually remove project_wheel_metadata. This function has fallen behind the CLI's implementation (which parses the metadata into a user-friendlier JSON structure) and was conceived at a time when we were reluctant to extend the CLI with a metadata extraction command. __main__._build_metadata can be made public to compensate.

@gaborbernat

Copy link
Copy Markdown
Contributor Author

Done. Added build.util.wheel_metadata, which returns the parsed, JSON-serialisable metadata the --metadata CLI prints (a packaging.metadata.RawMetadata), and moved the check_dependencies option onto it. Deprecated project_wheel_metadata (DeprecationWarning + changelog removal note) pointing at the new function.

I exposed it as build.util.wheel_metadata rather than literally promoting __main__._build_metadata, to keep the public surface in build.util next to the function it replaces and avoid leaking the CLI-only knobs (installer, constraints, config-settings). Happy to rename or relocate if you'd prefer a different home.

@gaborbernat gaborbernat changed the title ✨ feat(util): validate dependencies in non-isolated metadata reads ✨ feat(util): add wheel_metadata, deprecate project_wheel_metadata Jun 5, 2026
@gaborbernat
gaborbernat force-pushed the 557-validate-no-isolation-deps branch from 0b7501d to ad57096 Compare June 6, 2026 01:35
@layday

layday commented Jun 6, 2026

Copy link
Copy Markdown
Member

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.

@gaborbernat

Copy link
Copy Markdown
Contributor Author

So what do you think we should do today then? 🤔 close this and the related issue as won't fix? 🤔

@layday

layday commented Jun 6, 2026

Copy link
Copy Markdown
Member

That we should simply deprecate project_wheel_metadata - let me know if you think otherwise though.

@gaborbernat

Copy link
Copy Markdown
Contributor Author

And what should we guide users towards, using the cli?

`project_wheel_metadata` returns an `email.message.Message`-style object and
has fallen behind the CLI, which now generates parsed, JSON-serialisable
metadata. Rather than grow a second utility function that would drift again,
deprecate it and steer callers to the `python -m build --metadata` command.

The function keeps working and emits a DeprecationWarning pointing at the CLI.
@gaborbernat
gaborbernat force-pushed the 557-validate-no-isolation-deps branch from 70cb0a1 to 1706696 Compare June 9, 2026 06:30
@gaborbernat gaborbernat changed the title ✨ feat(util): add wheel_metadata, deprecate project_wheel_metadata ⚠️ feat(util): deprecate project_wheel_metadata Jun 9, 2026
@gaborbernat
gaborbernat merged commit cd56622 into pypa:main Jun 9, 2026
59 checks passed
@gaborbernat
gaborbernat deleted the 557-validate-no-isolation-deps branch June 29, 2026 22:29
@astrojuanlu

astrojuanlu commented Jul 3, 2026 •

Copy link
Copy Markdown

Doesn't this mean that now there's no public, programmatic, non-deprecated API to get the metadata?

Promoting __main__._build_metadata doesn't seem very useful without some code changes, it's clearly made for the CLI:

build/src/build/__main__.py

Lines 477 to 479 in 43c337a

_print_metadata(metadata_file.read())
return []

@astrojuanlu

Copy link
Copy Markdown

In the meantime, I rescued @gaborbernat 's implementation from the git push --force abyss and preserved it in astrojuanlu@701775c

@gaborbernat

Copy link
Copy Markdown
Contributor Author

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.

We removed it per this idea 😊

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

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Validate dependencies in non-isolated builds

3 participants