pytest_report_teststatus documentation is contradictory

[samuelcolvin]

See here:

The example return value is "rerun", "R", ("RERUN", {"yellow": True}), while the return type is documented as

Tuple[str, str, Union[str, Mapping[str, bool]]]

which don't match.

I'm assuming the return type should be

Tuple[str, str, Union[str, Tuple[str, Mapping[str, bool]]]]

Or something?

Also some clearer documentation on how the third element of the tuple is sued would be great.

[nicoddemus]

Indeed the docs are wrong, and the annotation in the code is correct:

pytest/src/_pytest/terminal.py

Lines 528 to 530 in 31d0b51

	res: Tuple[
	str, str, Union[str, Tuple[str, Mapping[str, bool]]]
	] = self.config.hook.pytest_report_teststatus(report=rep, config=self.config)

The return value can be, for example:

("rerun", "R", "RERUN")

Or:

("rerun", "R", ("RERUN", {"yellow": True}))

This signature is like that for historical reasons unfortunately, nowadays we would use probably a dataclass.

[nicoddemus]

The possible values that can be used in the mapping are not really documented I think, they are defined here:

pytest/src/_pytest/_io/terminalwriter.py

Lines 42 to 63 in 31d0b51

	_esctable = dict(
	black=30,
	red=31,
	green=32,
	yellow=33,
	blue=34,
	purple=35,
	cyan=36,
	white=37,
	Black=40,
	Red=41,
	Green=42,
	Yellow=43,
	Blue=44,
	Purple=45,
	Cyan=46,
	White=47,
	bold=1,
	light=2,
	blink=5,
	invert=7,
	)

[samuelcolvin]

makes sense, thanks for the details.

[The-Compiler]

This signature is like that for historical reasons unfortunately, nowadays we would use probably a dataclass.

I feel like we should do just that, and figure out a way to make it backwards compatible.

If pytest itself would be the only place invoking the hook, it'd just be a matter of an isinstance - if we want to keep compatibility with some 15-20 projects invoking the hook themselves, returning an object with a __getitem__ and __iter__ implemented (perhaps emitting a DeprecationWarning) would probably work smoothly.

[nicoddemus]

Perhaps a named tuple would work too?

[RonnyPfannschmidt]

I wonder if we could try to mirror rich styled spans and supply easy conversation

This is one of the rarely used apis that tie us into the legacy terminalwriter apis