Repository navigation
⚠️ feat(util): deprecate project_wheel_metadata - #1084
Conversation
94f425c to
20b44d2
Compare
20b44d2 to
4c5bb7d
Compare
|
My preference would be to deprecate and eventually remove |
|
Done. Added I exposed it as |
0b7501d to
ad57096
Compare
|
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. |
|
So what do you think we should do today then? 🤔 close this and the related issue as won't fix? 🤔 |
|
That we should simply deprecate |
|
And what should we guide users towards, using the cli? |
ad57096 to
70cb0a1
Compare
`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.
70cb0a1 to
1706696
Compare
|
Doesn't this mean that now there's no public, programmatic, non-deprecated API to get the metadata? Promoting Lines 477 to 479 in 43c337a |
|
In the meantime, I rescued @gaborbernat 's implementation from the |
We removed it per this idea 😊 |
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_metadatawithisolated=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 as0.0.0when something likesetuptools_scmis 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=Falseand 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 to0.0.0with no warning.This adds
build.util.wheel_metadata, which returns a project's metadata as a parsed, JSON-serialisable mapping — the same structurepython -m build --metadataprints — and takes acheck_dependenciesflag. ✅ Withisolated=Falseandcheck_dependencies=True, build confirms the declared build dependencies are present against the interpreter actually running, and stops with a clearDependencyErrorwhen 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_metadatais deprecated in favour of it. As noted in review, it returns anemail.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:
setuptools_scmmakes the recorded version collapse from a real value to0.0.0with no error.BUILD_ENVIRONMENT=current(jaraco.packaging ≥ 9.5) to read metadata against the current interpreter.PIP_NO_INDEX=1 PIP_FIND_LINKS=..builditself.--no-isolation -x, accepting thatproject_wheel_metadatadoes no dependency check at all.build.Seen in the wild on GitHub
Packagers reading metadata or building without isolation pre-provide the build deps by hand:
python-jaraco.stream.spec(L62-L64) —export BUILD_ENVIRONMENT=currentso the Sphinx metadata read uses the rpmBuildRequiresinstead of an isolated build.twineAPKBUILD (L48) —python3 -m build --no-isolation --skip-dependency-check, withpy3-setuptools_scmhand-added tomakedepends(L24-L27).apache-arrowPortfile (L353) —-m build --no-isolationpaired with a manually listedsetuptools_scmbuild dep (L250).--no-isolationthe venv must contain every[build-system].requiresentry, after a silent failure from the missing ones.