jaraco / jaraco/jaraco.packaging
Deprecation: build.util.project_wheel_metadata (recommended replacement is a subprocess, and the promised Python API never shipped)
- Dominant language
- Python
- Stars
- 4
- Forks
- 5
- PR merge metrics
- No merged PRs in 30d
Description
## Deprecation
Since [`build` 1.5.1](https://build.pypa.io/en/stable/changelog.html), `build.util.project_wheel_metadata` — which `jaraco.packaging.metadata.load` wraps — emits a `DeprecationWarning`:
> `project_wheel_metadata is deprecated; generate metadata with the `python -m build --metadata` command instead`
Surfaces in our own test run:
```
jaraco/packaging/metadata.py:24: DeprecationWarning: project_wheel_metadata is deprecated;
generate metadata with the `python -m build --metadata` command instead
```
## Origin / motivation
The deprecation traces back to a report of *ours*:
- pypa/build#557 (*Validate dependencies in non-isolated builds*, filed by @jaraco), whose canonical reproduction is jaraco.packaging#9 — with `isolated=False` and a missing build dep (e.g. `setuptools_scm`), the backend does not fail; the recorded version silently collapses to `0.0.0`.
- Deprecated via pypa/build#1084 (@gaborbernat). The stated goal: retire an API that returns an `email.message.Message`-style object and had fallen behind the CLI, in favour of a dependency-checked replacement that returns the same JSON structure `python -m build --metadata` prints.
## The catch
pypa/build#1084's **description** promises a supported Python replacement, `build.util.wheel_metadata()` (with a `check_dependencies` flag). But the **merged diff only adds the deprecation warning** — no `wheel_metadata` exists in 1.5.1 or on `build`'s `main`. The only replacement that actually shipped is the CLI: `python -m build --metadata`.
So the recommended migration replaces a supported in-process API with a **subprocess call**, which:
- adds complexity (spawn a child interpreter, capture stdout);
- loses fidelity — `load()` currently returns a live `importlib.metadata.PackageMetadata` object, and every downstream consumer here (`hunt_down_url`, `get_source_url`, `extract_author`, `extract_email`) relies on `.get()`, `.get_all()`, and `meta['Author-email']`. JSON-over-subprocess discards that interface.
Notably, `build.util._project_wheel_metadata` (the non-deprecated internal core) still does exactly what we want in-process, via the public `ProjectBuilder` / `DefaultIsolatedEnv` / `builder.metadata_path()` building blocks.
## Options
1. **Reimplement in-process** using build's still-public `ProjectBuilder` + `metadata_path()` (mirroring `_project_wheel_metadata`), preserving the `PackageMetadata` return type and all current consumers. No subprocess, no downstream churn.
2. **Follow the official recommendation** — call `python -m build --metadata`, parse JSON, and rewrite the consumers. Higher complexity, loss of the metadata object.
3. **Engage upstream** — pypa/build shipped a deprecation pointing at a CLI while the promised `wheel_metadata` API never landed; push to restore a supported programmatic entry point (or ship `wheel_metadata`) before we migrate.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with jaraco/packaging/metadata.py and its load(), hunt_down_url, get_source_url, extract_author, and extract_email consumers. Compare the documented build.util.project_wheel_metadata deprecation with build.util._project_wheel_metadata and the ProjectBuilder, DefaultIsolatedEnv, and metadata_path() building blocks; the issue needs a decision on an in-process migration, CLI migration, or upstream engagement before implementation can be considered done.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100