Skip to content

fix: report malformed project and archive inputs as BuildException (#1264) - #1298

Closed
v01dst wants to merge 2 commits into
pypa:mainfrom
v01dst:fix/1264-build-exception-for-malformed-input
Closed

v01dst wants to merge 2 commits into
pypa:mainfrom
v01dst:fix/1264-build-exception-for-malformed-input

Conversation

@v01dst

@v01dst v01dst commented Nov 18, 2026 •

Copy link
Copy Markdown

Why I made this PR

The API guide shows callers handling BuildException, but several malformed inputs raise the raw exception from the standard library or from packaging instead, so that pattern does not catch them and the CLI prints a traceback before its error line. The failure mode then depends on which malformed input was handed to build.

Description

Every malformed input is now reported as a BuildException, which the CLI already turns into a one-line error and the documented except BuildException pattern catches:

Input Before After
pyproject.toml that is not valid UTF-8 UnicodeDecodeError BuildException
pyproject.toml that is a directory IsADirectoryError (Linux), PermissionError (Windows) BuildException
backend-path entry that is absolute or leaves the source tree ValueError from pyproject-hooks BuildSystemTableValidationError
invalid requirement string in requires packaging.requirements.InvalidRequirement BuildException
source distribution that is not a tar archive tarfile.ReadError BuildException
wheel that is not a zip file zipfile.BadZipFile BuildException

Notes on the choices:

  • The backend-path check mirrors the one pyproject-hooks does (norm_and_check), so the error is raised while build is still validating the [build-system] table and the message names the offending entry.
  • The source distribution case restores the handling that 1.6.1 had (failed to read source distribution ...); it was lost in 13cda2c.
  • A source distribution with an unsafe member (path traversal, absolute symlink) still raises the tarfile error from the data filter, as before. That is a malicious archive being rejected rather than a malformed input, and the existing tests pin that behavior.
  • pyproject.toml as a directory raises PermissionError on Windows and IsADirectoryError on Linux, so both are handled.

The BuildException messages name the file and the reason, so the CLI prints one line instead of a traceback:

$ python -m build --metadata demo-1.0-py3-none-any.whl
ERROR 'demo-1.0-py3-none-any.whl' is not a valid wheel: File is not a zip file

Changelog

  • Added changelog fragment: docs/changelog/1298.bugfix.rst.

Checklist

  • I looked at the contributing guide (docs/development/contributing.rst)
  • Tests pass locally (pytest suite, ruff format and check, pyrefly)
  • The PR description is not significantly longer than the change
AI assistance (supporting detail, reviewed by the author)

The reproduction and the test cases were written with an AI coding assistant (OpenCode, MiniMax-M3.1-Flash). The author checked the behaviour of every path against the code on main before and after the change: each malformed input raised the raw exception listed in the table above before the change and raises the listed BuildException after it. The test suite was run locally with Python 3.12 on Windows (362 passed, 3 skipped).

v01dst added a commit to v01dst/build that referenced this pull request Nov 18, 2026
Signed-off-by: v01dst <v01dst@users.noreply.github.com>
`backend-path` entries have to stay inside the source tree (PEP 517), but
`build` only checked that the entry was a directory.

An entry that leaves the source tree (`..`, an absolute path) was handed to
`pyproject-hooks`, which raised a bare `ValueError`. The `except
BuildException` pattern shown in the API guide does not catch it, and the CLI
prints a traceback before its error line.

An entry that is a symlink to a directory outside the source tree was
accepted, and `build` then imported the backend from outside the tree.

`_validate_backend_path` now checks every entry before the hook caller is
created. The containment check resolves symlinks on both sides and compares
the results with `pathlib.Path.is_relative_to`, so it does not need the
cross-drive special case that `os.path.commonpath` needs on Windows. The
directory check runs first, so an entry that cannot be resolved at all is
still reported the way it was before.

Fixes pypa#1267.
Refs pypa#1264.

Signed-off-by: v01dst <v01dst@users.noreply.github.com>
Signed-off-by: v01dst <v01dst@users.noreply.github.com>
@v01dst
v01dst force-pushed the fix/1264-build-exception-for-malformed-input branch from 234c02e to d5fd170 Compare November 18, 2026 23:57
@v01dst

v01dst commented Nov 19, 2026

Copy link
Copy Markdown
Author

Closing this in favour of #1299, which is the same fix with the scope narrowed.

I read the discussion on #1264 again before finalising this one: @henryiii picked out backend-path as the case worth handling, and @layday and @gaborbernat were of the opinion that the other exceptions are reasonable as they are. The first version of this pull request wrapped five different exceptions, which went against that.

#1299 only changes _validate_backend_path:

  • an entry that leaves the source tree (.., an absolute path) is now a BuildSystemTableValidationError instead of a bare ValueError from pyproject-hooks,
  • an entry that is a symlink to a directory outside the source tree is rejected instead of being used to import a backend from outside the tree (backend-path accepts symlinks outside the source tree #1267).

The other malformed inputs from #1264 are not touched.

@v01dst v01dst closed this Nov 19, 2026
@v01dst
v01dst deleted the fix/1264-build-exception-for-malformed-input branch November 19, 2026 00:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant