Make hook tracing unable to fail a hook call

[RonnyPfannschmidt]

AI-authored. I asked Claude Code (Opus 5) to work through the tracing PR
cluster and produce a single change superseding it. The code, the tests, the
measurements and the text below are the agent's work. I read it and I am
posting it, and I will follow up on review comments myself.

Closes #424. Closes #681. Supersedes #627, #666, #684, #716.

The two bugs

Tracing can turn a working hook call into a failing one:

• Avoid erroring from tracing #424 — an object whose __repr__/__str__ raises propagates that exception
  out of the hook call (originally kedro-org/kedro#2630).
• Tracing crashes with UnicodeEncodeError on surrogate escapes in hook arguments/results #681 — a lone surrogate in a hook argument or return value produces a message
  the writer cannot encode (originally pytest-dev/pytest#13750).

Against main, with a writer that encodes to utf-8 the way pytest's --debug file does:

surrogate    UnicodeEncodeError: 'utf-8' codec can't encode character '\ud800' in position 25
broken repr  RuntimeError: repr is broken

With this branch, both print OK.

The change

One helper in _tracing.py, in the shape of pytest's saferepr (as #424 asked for),
applied to both the positional labels and the keyword values:

• _safe_str() — KeyboardInterrupt and SystemExit still propagate, anything else
  renders as <[RuntimeError('str is broken') raised in str()] BrokenStr object at 0x...>.
  BaseException rather than Exception, because pytest's OutcomeException — and so
  pytest.fail()/skip() — sits outside the Exception hierarchy, and a __repr__
  that fails a test while --debug is on is exactly the reported scenario.
• _escape_surrogates() afterwards — backslashreplace, which also covers surrogates
  that come out of an object's own __repr__, a case repr() alone does not fix. It
  short-circuits on ASCII text, which is nearly all of it.

pytest --debug output is unchanged: 674 trace lines on a sample run, byte for byte
identical to main once addresses are normalised. Nothing is added, nothing is quoted,
nothing is reformatted — the only difference is that the two inputs above no longer raise.

Why the trace output is left alone, despite #681

#681 and #627 also called for rendering traced values with repr() so their type is
visible (plugin_name: 'lfplugin', start_path: PosixPath('/x')). The first commit here
implements that; the second backs it out. Both are kept so the decision is reviewable.

The reason is that the trace is pytest UX. --debug output is read by a human
scanning for the hook that misbehaved, and a fix for a crash nobody hits in normal use
should not make that scan worse for everyone who does. I am not willing to take that
trade in pluggy — the fix has to be invisible to people who were not hitting the bug.

The worst case is a value meant to be read as a block. With enable_assertion_pass_hook,
pytest passes the assertion explanation to pytest_assertion_pass as a multi-line string.
Under str() the trace shows it as written:

    expl: {'x': [0, 1, ...} == {'x': [0, 1, ...}

      Omitting 2 identical items, use -vv to show
      Use -v to get more diff

Under repr() the same value becomes one escaped line:

    expl: "{'x': [0, 1, ...} == {'x': [0, 1, ...}\n  \n  Omitting 2 identical items, use -vv to show\n  Use -v to get more diff"

The measurement that settles it, taken on a real pytest --debug run — 439 traced kwarg
values, of which 123 render differently under repr():

what changes	count
a string gains quotes (lfplugin → 'lfplugin')	~115
a path gains its type (/tmp/x → PosixPath('/tmp/x') / local('/tmp/x'))	13
an enum gains its name (1 → <ExitCode.TESTS_FAILED: 1>)	2

94% of the delta is quote noise on strings that were already readable. The genuine wins
are real — path and collection_path printing the same text while being a
py.path.local and a PosixPath is exactly the confusion a trace should resolve — but
they are 15 lines out of 674, and they are not worth the other 115.

None of that blocks the bug fixes: they never depended on repr(). The guard and the
surrogate escaping live in _safe_str, so #424 and #681 close either way. Surrogates
render as arg: \ud800 rather than arg: '\ud800'; both are legible, neither raises.

So the type-visibility idea is not rejected, only unbundled. If it is still wanted it can
be argued on its own merits in #681 — as a deliberate output change, with its own
changelog entry and its own discussion about what pytest's debug log should look like —
rather than riding along with a crash fix that has to ship regardless.

The one thing repr() would buy on such a value is keeping the log's one-line-per-value
structure intact for a machine reading it. That is a parsing concern, and it does not
outweigh making the block unreadable for the person the log is written for.

Relation to the existing PRs

Each approach against the same matrix (all cells measured, not assumed):

input	main	#666	#684	#716	this PR
surrogate in a kwarg	crash	crash	fixed	fixed	fixed
surrogate in the hook result	crash	crash	fixed	fixed	fixed
object whose __repr__ returns a surrogate	crash	crash	crash	fixed	fixed
object with a broken __repr__	crash	fixed	crash	crash	fixed
value passed positionally by a downstream pm.trace() caller	crash	fixed	not covered	fixed	fixed
pytest --debug output unchanged	—	yes	no (16% of lines, plus escaped blocks)	yes	yes

• Handle broken repr in tracing #666's guard is carried over and widened — BaseException rather than Exception,
  and pytest's message format rather than a bespoke one. Its test is carried over. Thanks
  @ShipItAndPray.
• fix: safe formatting for surrogates in pluggy tracing #716's insight that positional args need sanitising too is carried over, and it is
  what keeps downstream pm.trace() callers (pytest calls it directly) safe — and what
  makes the _manager.py change in Escape surrogate values in tracing output #684 unnecessary. Thanks @ltsyk.
• Escape surrogate values in tracing output #684 contributed the regression tests for both the kwarg and the result path, which
  are carried over; its repr() change is the part discussed above. Thanks @Himanshuagrawal4.
• Unicode encoding error #627 is where all of this was worked out. Thanks @Ghanchu.

Testing

• uv run pytest — 180 passed.
• uv run pre-commit run -a — all hooks pass.
• _tracing.py at 100% statement and branch coverage.
• 13 new tests: 7 fail on main, 2 pin the existing str rendering and the already-correct
  handling of legible non-ASCII, and 4 cover the guards themselves — an exception whose
  own repr fails, one whose repr and str both fail, and KeyboardInterrupt raised from
  the value and from the explanation.
• pytest --debug output diffed against main: 0 differences.

🤖 Generated with Claude Code

[bluetech]

Thanks, LGTM with some comments.

[bluetech]

Does _format_str_exception catch exception because the "{obj}" can fail?

[RonnyPfannschmidt]

people do fun stuff with outcome exceptions

[RonnyPfannschmidt]

Written by Claude Opus 5.5 via Claude Code for the pluggy reviewers; I prompted it, it did the work, I read it.

Yes. _try_repr_or_str falls back to str(exc) through the f-string, and that can raise too. There is now a one-line comment saying so.

[bluetech]

Seems to me that the f'{type(obj).__name__}("{obj}")' part is a bit too much. A __repr__ raising is already and edge case, and we then add a fallback to __str__ and then another edge-case of it failing.

Seems to me we can just try the repr and if it fails go directly to raised in repr message.

[bluetech]

@RonnyPfannschmidt did you see my two remaining comments? I can send a PR for it if you'd like.

[RonnyPfannschmidt]

Yes resolved

[bluetech]

Oops, didn't notice. Thanks