Skip to content

✨ feat(cli): machine-readable build report, and metadata from a wheel - #1080

Merged
gaborbernat merged 5 commits into
pypa:mainfrom
gaborbernat:198-machine-readable-report
Jun 12, 2026
Merged

gaborbernat merged 5 commits into
pypa:mainfrom
gaborbernat:198-machine-readable-report

Conversation

@gaborbernat

@gaborbernat gaborbernat commented Jun 3, 2026 •

Copy link
Copy Markdown
Contributor

Closes #198.

Anyone wiring build into a release pipeline hits the same wall: once the build finishes, they need to know which files came out so they can upload, sign, or checksum them. The filenames are not predictable, since they carry the version and, for wheels, the Python, ABI and platform tags. So today people reach for workarounds that each have a sharp edge. They glob dist/* and trust that the next tool expands it (only twine does; pip install dist/* does not). They rm -rf dist before every build so a stale artifact from last time does not get published by accident. They scrape the coloured Successfully built … line off the terminal. Or they drop down to the Python API and reimplement a chunk of the CLI. 📦 None of these is something we want to be the recommended path.

This adds a first-class answer: python -m build --report dist/report.json writes a small JSON file describing exactly what was produced — each artifact's name, path, kind (sdist or wheel), size, and SHA-256 hash. A pipeline can then do twine upload $(jq -r '.artifacts[].path' dist/report.json) and be certain it is shipping this build's output and nothing else. Including the hash also gives projects a ready hook for provenance and checksums (the ask from #789, folded in here). ✨

The report goes to a file the frontend owns rather than to stdout, because the build backend runs as a subprocess that can print to stdout itself — so a structured payload there could never be parsed safely. The report is JSON and its version field is a schema version, so the format can grow later without breaking readers. The default python -m build experience is untouched and the feature is entirely opt-in.

Building on that, --metadata now also accepts a built wheel: python -m build --metadata dist/mypackage-1.0.0-py3-none-any.whl reads the wheel's METADATA and prints it as JSON without building anything. A pipeline can lift a wheel's path straight out of report.json and inspect what it shipped — no rebuild, no unzip.

Workarounds people use today

The fragile stopgaps people reach for in the issue threads until this lands:

  • #198 (comment) — rm -rf dist before each build, then twine upload dist/* relying on twine's own glob expansion to avoid shipping stale artifacts.
  • #198 (comment) — the catch: pip install dist/* does not glob-expand, so CI still has to discover the dynamically named files some other way.
  • #198 (comment) — the original ask: write a manifest JSON and pipe its path through jq into the installer.
  • #198 (comment) — hand-rolling a JSON file in dist/, which then breaks because twine dist/* tries to upload the JSON to PyPI.
  • #198 (comment) — confirmation that stdout/stderr scraping cannot work (the backend writes there too), with uv#2314 and twine#281 showing the same problem hit elsewhere.
  • #789 (comment) — the rebuttal to scraping the coloured Successfully built … line for digests: build logs are the wrong place; machine-readable output is the real fix.

Seen in the wild on GitHub

Release pipelines wipe dist/ first, then re-discover the produced files by globbing, because nothing tells them the names:

@gaborbernat gaborbernat added the enhancement New feature or request label Jun 3, 2026
@gaborbernat gaborbernat closed this Jun 3, 2026
@gaborbernat gaborbernat reopened this Jun 4, 2026
@gaborbernat
gaborbernat force-pushed the 198-machine-readable-report branch 2 times, most recently from db5d10d to 7467525 Compare June 4, 2026 00:27
@gaborbernat
gaborbernat marked this pull request as ready for review June 4, 2026 00:39
@layday

layday commented Jun 4, 2026

Copy link
Copy Markdown
Member

I like this, but I think we should make it work with --metadata in some fashion. Perhaps --metadata could accept a wheel as input, the path of which would be extracted from the report, and generate its metadata. (This can happen in a follow-up.)

Comment thread src/build/__main__.py Resolved
@gaborbernat
gaborbernat force-pushed the 198-machine-readable-report branch from 7467525 to 0376bda Compare June 4, 2026 22:37
@gaborbernat
gaborbernat requested a review from layday June 4, 2026 22:43
@gaborbernat gaborbernat changed the title ✨ feat(cli): add machine-readable build report ✨ feat(cli): machine-readable build report, and metadata from a wheel Jun 5, 2026
@gaborbernat
gaborbernat force-pushed the 198-machine-readable-report branch from c9cf8aa to 9d66ae8 Compare June 6, 2026 00:56
@gaborbernat
gaborbernat force-pushed the 198-machine-readable-report branch 2 times, most recently from d3508d2 to b82d46c Compare June 9, 2026 14:53
@layday

layday commented Jun 9, 2026

Copy link
Copy Markdown
Member

I'm just thinking if this shouldn't be co-located with the built dists. I feel like having to pass a path to --report might be a little too much friction? I'd personally never not want to produce a report; if build would do this by default, I'd be happy. I could live with having to specify a flag, but having to pass the path feels a little redundant.

@gaborbernat
gaborbernat force-pushed the 198-machine-readable-report branch 2 times, most recently from 1ba9f57 to 96cd2f3 Compare June 9, 2026 19:29
@gaborbernat

Copy link
Copy Markdown
Contributor Author

Good point on the friction — reworked. --report is now a no-arg flag: by default it writes build-report.json next to the distributions in --outdir, so the common case is just python -m build --report. An optional --report PATH is still there for a custom location.

I kept it opt-in rather than always-on, since writing a file the user didn't ask for felt surprising — but it's now zero-config when you do want it.

On concurrency: the write is atomic (temp file + os.replace), so a reader never sees a partial file, but two builds sharing one --outdir overwrite each other's build-report.json (last wins) — the same way their distributions would. I documented that parallel builds with differing args should use separate --outdir (or distinct --report PATH), since a per-build output dir is the safer pattern regardless.

@henryiii

henryiii commented Jun 12, 2026 •

Copy link
Copy Markdown
Contributor

I'm not sure putting it in the outdir is always the best (I'm at least happy there's a report path option!) twine upload dist/* is the standard way to upload (even explicitly done that way in the intro tutorial!), and that would probably break if there's suddenly a non-wheel/sdist file. In fact, the whole argument for #455 was to keep the outdir clean, and now we are putting an extra non-uploadable file into it?

I'd prefer the path be required, I think. I can't think of a good reason to put it in the dist/ folder (breaks uploads) or in the source folder (would often get picked up and placed in the sdist), so just forcing a choice is probably best?

(If twine does ignore non-wheel non-sdist files even when passed explicitly via shell expansion, that would be better. Also if it was prefixed by a dot, then shell expansion wouldn't pick it up, that's another option).

@layday

layday commented Jun 12, 2026

Copy link
Copy Markdown
Member

That's a good point. Maybe we should discuss this with the twine team, to see if there's any appetite for uploading files from a manifest.

@gaborbernat

Copy link
Copy Markdown
Contributor Author

My initial design was to let the report flag take a directory, and now that another maintainer also prefered that, I'll revert to it. I think is a cleaner approach 😊

@henryiii

Copy link
Copy Markdown
Contributor

Why not just make it take the full path (--report=dist/anything.json), then we can work on a "flag-less" version later once we see if twine can ignore it and pick default names and location then?

Test added 4 commits June 12, 2026 12:05
After a build, downstream steps such as uploading, signing, or recording
checksums need the exact artifact filenames. Those names are dynamic since
they encode the version and the wheel's Python, ABI and platform tags, so
today users glob dist/ (and often clear it first) or scrape the success line
off stdout. Neither is reliable.

Add --report PATH, which writes a JSON document listing each artifact's name,
path, kind, size and SHA-256 hash, selected with --output-format. The report
goes to a file build owns rather than stdout because the backend subprocess
may write to stdout itself, so a structured payload there could not be parsed.
Including hashes also covers the request to surface digests for provenance.
Building on --report, let --metadata take a .whl as its source
argument and read the wheel's METADATA directly instead of building.
A wheel path lifted from the report can then be inspected without a
rebuild. A wheel passed without --metadata is rejected, since build
cannot build from a wheel.

Also drop typing from __main__'s lazy modules: the report's TypedDict
subclasses are evaluated at import, so typing must load eagerly.
Address review: the name is too generic while JSON is the only format.
Reintroduce under a clearer name if more formats are added later. The
report stays JSON.
The schema sample had placeholder sizes and the empty-string SHA-256 on
both artifacts. Replace it with the actual JSON from a real build,
including the expanded hashes object json.dumps emits.
Writing build-report.json into the output directory by default put a
non-distribution file where `twine upload dist/*` style workflows would
trip over it, and keeping the outdir clean was the whole argument for
the default outdir behavior in pypa#455. Review on pypa#1080 settled on always
asking the caller where the report goes.

Drop the optional-argument form so --report takes the report file path,
and steer the docs examples away from the output directory. A flag-less
default can return later if twine learns to skip non-distribution
files.
@gaborbernat
gaborbernat force-pushed the 198-machine-readable-report branch from 96cd2f3 to 68bd564 Compare June 12, 2026 19:14
@gaborbernat

Copy link
Copy Markdown
Contributor Author

Done — --report now requires the file path (--report build-report.json), there is no default location. The docs steer the examples away from the output directory so twine upload dist/* workflows stay safe, and a flag-less default can come later if twine learns to ignore non-distribution files. Also rebased onto latest main.

@gaborbernat
gaborbernat merged commit 254be0c into pypa:main Jun 12, 2026
59 checks passed
@gaborbernat
gaborbernat deleted the 198-machine-readable-report branch June 29, 2026 22:29
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.

Machine-readable build report

3 participants