jaraco / jaraco/jaraco.packaging

Deprecation: build.util.project_wheel_metadata (recommended replacement is a subprocess, and the promised Python API never shipped)

Open
#25 1 comment 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.