Visitar URL original
Require hints when rendering error chains by zanieb · Pull Request #20155 · astral-sh/uv · GitHub
Skip to content

Require hints when rendering error chains - #20155

Merged
zanieb merged 1 commit into
mainfrom
zb/explicit-error-hints
Jul 6, 2026
Merged

zanieb merged 1 commit into
mainfrom
zb/explicit-error-hints

Conversation

@zanieb

@zanieb zanieb commented Jul 6, 2026 •

Copy link
Copy Markdown
Member

Require callers of the error and warning chain renderers to provide a Hints collection explicitly.

This keeps ErrorOptions focused on presentation settings and makes omission of hint extraction visible at each call site. Existing call sites that do not have applicable hints pass Hints::none().

@zanieb zanieb added the internal A refactor or improvement that is not user-facing label Jul 6, 2026
@zanieb
zanieb marked this pull request as ready for review July 6, 2026 19:36
@zanieb
zanieb enabled auto-merge (squash) July 6, 2026 19:39
@zanieb
zanieb merged commit 2cf679f into main Jul 6, 2026
108 of 110 checks passed
@astral-sh-bot

astral-sh-bot Bot commented Jul 6, 2026

Copy link
Copy Markdown

uv test inventory changes

This PR changes the tests when compared with the latest main baseline.

  • Added tests: 0
  • Removed tests: 1
  • Changed suites: 1
uv-fs: +0 / -1

Added: none

Removed:

  • uv-fs::read::tests::reads_without_utf_8_validation

@zanieb
zanieb deleted the zb/explicit-error-hints branch July 6, 2026 20:02
zanieb added a commit that referenced this pull request Jul 7, 2026
Preserve authored line breaks inside nested error causes and indent
those authored lines by four spaces.

Wrapped continuation lines retain their hanging indentation, while lines
that were already present in the error message keep the diagnostic's
previous four-space nesting. The behavior also applies when line
wrapping is disabled or no terminal width is available.

This is stacked on #20155, which makes hints an explicit renderer
argument.
zanieb added a commit that referenced this pull request Sep 11, 2026
Rename `uv_errors::Hint` to `Hinted`. The trait describes an error's
ability to provide a collection of contextual hints, while `Hint` is a
clearer name for an individual hint value. Update the implementations,
trait bounds, and callers without changing diagnostic output or error
classification.

Prior work:

- #18090 introduced the hint-producing trait and `Hints` collection.
- #20155 made hints explicit in error-chain rendering.

This prepares the concrete `Hint` type in #21577.
zanieb added a commit that referenced this pull request Sep 11, 2026
Hint ordering currently depends on error-chain traversal and manually
appending caller-provided advice. Add `HintOrdering::{First, Any, Last}`
to individual `Hint` values and `Hints` collections so error types can
specify where their guidance belongs. Borrowed iteration visits the
three groups without sorting or allocating; owned iteration sorts the
existing vector. Both retain insertion order within each group. Error
and warning renderers borrow the collection. Unannotated hints use
`Any`, and merging duplicate messages retains the earliest ordering. The
operation reporter's caller-provided hints and tool script usage advice
use `Last`.

Prior work:

- #18090 introduced the `Hint` and `Hints` APIs.
- #20155 made hints explicit in error-chain rendering.
- #21584 renamed the hint-producing trait to `Hinted`.

This provides the ordering primitive for #17110 without requiring the
command-layer collector to special-case error types.
zanieb added a commit that referenced this pull request Sep 11, 2026
Route the remaining package-operation errors through `UvError` and the
standard error-chain renderer, then remove uv's direct `miette`
dependency and global hook. Diagnostics use the same source-chain
formatting and hint collection as other commands, with cause-specific
hints before general command advice. No-solution headings omit trailing
punctuation, retain their command context, and are not repeated inside
build-dependency errors. Final errors remain visible with `-q` and are
suppressed with `-qq`.

Classify operation failures by their underlying cause instead of by
which renderer handles them. Each error type owns its classification,
and type-erased build errors forward it. Expected package, resolution,
build, integrity, and lock-validation failures use code 1, while
recognized transport, cache, filesystem, and internal failures use code
2. This deliberately changes some previously inconsistent statuses
without attempting to normalize every standalone command or opaque
archive-error path. Command-line argument errors remain code 2.
Third-party dependencies may still use `miette` internally.

Prior work:

- #14546 removed `miette` from `uv venv`.
- #17535 added first-party line wrapping.
- #18090 established the `Hint` and `Hints` APIs.
- #20155 made hints explicit in error-chain rendering.
- #20156 preserved indentation in multiline causes.
- #20159 migrated `uv build` errors to standard rendering.
- #20160 migrated tool requirement errors to standard rendering.
- #20188 introduced the explicit `UvError` model.
- #20163 routed final errors through `Printer` for `-q` and `-qq`.
- #20217 enabled cause-chain rendering for user errors.
- #21563 added verification of index-provided metadata hashes.
- #21279 reused URL-provided hashes during resolution.
- #21584 renamed the hint-producing trait to `Hinted`.
- #21577 added explicit hint ordering.

Follow-up work:

- #21566 collects hints for batched `uv tool upgrade` failures and fixes
their quiet-mode output.
- #21568 routes Python upgrade request errors and version-file hints
through `UvError`.
- #21587 separates operation-specific diagnostic context from
exit-status classification.
- #21599 renders error and warning causes with compact tree connectors.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

internal A refactor or improvement that is not user-facing

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant