raises.py 59 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517
  1. from __future__ import annotations
  2. from abc import ABC
  3. from abc import abstractmethod
  4. import re
  5. from re import Pattern
  6. import sys
  7. from textwrap import indent
  8. from typing import Any
  9. from typing import cast
  10. from typing import final
  11. from typing import Generic
  12. from typing import get_args
  13. from typing import get_origin
  14. from typing import Literal
  15. from typing import overload
  16. from typing import TYPE_CHECKING
  17. import warnings
  18. from _pytest._code import ExceptionInfo
  19. from _pytest._code.code import stringify_exception
  20. from _pytest.outcomes import fail
  21. from _pytest.warning_types import PytestWarning
  22. if TYPE_CHECKING:
  23. from collections.abc import Callable
  24. from collections.abc import Sequence
  25. # for some reason Sphinx does not play well with 'from types import TracebackType'
  26. import types
  27. from typing import TypeGuard
  28. from typing_extensions import ParamSpec
  29. from typing_extensions import TypeVar
  30. P = ParamSpec("P")
  31. # this conditional definition is because we want to allow a TypeVar default
  32. BaseExcT_co_default = TypeVar(
  33. "BaseExcT_co_default",
  34. bound=BaseException,
  35. default=BaseException,
  36. covariant=True,
  37. )
  38. # Use short name because it shows up in docs.
  39. E = TypeVar("E", bound=BaseException, default=BaseException)
  40. else:
  41. from typing import TypeVar
  42. BaseExcT_co_default = TypeVar(
  43. "BaseExcT_co_default", bound=BaseException, covariant=True
  44. )
  45. # RaisesGroup doesn't work with a default.
  46. BaseExcT_co = TypeVar("BaseExcT_co", bound=BaseException, covariant=True)
  47. BaseExcT_1 = TypeVar("BaseExcT_1", bound=BaseException)
  48. BaseExcT_2 = TypeVar("BaseExcT_2", bound=BaseException)
  49. ExcT_1 = TypeVar("ExcT_1", bound=Exception)
  50. ExcT_2 = TypeVar("ExcT_2", bound=Exception)
  51. if sys.version_info < (3, 11):
  52. from exceptiongroup import BaseExceptionGroup
  53. from exceptiongroup import ExceptionGroup
  54. # String patterns default to including the unicode flag.
  55. _REGEX_NO_FLAGS = re.compile(r"").flags
  56. # pytest.raises helper
  57. @overload
  58. def raises(
  59. expected_exception: type[E] | tuple[type[E], ...],
  60. *,
  61. match: str | re.Pattern[str] | None = ...,
  62. check: Callable[[E], bool] = ...,
  63. ) -> RaisesExc[E]: ...
  64. @overload
  65. def raises(
  66. *,
  67. match: str | re.Pattern[str],
  68. # If exception_type is not provided, check() must do any typechecks itself.
  69. check: Callable[[BaseException], bool] = ...,
  70. ) -> RaisesExc[BaseException]: ...
  71. @overload
  72. def raises(*, check: Callable[[BaseException], bool]) -> RaisesExc[BaseException]: ...
  73. @overload
  74. def raises(
  75. expected_exception: type[E] | tuple[type[E], ...],
  76. func: Callable[..., Any],
  77. *args: Any,
  78. **kwargs: Any,
  79. ) -> ExceptionInfo[E]: ...
  80. def raises(
  81. expected_exception: type[E] | tuple[type[E], ...] | None = None,
  82. *args: Any,
  83. **kwargs: Any,
  84. ) -> RaisesExc[BaseException] | ExceptionInfo[E]:
  85. r"""Assert that a code block/function call raises an exception type, or one of its subclasses.
  86. :param expected_exception:
  87. The expected exception type, or a tuple if one of multiple possible
  88. exception types are expected. Note that subclasses of the passed exceptions
  89. will also match.
  90. This is not a required parameter, you may opt to only use ``match`` and/or
  91. ``check`` for verifying the raised exception.
  92. :kwparam str | re.Pattern[str] | None match:
  93. If specified, a string containing a regular expression,
  94. or a regular expression object, that is tested against the string
  95. representation of the exception and its :pep:`678` `__notes__`
  96. using :func:`re.search`.
  97. To match a literal string that may contain :ref:`special characters
  98. <re-syntax>`, the pattern can first be escaped with :func:`re.escape`.
  99. (This is only used when ``pytest.raises`` is used as a context manager,
  100. and passed through to the function otherwise.
  101. When using ``pytest.raises`` as a function, you can use:
  102. ``pytest.raises(Exc, func, match="passed on").match("my pattern")``.)
  103. :kwparam Callable[[BaseException], bool] check:
  104. .. versionadded:: 8.4
  105. If specified, a callable that will be called with the exception as a parameter
  106. after checking the type and the match regex if specified.
  107. If it returns ``True`` it will be considered a match, if not it will
  108. be considered a failed match.
  109. Use ``pytest.raises`` as a context manager, which will capture the exception of the given
  110. type, or any of its subclasses::
  111. >>> import pytest
  112. >>> with pytest.raises(ZeroDivisionError):
  113. ... 1/0
  114. If the code block does not raise the expected exception (:class:`ZeroDivisionError` in the example
  115. above), or no exception at all, the check will fail instead.
  116. You can also use the keyword argument ``match`` to assert that the
  117. exception matches a text or regex::
  118. >>> with pytest.raises(ValueError, match='must be 0 or None'):
  119. ... raise ValueError("value must be 0 or None")
  120. >>> with pytest.raises(ValueError, match=r'must be \d+$'):
  121. ... raise ValueError("value must be 42")
  122. The ``match`` argument searches the formatted exception string, which includes any
  123. `PEP-678 <https://peps.python.org/pep-0678/>`__ ``__notes__``:
  124. >>> with pytest.raises(ValueError, match=r"had a note added"): # doctest: +SKIP
  125. ... e = ValueError("value must be 42")
  126. ... e.add_note("had a note added")
  127. ... raise e
  128. The ``check`` argument, if provided, must return True when passed the raised exception
  129. for the match to be successful, otherwise an :exc:`AssertionError` is raised.
  130. >>> import errno
  131. >>> with pytest.raises(OSError, check=lambda e: e.errno == errno.EACCES):
  132. ... raise OSError(errno.EACCES, "no permission to view")
  133. The context manager produces an :class:`ExceptionInfo` object which can be used to inspect the
  134. details of the captured exception::
  135. >>> with pytest.raises(ValueError) as exc_info:
  136. ... raise ValueError("value must be 42")
  137. >>> assert exc_info.type is ValueError
  138. >>> assert exc_info.value.args[0] == "value must be 42"
  139. .. warning::
  140. Given that ``pytest.raises`` matches subclasses, be wary of using it to match :class:`Exception` like this::
  141. # Careful, this will catch ANY exception raised.
  142. with pytest.raises(Exception):
  143. some_function()
  144. Because :class:`Exception` is the base class of almost all exceptions, it is easy for this to hide
  145. real bugs, where the user wrote this expecting a specific exception, but some other exception is being
  146. raised due to a bug introduced during a refactoring.
  147. Avoid using ``pytest.raises`` to catch :class:`Exception` unless certain that you really want to catch
  148. **any** exception raised.
  149. .. note::
  150. When using ``pytest.raises`` as a context manager, it's worthwhile to
  151. note that normal context manager rules apply and that the exception
  152. raised *must* be the final line in the scope of the context manager.
  153. Lines of code after that, within the scope of the context manager will
  154. not be executed. For example::
  155. >>> value = 15
  156. >>> with pytest.raises(ValueError) as exc_info:
  157. ... if value > 10:
  158. ... raise ValueError("value must be <= 10")
  159. ... assert exc_info.type is ValueError # This will not execute.
  160. Instead, the following approach must be taken (note the difference in
  161. scope)::
  162. >>> with pytest.raises(ValueError) as exc_info:
  163. ... if value > 10:
  164. ... raise ValueError("value must be <= 10")
  165. ...
  166. >>> assert exc_info.type is ValueError
  167. **Expecting exception groups**
  168. When expecting exceptions wrapped in :exc:`BaseExceptionGroup` or
  169. :exc:`ExceptionGroup`, you should instead use :class:`pytest.RaisesGroup`.
  170. **Using with** ``pytest.mark.parametrize``
  171. When using :ref:`pytest.mark.parametrize ref`
  172. it is possible to parametrize tests such that
  173. some runs raise an exception and others do not.
  174. See :ref:`parametrizing_conditional_raising` for an example.
  175. .. seealso::
  176. :ref:`assertraises` for more examples and detailed discussion.
  177. **Legacy form**
  178. It is possible to specify a callable by passing a to-be-called lambda::
  179. >>> raises(ZeroDivisionError, lambda: 1/0)
  180. <ExceptionInfo ...>
  181. or you can specify an arbitrary callable with arguments::
  182. >>> def f(x): return 1/x
  183. ...
  184. >>> raises(ZeroDivisionError, f, 0)
  185. <ExceptionInfo ...>
  186. >>> raises(ZeroDivisionError, f, x=0)
  187. <ExceptionInfo ...>
  188. The form above is fully supported but discouraged for new code because the
  189. context manager form is regarded as more readable and less error-prone.
  190. .. note::
  191. Similar to caught exception objects in Python, explicitly clearing
  192. local references to returned ``ExceptionInfo`` objects can
  193. help the Python interpreter speed up its garbage collection.
  194. Clearing those references breaks a reference cycle
  195. (``ExceptionInfo`` --> caught exception --> frame stack raising
  196. the exception --> current frame stack --> local variables -->
  197. ``ExceptionInfo``) which makes Python keep all objects referenced
  198. from that cycle (including all local variables in the current
  199. frame) alive until the next cyclic garbage collection run.
  200. More detailed information can be found in the official Python
  201. documentation for :ref:`the try statement <python:try>`.
  202. """
  203. __tracebackhide__ = True
  204. if not args:
  205. if set(kwargs) - {"match", "check", "expected_exception"}:
  206. msg = "Unexpected keyword arguments passed to pytest.raises: "
  207. msg += ", ".join(sorted(kwargs))
  208. msg += "\nUse context-manager form instead?"
  209. raise TypeError(msg)
  210. if expected_exception is None:
  211. return RaisesExc(**kwargs)
  212. return RaisesExc(expected_exception, **kwargs)
  213. if not expected_exception:
  214. raise ValueError(
  215. f"Expected an exception type or a tuple of exception types, but got `{expected_exception!r}`. "
  216. f"Raising exceptions is already understood as failing the test, so you don't need "
  217. f"any special code to say 'this should never raise an exception'."
  218. )
  219. func = args[0]
  220. if not callable(func):
  221. raise TypeError(f"{func!r} object (type: {type(func)}) must be callable")
  222. with RaisesExc(expected_exception) as excinfo:
  223. func(*args[1:], **kwargs)
  224. try:
  225. return excinfo
  226. finally:
  227. del excinfo
  228. # note: RaisesExc/RaisesGroup uses fail() internally, so this alias
  229. # indicates (to [internal] plugins?) that `pytest.raises` will
  230. # raise `_pytest.outcomes.Failed`, where
  231. # `outcomes.Failed is outcomes.fail.Exception is raises.Exception`
  232. # note: this is *not* the same as `_pytest.main.Failed`
  233. # note: mypy does not recognize this attribute, and it's not possible
  234. # to use a protocol/decorator like the others in outcomes due to
  235. # https://github.com/python/mypy/issues/18715
  236. raises.Exception = fail.Exception # type: ignore[attr-defined]
  237. def _match_pattern(match: Pattern[str]) -> str | Pattern[str]:
  238. """Helper function to remove redundant `re.compile` calls when printing regex"""
  239. return match.pattern if match.flags == _REGEX_NO_FLAGS else match
  240. def repr_callable(fun: Callable[[BaseExcT_1], bool]) -> str:
  241. """Get the repr of a ``check`` parameter.
  242. Split out so it can be monkeypatched (e.g. by hypothesis)
  243. """
  244. return repr(fun)
  245. def backquote(s: str) -> str:
  246. return "`" + s + "`"
  247. def _exception_type_name(
  248. e: type[BaseException] | tuple[type[BaseException], ...],
  249. ) -> str:
  250. if isinstance(e, type):
  251. return e.__name__
  252. if len(e) == 1:
  253. return e[0].__name__
  254. return "(" + ", ".join(ee.__name__ for ee in e) + ")"
  255. def _check_raw_type(
  256. expected_type: type[BaseException] | tuple[type[BaseException], ...] | None,
  257. exception: BaseException,
  258. ) -> str | None:
  259. if expected_type is None or expected_type == ():
  260. return None
  261. if not isinstance(
  262. exception,
  263. expected_type,
  264. ):
  265. actual_type_str = backquote(_exception_type_name(type(exception)) + "()")
  266. expected_type_str = backquote(_exception_type_name(expected_type))
  267. if (
  268. isinstance(exception, BaseExceptionGroup)
  269. and isinstance(expected_type, type)
  270. and not issubclass(expected_type, BaseExceptionGroup)
  271. ):
  272. return f"Unexpected nested {actual_type_str}, expected {expected_type_str}"
  273. return f"{actual_type_str} is not an instance of {expected_type_str}"
  274. return None
  275. def is_fully_escaped(s: str) -> bool:
  276. # we know we won't compile with re.VERBOSE, so whitespace doesn't need to be escaped
  277. metacharacters = "{}()+.*?^$[]"
  278. return not any(
  279. c in metacharacters and (i == 0 or s[i - 1] != "\\") for (i, c) in enumerate(s)
  280. )
  281. def unescape(s: str) -> str:
  282. return re.sub(r"\\([{}()+-.*?^$\[\]\s\\])", r"\1", s)
  283. # These classes conceptually differ from ExceptionInfo in that ExceptionInfo is tied, and
  284. # constructed from, a particular exception - whereas these are constructed with expected
  285. # exceptions, and later allow matching towards particular exceptions.
  286. # But there's overlap in `ExceptionInfo.match` and `AbstractRaises._check_match`, as with
  287. # `AbstractRaises.matches` and `ExceptionInfo.errisinstance`+`ExceptionInfo.group_contains`.
  288. # The interaction between these classes should perhaps be improved.
  289. class AbstractRaises(ABC, Generic[BaseExcT_co]):
  290. """ABC with common functionality shared between RaisesExc and RaisesGroup"""
  291. def __init__(
  292. self,
  293. *,
  294. match: str | Pattern[str] | None,
  295. check: Callable[[BaseExcT_co], bool] | None,
  296. ) -> None:
  297. if isinstance(match, str):
  298. # juggle error in order to avoid context to fail (necessary?)
  299. re_error = None
  300. try:
  301. self.match: Pattern[str] | None = re.compile(match)
  302. except re.error as e:
  303. re_error = e
  304. if re_error is not None:
  305. fail(f"Invalid regex pattern provided to 'match': {re_error}")
  306. if match == "":
  307. warnings.warn(
  308. PytestWarning(
  309. "matching against an empty string will *always* pass. If you want "
  310. "to check for an empty message you need to pass '^$'. If you don't "
  311. "want to match you should pass `None` or leave out the parameter."
  312. ),
  313. stacklevel=2,
  314. )
  315. else:
  316. self.match = match
  317. # check if this is a fully escaped regex and has ^$ to match fully
  318. # in which case we can do a proper diff on error
  319. self.rawmatch: str | None = None
  320. if isinstance(match, str) or (
  321. isinstance(match, Pattern) and match.flags == _REGEX_NO_FLAGS
  322. ):
  323. if isinstance(match, Pattern):
  324. match = match.pattern
  325. if (
  326. match
  327. and match[0] == "^"
  328. and match[-1] == "$"
  329. and is_fully_escaped(match[1:-1])
  330. ):
  331. self.rawmatch = unescape(match[1:-1])
  332. self.check = check
  333. self._fail_reason: str | None = None
  334. # used to suppress repeated printing of `repr(self.check)`
  335. self._nested: bool = False
  336. # set in self._parse_exc
  337. self.is_baseexception = False
  338. def _parse_exc(
  339. self, exc: type[BaseExcT_1] | types.GenericAlias, expected: str
  340. ) -> type[BaseExcT_1]:
  341. if isinstance(exc, type) and issubclass(exc, BaseException):
  342. if not issubclass(exc, Exception):
  343. self.is_baseexception = True
  344. return exc
  345. # because RaisesGroup does not support variable number of exceptions there's
  346. # still a use for RaisesExc(ExceptionGroup[Exception]).
  347. origin_exc: type[BaseException] | None = get_origin(exc)
  348. if origin_exc and issubclass(origin_exc, BaseExceptionGroup):
  349. exc_type = get_args(exc)[0]
  350. if (
  351. issubclass(origin_exc, ExceptionGroup) and exc_type in (Exception, Any)
  352. ) or (
  353. issubclass(origin_exc, BaseExceptionGroup)
  354. and exc_type in (BaseException, Any)
  355. ):
  356. if not issubclass(origin_exc, ExceptionGroup):
  357. self.is_baseexception = True
  358. return cast(type[BaseExcT_1], origin_exc)
  359. else:
  360. raise ValueError(
  361. f"Only `ExceptionGroup[Exception]` or `BaseExceptionGroup[BaseException]` "
  362. f"are accepted as generic types but got `{exc}`. "
  363. f"As `raises` will catch all instances of the specified group regardless of the "
  364. f"generic argument specific nested exceptions has to be checked "
  365. f"with `RaisesGroup`."
  366. )
  367. # unclear if the Type/ValueError distinction is even helpful here
  368. msg = f"Expected {expected}, but got "
  369. if isinstance(exc, type): # type: ignore[unreachable]
  370. raise ValueError(msg + f"{exc.__name__!r}")
  371. if isinstance(exc, BaseException): # type: ignore[unreachable]
  372. raise TypeError(msg + f"an exception instance: {type(exc).__name__}")
  373. raise TypeError(msg + repr(type(exc).__name__))
  374. @property
  375. def fail_reason(self) -> str | None:
  376. """Set after a call to :meth:`matches` to give a human-readable reason for why the match failed.
  377. When used as a context manager the string will be printed as the reason for the
  378. test failing."""
  379. return self._fail_reason
  380. def _check_check(
  381. self: AbstractRaises[BaseExcT_1],
  382. exception: BaseExcT_1,
  383. ) -> bool:
  384. if self.check is None:
  385. return True
  386. if self.check(exception):
  387. return True
  388. check_repr = "" if self._nested else " " + repr_callable(self.check)
  389. self._fail_reason = f"check{check_repr} did not return True"
  390. return False
  391. # TODO: harmonize with ExceptionInfo.match
  392. def _check_match(self, e: BaseException) -> bool:
  393. if self.match is None or re.search(
  394. self.match,
  395. stringified_exception := stringify_exception(
  396. e, include_subexception_msg=False
  397. ),
  398. ):
  399. return True
  400. # if we're matching a group, make sure we're explicit to reduce confusion
  401. # if they're trying to match an exception contained within the group
  402. maybe_specify_type = (
  403. f" the `{_exception_type_name(type(e))}()`"
  404. if isinstance(e, BaseExceptionGroup)
  405. else ""
  406. )
  407. if isinstance(self.rawmatch, str):
  408. # TODO: it instructs to use `-v` to print leading text, but that doesn't work
  409. # I also don't know if this is the proper entry point, or tool to use at all
  410. from _pytest.assertion.util import _diff_text
  411. from _pytest.assertion.util import dummy_highlighter
  412. diff = _diff_text(self.rawmatch, stringified_exception, dummy_highlighter)
  413. self._fail_reason = ("\n" if diff[0][0] == "-" else "") + "\n".join(diff)
  414. return False
  415. self._fail_reason = (
  416. f"Regex pattern did not match{maybe_specify_type}.\n"
  417. f" Expected regex: {_match_pattern(self.match)!r}\n"
  418. f" Actual message: {stringified_exception!r}"
  419. )
  420. if _match_pattern(self.match) == stringified_exception:
  421. self._fail_reason += "\n Did you mean to `re.escape()` the regex?"
  422. return False
  423. @abstractmethod
  424. def matches(
  425. self: AbstractRaises[BaseExcT_1], exception: BaseException
  426. ) -> TypeGuard[BaseExcT_1]:
  427. """Check if an exception matches the requirements of this AbstractRaises.
  428. If it fails, :meth:`AbstractRaises.fail_reason` should be set.
  429. """
  430. @final
  431. class RaisesExc(AbstractRaises[BaseExcT_co_default]):
  432. """
  433. .. versionadded:: 8.4
  434. This is the class constructed when calling :func:`pytest.raises`, but may be used
  435. directly as a helper class with :class:`RaisesGroup` when you want to specify
  436. requirements on sub-exceptions.
  437. You don't need this if you only want to specify the type, since :class:`RaisesGroup`
  438. accepts ``type[BaseException]``.
  439. :param type[BaseException] | tuple[type[BaseException]] | None expected_exception:
  440. The expected type, or one of several possible types.
  441. May be ``None`` in order to only make use of ``match`` and/or ``check``
  442. The type is checked with :func:`isinstance`, and does not need to be an exact match.
  443. If that is wanted you can use the ``check`` parameter.
  444. :kwparam str | Pattern[str] match:
  445. A regex to match.
  446. :kwparam Callable[[BaseException], bool] check:
  447. If specified, a callable that will be called with the exception as a parameter
  448. after checking the type and the match regex if specified.
  449. If it returns ``True`` it will be considered a match, if not it will
  450. be considered a failed match.
  451. :meth:`RaisesExc.matches` can also be used standalone to check individual exceptions.
  452. Examples::
  453. with RaisesGroup(RaisesExc(ValueError, match="string"))
  454. ...
  455. with RaisesGroup(RaisesExc(check=lambda x: x.args == (3, "hello"))):
  456. ...
  457. with RaisesGroup(RaisesExc(check=lambda x: type(x) is ValueError)):
  458. ...
  459. """
  460. # Trio bundled hypothesis monkeypatching, we will probably instead assume that
  461. # hypothesis will handle that in their pytest plugin by the time this is released.
  462. # Alternatively we could add a version of get_pretty_function_description ourselves
  463. # https://github.com/HypothesisWorks/hypothesis/blob/8ced2f59f5c7bea3344e35d2d53e1f8f8eb9fcd8/hypothesis-python/src/hypothesis/internal/reflection.py#L439
  464. # At least one of the three parameters must be passed.
  465. @overload
  466. def __init__(
  467. self,
  468. expected_exception: (
  469. type[BaseExcT_co_default] | tuple[type[BaseExcT_co_default], ...]
  470. ),
  471. /,
  472. *,
  473. match: str | Pattern[str] | None = ...,
  474. check: Callable[[BaseExcT_co_default], bool] | None = ...,
  475. ) -> None: ...
  476. @overload
  477. def __init__(
  478. self: RaisesExc[BaseException], # Give E a value.
  479. /,
  480. *,
  481. match: str | Pattern[str] | None,
  482. # If exception_type is not provided, check() must do any typechecks itself.
  483. check: Callable[[BaseException], bool] | None = ...,
  484. ) -> None: ...
  485. @overload
  486. def __init__(self, /, *, check: Callable[[BaseException], bool]) -> None: ...
  487. def __init__(
  488. self,
  489. expected_exception: (
  490. type[BaseExcT_co_default] | tuple[type[BaseExcT_co_default], ...] | None
  491. ) = None,
  492. /,
  493. *,
  494. match: str | Pattern[str] | None = None,
  495. check: Callable[[BaseExcT_co_default], bool] | None = None,
  496. ):
  497. super().__init__(match=match, check=check)
  498. if isinstance(expected_exception, tuple):
  499. expected_exceptions = expected_exception
  500. elif expected_exception is None:
  501. expected_exceptions = ()
  502. else:
  503. expected_exceptions = (expected_exception,)
  504. if (expected_exceptions == ()) and match is None and check is None:
  505. raise ValueError("You must specify at least one parameter to match on.")
  506. self.expected_exceptions = tuple(
  507. self._parse_exc(e, expected="a BaseException type")
  508. for e in expected_exceptions
  509. )
  510. self._just_propagate = False
  511. def matches(
  512. self,
  513. exception: BaseException | None,
  514. ) -> TypeGuard[BaseExcT_co_default]:
  515. """Check if an exception matches the requirements of this :class:`RaisesExc`.
  516. If it fails, :attr:`RaisesExc.fail_reason` will be set.
  517. Examples::
  518. assert RaisesExc(ValueError).matches(my_exception):
  519. # is equivalent to
  520. assert isinstance(my_exception, ValueError)
  521. # this can be useful when checking e.g. the ``__cause__`` of an exception.
  522. with pytest.raises(ValueError) as excinfo:
  523. ...
  524. assert RaisesExc(SyntaxError, match="foo").matches(excinfo.value.__cause__)
  525. # above line is equivalent to
  526. assert isinstance(excinfo.value.__cause__, SyntaxError)
  527. assert re.search("foo", str(excinfo.value.__cause__)
  528. """
  529. self._just_propagate = False
  530. if exception is None:
  531. self._fail_reason = "exception is None"
  532. return False
  533. if not self._check_type(exception):
  534. self._just_propagate = True
  535. return False
  536. if not self._check_match(exception):
  537. return False
  538. return self._check_check(exception)
  539. def __repr__(self) -> str:
  540. parameters = []
  541. if self.expected_exceptions:
  542. parameters.append(_exception_type_name(self.expected_exceptions))
  543. if self.match is not None:
  544. # If no flags were specified, discard the redundant re.compile() here.
  545. parameters.append(
  546. f"match={_match_pattern(self.match)!r}",
  547. )
  548. if self.check is not None:
  549. parameters.append(f"check={repr_callable(self.check)}")
  550. return f"RaisesExc({', '.join(parameters)})"
  551. def _check_type(self, exception: BaseException) -> TypeGuard[BaseExcT_co_default]:
  552. self._fail_reason = _check_raw_type(self.expected_exceptions, exception)
  553. return self._fail_reason is None
  554. def __enter__(self) -> ExceptionInfo[BaseExcT_co_default]:
  555. self.excinfo: ExceptionInfo[BaseExcT_co_default] = ExceptionInfo.for_later()
  556. return self.excinfo
  557. # TODO: move common code into superclass
  558. def __exit__(
  559. self,
  560. exc_type: type[BaseException] | None,
  561. exc_val: BaseException | None,
  562. exc_tb: types.TracebackType | None,
  563. ) -> bool:
  564. __tracebackhide__ = True
  565. if exc_type is None:
  566. if not self.expected_exceptions:
  567. fail("DID NOT RAISE any exception")
  568. if len(self.expected_exceptions) > 1:
  569. fail(f"DID NOT RAISE any of {self.expected_exceptions!r}")
  570. fail(f"DID NOT RAISE {self.expected_exceptions[0]!r}")
  571. assert self.excinfo is not None, (
  572. "Internal error - should have been constructed in __enter__"
  573. )
  574. if not self.matches(exc_val):
  575. if self._just_propagate:
  576. return False
  577. raise AssertionError(self._fail_reason)
  578. # Cast to narrow the exception type now that it's verified....
  579. # even though the TypeGuard in self.matches should be narrowing
  580. exc_info = cast(
  581. "tuple[type[BaseExcT_co_default], BaseExcT_co_default, types.TracebackType]",
  582. (exc_type, exc_val, exc_tb),
  583. )
  584. self.excinfo.fill_unfilled(exc_info)
  585. return True
  586. @final
  587. class RaisesGroup(AbstractRaises[BaseExceptionGroup[BaseExcT_co]]):
  588. """
  589. .. versionadded:: 8.4
  590. Contextmanager for checking for an expected :exc:`ExceptionGroup`.
  591. This works similar to :func:`pytest.raises`, but allows for specifying the structure of an :exc:`ExceptionGroup`.
  592. :meth:`ExceptionInfo.group_contains` also tries to handle exception groups,
  593. but it is very bad at checking that you *didn't* get unexpected exceptions.
  594. The catching behaviour differs from :ref:`except* <except_star>`, being much
  595. stricter about the structure by default.
  596. By using ``allow_unwrapped=True`` and ``flatten_subgroups=True`` you can match
  597. :ref:`except* <except_star>` fully when expecting a single exception.
  598. :param args:
  599. Any number of exception types, :class:`RaisesGroup` or :class:`RaisesExc`
  600. to specify the exceptions contained in this exception.
  601. All specified exceptions must be present in the raised group, *and no others*.
  602. If you expect a variable number of exceptions you need to use
  603. :func:`pytest.raises(ExceptionGroup) <pytest.raises>` and manually check
  604. the contained exceptions. Consider making use of :meth:`RaisesExc.matches`.
  605. It does not care about the order of the exceptions, so
  606. ``RaisesGroup(ValueError, TypeError)``
  607. is equivalent to
  608. ``RaisesGroup(TypeError, ValueError)``.
  609. :kwparam str | re.Pattern[str] | None match:
  610. If specified, a string containing a regular expression,
  611. or a regular expression object, that is tested against the string
  612. representation of the exception group and its :pep:`678` `__notes__`
  613. using :func:`re.search`.
  614. To match a literal string that may contain :ref:`special characters
  615. <re-syntax>`, the pattern can first be escaped with :func:`re.escape`.
  616. Note that " (5 subgroups)" will be stripped from the ``repr`` before matching.
  617. :kwparam Callable[[E], bool] check:
  618. If specified, a callable that will be called with the group as a parameter
  619. after successfully matching the expected exceptions. If it returns ``True``
  620. it will be considered a match, if not it will be considered a failed match.
  621. :kwparam bool allow_unwrapped:
  622. If expecting a single exception or :class:`RaisesExc` it will match even
  623. if the exception is not inside an exceptiongroup.
  624. Using this together with ``match``, ``check`` or expecting multiple exceptions
  625. will raise an error.
  626. :kwparam bool flatten_subgroups:
  627. "flatten" any groups inside the raised exception group, extracting all exceptions
  628. inside any nested groups, before matching. Without this it expects you to
  629. fully specify the nesting structure by passing :class:`RaisesGroup` as expected
  630. parameter.
  631. Examples::
  632. with RaisesGroup(ValueError):
  633. raise ExceptionGroup("", (ValueError(),))
  634. # match
  635. with RaisesGroup(
  636. ValueError,
  637. ValueError,
  638. RaisesExc(TypeError, match="^expected int$"),
  639. match="^my group$",
  640. ):
  641. raise ExceptionGroup(
  642. "my group",
  643. [
  644. ValueError(),
  645. TypeError("expected int"),
  646. ValueError(),
  647. ],
  648. )
  649. # check
  650. with RaisesGroup(
  651. KeyboardInterrupt,
  652. match="^hello$",
  653. check=lambda x: isinstance(x.__cause__, ValueError),
  654. ):
  655. raise BaseExceptionGroup("hello", [KeyboardInterrupt()]) from ValueError
  656. # nested groups
  657. with RaisesGroup(RaisesGroup(ValueError)):
  658. raise ExceptionGroup("", (ExceptionGroup("", (ValueError(),)),))
  659. # flatten_subgroups
  660. with RaisesGroup(ValueError, flatten_subgroups=True):
  661. raise ExceptionGroup("", (ExceptionGroup("", (ValueError(),)),))
  662. # allow_unwrapped
  663. with RaisesGroup(ValueError, allow_unwrapped=True):
  664. raise ValueError
  665. :meth:`RaisesGroup.matches` can also be used directly to check a standalone exception group.
  666. The matching algorithm is greedy, which means cases such as this may fail::
  667. with RaisesGroup(ValueError, RaisesExc(ValueError, match="hello")):
  668. raise ExceptionGroup("", (ValueError("hello"), ValueError("goodbye")))
  669. even though it generally does not care about the order of the exceptions in the group.
  670. To avoid the above you should specify the first :exc:`ValueError` with a :class:`RaisesExc` as well.
  671. .. note::
  672. When raised exceptions don't match the expected ones, you'll get a detailed error
  673. message explaining why. This includes ``repr(check)`` if set, which in Python can be
  674. overly verbose, showing memory locations etc etc.
  675. If installed and imported (in e.g. ``conftest.py``), the ``hypothesis`` library will
  676. monkeypatch this output to provide shorter & more readable repr's.
  677. """
  678. # allow_unwrapped=True requires: singular exception, exception not being
  679. # RaisesGroup instance, match is None, check is None
  680. @overload
  681. def __init__(
  682. self,
  683. expected_exception: type[BaseExcT_co] | RaisesExc[BaseExcT_co],
  684. /,
  685. *,
  686. allow_unwrapped: Literal[True],
  687. flatten_subgroups: bool = False,
  688. ) -> None: ...
  689. # flatten_subgroups = True also requires no nested RaisesGroup
  690. @overload
  691. def __init__(
  692. self,
  693. expected_exception: type[BaseExcT_co] | RaisesExc[BaseExcT_co],
  694. /,
  695. *other_exceptions: type[BaseExcT_co] | RaisesExc[BaseExcT_co],
  696. flatten_subgroups: Literal[True],
  697. match: str | Pattern[str] | None = None,
  698. check: Callable[[BaseExceptionGroup[BaseExcT_co]], bool] | None = None,
  699. ) -> None: ...
  700. # simplify the typevars if possible (the following 3 are equivalent but go simpler->complicated)
  701. # ... the first handles RaisesGroup[ValueError], the second RaisesGroup[ExceptionGroup[ValueError]],
  702. # the third RaisesGroup[ValueError | ExceptionGroup[ValueError]].
  703. # ... otherwise, we will get results like RaisesGroup[ValueError | ExceptionGroup[Never]] (I think)
  704. # (technically correct but misleading)
  705. @overload
  706. def __init__(
  707. self: RaisesGroup[ExcT_1],
  708. expected_exception: type[ExcT_1] | RaisesExc[ExcT_1],
  709. /,
  710. *other_exceptions: type[ExcT_1] | RaisesExc[ExcT_1],
  711. match: str | Pattern[str] | None = None,
  712. check: Callable[[ExceptionGroup[ExcT_1]], bool] | None = None,
  713. ) -> None: ...
  714. @overload
  715. def __init__(
  716. self: RaisesGroup[ExceptionGroup[ExcT_2]],
  717. expected_exception: RaisesGroup[ExcT_2],
  718. /,
  719. *other_exceptions: RaisesGroup[ExcT_2],
  720. match: str | Pattern[str] | None = None,
  721. check: Callable[[ExceptionGroup[ExceptionGroup[ExcT_2]]], bool] | None = None,
  722. ) -> None: ...
  723. @overload
  724. def __init__(
  725. self: RaisesGroup[ExcT_1 | ExceptionGroup[ExcT_2]],
  726. expected_exception: type[ExcT_1] | RaisesExc[ExcT_1] | RaisesGroup[ExcT_2],
  727. /,
  728. *other_exceptions: type[ExcT_1] | RaisesExc[ExcT_1] | RaisesGroup[ExcT_2],
  729. match: str | Pattern[str] | None = None,
  730. check: (
  731. Callable[[ExceptionGroup[ExcT_1 | ExceptionGroup[ExcT_2]]], bool] | None
  732. ) = None,
  733. ) -> None: ...
  734. # same as the above 3 but handling BaseException
  735. @overload
  736. def __init__(
  737. self: RaisesGroup[BaseExcT_1],
  738. expected_exception: type[BaseExcT_1] | RaisesExc[BaseExcT_1],
  739. /,
  740. *other_exceptions: type[BaseExcT_1] | RaisesExc[BaseExcT_1],
  741. match: str | Pattern[str] | None = None,
  742. check: Callable[[BaseExceptionGroup[BaseExcT_1]], bool] | None = None,
  743. ) -> None: ...
  744. @overload
  745. def __init__(
  746. self: RaisesGroup[BaseExceptionGroup[BaseExcT_2]],
  747. expected_exception: RaisesGroup[BaseExcT_2],
  748. /,
  749. *other_exceptions: RaisesGroup[BaseExcT_2],
  750. match: str | Pattern[str] | None = None,
  751. check: (
  752. Callable[[BaseExceptionGroup[BaseExceptionGroup[BaseExcT_2]]], bool] | None
  753. ) = None,
  754. ) -> None: ...
  755. @overload
  756. def __init__(
  757. self: RaisesGroup[BaseExcT_1 | BaseExceptionGroup[BaseExcT_2]],
  758. expected_exception: type[BaseExcT_1]
  759. | RaisesExc[BaseExcT_1]
  760. | RaisesGroup[BaseExcT_2],
  761. /,
  762. *other_exceptions: type[BaseExcT_1]
  763. | RaisesExc[BaseExcT_1]
  764. | RaisesGroup[BaseExcT_2],
  765. match: str | Pattern[str] | None = None,
  766. check: (
  767. Callable[
  768. [BaseExceptionGroup[BaseExcT_1 | BaseExceptionGroup[BaseExcT_2]]],
  769. bool,
  770. ]
  771. | None
  772. ) = None,
  773. ) -> None: ...
  774. def __init__(
  775. self: RaisesGroup[ExcT_1 | BaseExcT_1 | BaseExceptionGroup[BaseExcT_2]],
  776. expected_exception: type[BaseExcT_1]
  777. | RaisesExc[BaseExcT_1]
  778. | RaisesGroup[BaseExcT_2],
  779. /,
  780. *other_exceptions: type[BaseExcT_1]
  781. | RaisesExc[BaseExcT_1]
  782. | RaisesGroup[BaseExcT_2],
  783. allow_unwrapped: bool = False,
  784. flatten_subgroups: bool = False,
  785. match: str | Pattern[str] | None = None,
  786. check: (
  787. Callable[[BaseExceptionGroup[BaseExcT_1]], bool]
  788. | Callable[[ExceptionGroup[ExcT_1]], bool]
  789. | None
  790. ) = None,
  791. ):
  792. # The type hint on the `self` and `check` parameters uses different formats
  793. # that are *very* hard to reconcile while adhering to the overloads, so we cast
  794. # it to avoid an error when passing it to super().__init__
  795. check = cast(
  796. "Callable[[BaseExceptionGroup[ExcT_1|BaseExcT_1|BaseExceptionGroup[BaseExcT_2]]], bool]",
  797. check,
  798. )
  799. super().__init__(match=match, check=check)
  800. self.allow_unwrapped = allow_unwrapped
  801. self.flatten_subgroups: bool = flatten_subgroups
  802. self.is_baseexception = False
  803. if allow_unwrapped and other_exceptions:
  804. raise ValueError(
  805. "You cannot specify multiple exceptions with `allow_unwrapped=True.`"
  806. " If you want to match one of multiple possible exceptions you should"
  807. " use a `RaisesExc`."
  808. " E.g. `RaisesExc(check=lambda e: isinstance(e, (...)))`",
  809. )
  810. if allow_unwrapped and isinstance(expected_exception, RaisesGroup):
  811. raise ValueError(
  812. "`allow_unwrapped=True` has no effect when expecting a `RaisesGroup`."
  813. " You might want it in the expected `RaisesGroup`, or"
  814. " `flatten_subgroups=True` if you don't care about the structure.",
  815. )
  816. if allow_unwrapped and (match is not None or check is not None):
  817. raise ValueError(
  818. "`allow_unwrapped=True` bypasses the `match` and `check` parameters"
  819. " if the exception is unwrapped. If you intended to match/check the"
  820. " exception you should use a `RaisesExc` object. If you want to match/check"
  821. " the exceptiongroup when the exception *is* wrapped you need to"
  822. " do e.g. `if isinstance(exc.value, ExceptionGroup):"
  823. " assert RaisesGroup(...).matches(exc.value)` afterwards.",
  824. )
  825. self.expected_exceptions: tuple[
  826. type[BaseExcT_co] | RaisesExc[BaseExcT_co] | RaisesGroup[BaseException], ...
  827. ] = tuple(
  828. self._parse_excgroup(e, "a BaseException type, RaisesExc, or RaisesGroup")
  829. for e in (
  830. expected_exception,
  831. *other_exceptions,
  832. )
  833. )
  834. def _parse_excgroup(
  835. self,
  836. exc: (
  837. type[BaseExcT_co]
  838. | types.GenericAlias
  839. | RaisesExc[BaseExcT_1]
  840. | RaisesGroup[BaseExcT_2]
  841. ),
  842. expected: str,
  843. ) -> type[BaseExcT_co] | RaisesExc[BaseExcT_1] | RaisesGroup[BaseExcT_2]:
  844. # verify exception type and set `self.is_baseexception`
  845. if isinstance(exc, RaisesGroup):
  846. if self.flatten_subgroups:
  847. raise ValueError(
  848. "You cannot specify a nested structure inside a RaisesGroup with"
  849. " `flatten_subgroups=True`. The parameter will flatten subgroups"
  850. " in the raised exceptiongroup before matching, which would never"
  851. " match a nested structure.",
  852. )
  853. self.is_baseexception |= exc.is_baseexception
  854. exc._nested = True
  855. return exc
  856. elif isinstance(exc, RaisesExc):
  857. self.is_baseexception |= exc.is_baseexception
  858. exc._nested = True
  859. return exc
  860. elif isinstance(exc, tuple):
  861. raise TypeError(
  862. f"Expected {expected}, but got {type(exc).__name__!r}.\n"
  863. "RaisesGroup does not support tuples of exception types when expecting one of "
  864. "several possible exception types like RaisesExc.\n"
  865. "If you meant to expect a group with multiple exceptions, list them as separate arguments."
  866. )
  867. else:
  868. return super()._parse_exc(exc, expected)
  869. @overload
  870. def __enter__(
  871. self: RaisesGroup[ExcT_1],
  872. ) -> ExceptionInfo[ExceptionGroup[ExcT_1]]: ...
  873. @overload
  874. def __enter__(
  875. self: RaisesGroup[BaseExcT_1],
  876. ) -> ExceptionInfo[BaseExceptionGroup[BaseExcT_1]]: ...
  877. def __enter__(self) -> ExceptionInfo[BaseExceptionGroup[BaseException]]:
  878. self.excinfo: ExceptionInfo[BaseExceptionGroup[BaseExcT_co]] = (
  879. ExceptionInfo.for_later()
  880. )
  881. return self.excinfo
  882. def __repr__(self) -> str:
  883. reqs = [
  884. e.__name__ if isinstance(e, type) else repr(e)
  885. for e in self.expected_exceptions
  886. ]
  887. if self.allow_unwrapped:
  888. reqs.append(f"allow_unwrapped={self.allow_unwrapped}")
  889. if self.flatten_subgroups:
  890. reqs.append(f"flatten_subgroups={self.flatten_subgroups}")
  891. if self.match is not None:
  892. # If no flags were specified, discard the redundant re.compile() here.
  893. reqs.append(f"match={_match_pattern(self.match)!r}")
  894. if self.check is not None:
  895. reqs.append(f"check={repr_callable(self.check)}")
  896. return f"RaisesGroup({', '.join(reqs)})"
  897. def _unroll_exceptions(
  898. self,
  899. exceptions: Sequence[BaseException],
  900. ) -> Sequence[BaseException]:
  901. """Used if `flatten_subgroups=True`."""
  902. res: list[BaseException] = []
  903. for exc in exceptions:
  904. if isinstance(exc, BaseExceptionGroup):
  905. res.extend(self._unroll_exceptions(exc.exceptions))
  906. else:
  907. res.append(exc)
  908. return res
  909. @overload
  910. def matches(
  911. self: RaisesGroup[ExcT_1],
  912. exception: BaseException | None,
  913. ) -> TypeGuard[ExceptionGroup[ExcT_1]]: ...
  914. @overload
  915. def matches(
  916. self: RaisesGroup[BaseExcT_1],
  917. exception: BaseException | None,
  918. ) -> TypeGuard[BaseExceptionGroup[BaseExcT_1]]: ...
  919. def matches(
  920. self,
  921. exception: BaseException | None,
  922. ) -> bool:
  923. """Check if an exception matches the requirements of this RaisesGroup.
  924. If it fails, `RaisesGroup.fail_reason` will be set.
  925. Example::
  926. with pytest.raises(TypeError) as excinfo:
  927. ...
  928. assert RaisesGroup(ValueError).matches(excinfo.value.__cause__)
  929. # the above line is equivalent to
  930. myexc = excinfo.value.__cause
  931. assert isinstance(myexc, BaseExceptionGroup)
  932. assert len(myexc.exceptions) == 1
  933. assert isinstance(myexc.exceptions[0], ValueError)
  934. """
  935. self._fail_reason = None
  936. if exception is None:
  937. self._fail_reason = "exception is None"
  938. return False
  939. if not isinstance(exception, BaseExceptionGroup):
  940. # we opt to only print type of the exception here, as the repr would
  941. # likely be quite long
  942. not_group_msg = f"`{type(exception).__name__}()` is not an exception group"
  943. if len(self.expected_exceptions) > 1:
  944. self._fail_reason = not_group_msg
  945. return False
  946. # if we have 1 expected exception, check if it would work even if
  947. # allow_unwrapped is not set
  948. res = self._check_expected(self.expected_exceptions[0], exception)
  949. if res is None and self.allow_unwrapped:
  950. return True
  951. if res is None:
  952. self._fail_reason = (
  953. f"{not_group_msg}, but would match with `allow_unwrapped=True`"
  954. )
  955. elif self.allow_unwrapped:
  956. self._fail_reason = res
  957. else:
  958. self._fail_reason = not_group_msg
  959. return False
  960. actual_exceptions: Sequence[BaseException] = exception.exceptions
  961. if self.flatten_subgroups:
  962. actual_exceptions = self._unroll_exceptions(actual_exceptions)
  963. if not self._check_match(exception):
  964. self._fail_reason = cast(str, self._fail_reason)
  965. old_reason = self._fail_reason
  966. if (
  967. len(actual_exceptions) == len(self.expected_exceptions) == 1
  968. and isinstance(expected := self.expected_exceptions[0], type)
  969. and isinstance(actual := actual_exceptions[0], expected)
  970. and self._check_match(actual)
  971. ):
  972. assert self.match is not None, "can't be None if _check_match failed"
  973. assert self._fail_reason is old_reason is not None
  974. self._fail_reason += (
  975. f"\n"
  976. f" but matched the expected `{self._repr_expected(expected)}`.\n"
  977. f" You might want "
  978. f"`RaisesGroup(RaisesExc({expected.__name__}, match={_match_pattern(self.match)!r}))`"
  979. )
  980. else:
  981. self._fail_reason = old_reason
  982. return False
  983. # do the full check on expected exceptions
  984. if not self._check_exceptions(
  985. exception,
  986. actual_exceptions,
  987. ):
  988. self._fail_reason = cast(str, self._fail_reason)
  989. assert self._fail_reason is not None
  990. old_reason = self._fail_reason
  991. # if we're not expecting a nested structure, and there is one, do a second
  992. # pass where we try flattening it
  993. if (
  994. not self.flatten_subgroups
  995. and not any(
  996. isinstance(e, RaisesGroup) for e in self.expected_exceptions
  997. )
  998. and any(isinstance(e, BaseExceptionGroup) for e in actual_exceptions)
  999. and self._check_exceptions(
  1000. exception,
  1001. self._unroll_exceptions(exception.exceptions),
  1002. )
  1003. ):
  1004. # only indent if it's a single-line reason. In a multi-line there's already
  1005. # indented lines that this does not belong to.
  1006. indent = " " if "\n" not in self._fail_reason else ""
  1007. self._fail_reason = (
  1008. old_reason
  1009. + f"\n{indent}Did you mean to use `flatten_subgroups=True`?"
  1010. )
  1011. else:
  1012. self._fail_reason = old_reason
  1013. return False
  1014. # Only run `self.check` once we know `exception` is of the correct type.
  1015. if not self._check_check(exception):
  1016. reason = (
  1017. cast(str, self._fail_reason) + f" on the {type(exception).__name__}"
  1018. )
  1019. if (
  1020. len(actual_exceptions) == len(self.expected_exceptions) == 1
  1021. and isinstance(expected := self.expected_exceptions[0], type)
  1022. # we explicitly break typing here :)
  1023. and self._check_check(actual_exceptions[0]) # type: ignore[arg-type]
  1024. ):
  1025. self._fail_reason = reason + (
  1026. f", but did return True for the expected {self._repr_expected(expected)}."
  1027. f" You might want RaisesGroup(RaisesExc({expected.__name__}, check=<...>))"
  1028. )
  1029. else:
  1030. self._fail_reason = reason
  1031. return False
  1032. return True
  1033. @staticmethod
  1034. def _check_expected(
  1035. expected_type: (
  1036. type[BaseException] | RaisesExc[BaseException] | RaisesGroup[BaseException]
  1037. ),
  1038. exception: BaseException,
  1039. ) -> str | None:
  1040. """Helper method for `RaisesGroup.matches` and `RaisesGroup._check_exceptions`
  1041. to check one of potentially several expected exceptions."""
  1042. if isinstance(expected_type, type):
  1043. return _check_raw_type(expected_type, exception)
  1044. res = expected_type.matches(exception)
  1045. if res:
  1046. return None
  1047. assert expected_type.fail_reason is not None
  1048. if expected_type.fail_reason.startswith("\n"):
  1049. return f"\n{expected_type!r}: {indent(expected_type.fail_reason, ' ')}"
  1050. return f"{expected_type!r}: {expected_type.fail_reason}"
  1051. @staticmethod
  1052. def _repr_expected(e: type[BaseException] | AbstractRaises[BaseException]) -> str:
  1053. """Get the repr of an expected type/RaisesExc/RaisesGroup, but we only want
  1054. the name if it's a type"""
  1055. if isinstance(e, type):
  1056. return _exception_type_name(e)
  1057. return repr(e)
  1058. @overload
  1059. def _check_exceptions(
  1060. self: RaisesGroup[ExcT_1],
  1061. _exception: Exception,
  1062. actual_exceptions: Sequence[Exception],
  1063. ) -> TypeGuard[ExceptionGroup[ExcT_1]]: ...
  1064. @overload
  1065. def _check_exceptions(
  1066. self: RaisesGroup[BaseExcT_1],
  1067. _exception: BaseException,
  1068. actual_exceptions: Sequence[BaseException],
  1069. ) -> TypeGuard[BaseExceptionGroup[BaseExcT_1]]: ...
  1070. def _check_exceptions(
  1071. self,
  1072. _exception: BaseException,
  1073. actual_exceptions: Sequence[BaseException],
  1074. ) -> bool:
  1075. """Helper method for RaisesGroup.matches that attempts to pair up expected and actual exceptions"""
  1076. # The _exception parameter is not used, but necessary for the TypeGuard
  1077. # full table with all results
  1078. results = ResultHolder(self.expected_exceptions, actual_exceptions)
  1079. # (indexes of) raised exceptions that haven't (yet) found an expected
  1080. remaining_actual = list(range(len(actual_exceptions)))
  1081. # (indexes of) expected exceptions that haven't found a matching raised
  1082. failed_expected: list[int] = []
  1083. # successful greedy matches
  1084. matches: dict[int, int] = {}
  1085. # loop over expected exceptions first to get a more predictable result
  1086. for i_exp, expected in enumerate(self.expected_exceptions):
  1087. for i_rem in remaining_actual:
  1088. res = self._check_expected(expected, actual_exceptions[i_rem])
  1089. results.set_result(i_exp, i_rem, res)
  1090. if res is None:
  1091. remaining_actual.remove(i_rem)
  1092. matches[i_exp] = i_rem
  1093. break
  1094. else:
  1095. failed_expected.append(i_exp)
  1096. # All exceptions matched up successfully
  1097. if not remaining_actual and not failed_expected:
  1098. return True
  1099. # in case of a single expected and single raised we simplify the output
  1100. if 1 == len(actual_exceptions) == len(self.expected_exceptions):
  1101. assert not matches
  1102. self._fail_reason = res
  1103. return False
  1104. # The test case is failing, so we can do a slow and exhaustive check to find
  1105. # duplicate matches etc that will be helpful in debugging
  1106. for i_exp, expected in enumerate(self.expected_exceptions):
  1107. for i_actual, actual in enumerate(actual_exceptions):
  1108. if results.has_result(i_exp, i_actual):
  1109. continue
  1110. results.set_result(
  1111. i_exp, i_actual, self._check_expected(expected, actual)
  1112. )
  1113. successful_str = (
  1114. f"{len(matches)} matched exception{'s' if len(matches) > 1 else ''}. "
  1115. if matches
  1116. else ""
  1117. )
  1118. # all expected were found
  1119. if not failed_expected and results.no_match_for_actual(remaining_actual):
  1120. self._fail_reason = (
  1121. f"{successful_str}Unexpected exception(s):"
  1122. f" {[actual_exceptions[i] for i in remaining_actual]!r}"
  1123. )
  1124. return False
  1125. # all raised exceptions were expected
  1126. if not remaining_actual and results.no_match_for_expected(failed_expected):
  1127. no_match_for_str = ", ".join(
  1128. self._repr_expected(self.expected_exceptions[i])
  1129. for i in failed_expected
  1130. )
  1131. self._fail_reason = f"{successful_str}Too few exceptions raised, found no match for: [{no_match_for_str}]"
  1132. return False
  1133. # if there's only one remaining and one failed, and the unmatched didn't match anything else,
  1134. # we elect to only print why the remaining and the failed didn't match.
  1135. if (
  1136. 1 == len(remaining_actual) == len(failed_expected)
  1137. and results.no_match_for_actual(remaining_actual)
  1138. and results.no_match_for_expected(failed_expected)
  1139. ):
  1140. self._fail_reason = f"{successful_str}{results.get_result(failed_expected[0], remaining_actual[0])}"
  1141. return False
  1142. # there's both expected and raised exceptions without matches
  1143. s = ""
  1144. if matches:
  1145. s += f"\n{successful_str}"
  1146. indent_1 = " " * 2
  1147. indent_2 = " " * 4
  1148. if not remaining_actual:
  1149. s += "\nToo few exceptions raised!"
  1150. elif not failed_expected:
  1151. s += "\nUnexpected exception(s)!"
  1152. if failed_expected:
  1153. s += "\nThe following expected exceptions did not find a match:"
  1154. rev_matches = {v: k for k, v in matches.items()}
  1155. for i_failed in failed_expected:
  1156. s += (
  1157. f"\n{indent_1}{self._repr_expected(self.expected_exceptions[i_failed])}"
  1158. )
  1159. for i_actual, actual in enumerate(actual_exceptions):
  1160. if results.get_result(i_exp, i_actual) is None:
  1161. # we print full repr of match target
  1162. s += (
  1163. f"\n{indent_2}It matches {backquote(repr(actual))} which was paired with "
  1164. + backquote(
  1165. self._repr_expected(
  1166. self.expected_exceptions[rev_matches[i_actual]]
  1167. )
  1168. )
  1169. )
  1170. if remaining_actual:
  1171. s += "\nThe following raised exceptions did not find a match"
  1172. for i_actual in remaining_actual:
  1173. s += f"\n{indent_1}{actual_exceptions[i_actual]!r}:"
  1174. for i_exp, expected in enumerate(self.expected_exceptions):
  1175. res = results.get_result(i_exp, i_actual)
  1176. if i_exp in failed_expected:
  1177. assert res is not None
  1178. if res[0] != "\n":
  1179. s += "\n"
  1180. s += indent(res, indent_2)
  1181. if res is None:
  1182. # we print full repr of match target
  1183. s += (
  1184. f"\n{indent_2}It matches {backquote(self._repr_expected(expected))} "
  1185. f"which was paired with {backquote(repr(actual_exceptions[matches[i_exp]]))}"
  1186. )
  1187. if len(self.expected_exceptions) == len(actual_exceptions) and possible_match(
  1188. results
  1189. ):
  1190. s += (
  1191. "\nThere exist a possible match when attempting an exhaustive check,"
  1192. " but RaisesGroup uses a greedy algorithm. "
  1193. "Please make your expected exceptions more stringent with `RaisesExc` etc"
  1194. " so the greedy algorithm can function."
  1195. )
  1196. self._fail_reason = s
  1197. return False
  1198. def __exit__(
  1199. self,
  1200. exc_type: type[BaseException] | None,
  1201. exc_val: BaseException | None,
  1202. exc_tb: types.TracebackType | None,
  1203. ) -> bool:
  1204. __tracebackhide__ = True
  1205. if exc_type is None:
  1206. fail(f"DID NOT RAISE any exception, expected `{self.expected_type()}`")
  1207. assert self.excinfo is not None, (
  1208. "Internal error - should have been constructed in __enter__"
  1209. )
  1210. # group_str is the only thing that differs between RaisesExc and RaisesGroup...
  1211. # I might just scrap it? Or make it part of fail_reason
  1212. group_str = (
  1213. "(group)"
  1214. if self.allow_unwrapped and not issubclass(exc_type, BaseExceptionGroup)
  1215. else "group"
  1216. )
  1217. if not self.matches(exc_val):
  1218. fail(f"Raised exception {group_str} did not match: {self._fail_reason}")
  1219. # Cast to narrow the exception type now that it's verified....
  1220. # even though the TypeGuard in self.matches should be narrowing
  1221. exc_info = cast(
  1222. "tuple[type[BaseExceptionGroup[BaseExcT_co]], BaseExceptionGroup[BaseExcT_co], types.TracebackType]",
  1223. (exc_type, exc_val, exc_tb),
  1224. )
  1225. self.excinfo.fill_unfilled(exc_info)
  1226. return True
  1227. def expected_type(self) -> str:
  1228. subexcs = []
  1229. for e in self.expected_exceptions:
  1230. if isinstance(e, RaisesExc):
  1231. subexcs.append(repr(e))
  1232. elif isinstance(e, RaisesGroup):
  1233. subexcs.append(e.expected_type())
  1234. elif isinstance(e, type):
  1235. subexcs.append(e.__name__)
  1236. else: # pragma: no cover
  1237. raise AssertionError("unknown type")
  1238. group_type = "Base" if self.is_baseexception else ""
  1239. return f"{group_type}ExceptionGroup({', '.join(subexcs)})"
  1240. @final
  1241. class NotChecked:
  1242. """Singleton for unchecked values in ResultHolder"""
  1243. class ResultHolder:
  1244. """Container for results of checking exceptions.
  1245. Used in RaisesGroup._check_exceptions and possible_match.
  1246. """
  1247. def __init__(
  1248. self,
  1249. expected_exceptions: tuple[
  1250. type[BaseException] | AbstractRaises[BaseException], ...
  1251. ],
  1252. actual_exceptions: Sequence[BaseException],
  1253. ) -> None:
  1254. self.results: list[list[str | type[NotChecked] | None]] = [
  1255. [NotChecked for _ in expected_exceptions] for _ in actual_exceptions
  1256. ]
  1257. def set_result(self, expected: int, actual: int, result: str | None) -> None:
  1258. self.results[actual][expected] = result
  1259. def get_result(self, expected: int, actual: int) -> str | None:
  1260. res = self.results[actual][expected]
  1261. assert res is not NotChecked
  1262. # mypy doesn't support identity checking against anything but None
  1263. return res # type: ignore[return-value]
  1264. def has_result(self, expected: int, actual: int) -> bool:
  1265. return self.results[actual][expected] is not NotChecked
  1266. def no_match_for_expected(self, expected: list[int]) -> bool:
  1267. for i in expected:
  1268. for actual_results in self.results:
  1269. assert actual_results[i] is not NotChecked
  1270. if actual_results[i] is None:
  1271. return False
  1272. return True
  1273. def no_match_for_actual(self, actual: list[int]) -> bool:
  1274. for i in actual:
  1275. for res in self.results[i]:
  1276. assert res is not NotChecked
  1277. if res is None:
  1278. return False
  1279. return True
  1280. def possible_match(results: ResultHolder, used: set[int] | None = None) -> bool:
  1281. if used is None:
  1282. used = set()
  1283. curr_row = len(used)
  1284. if curr_row == len(results.results):
  1285. return True
  1286. return any(
  1287. val is None and i not in used and possible_match(results, used | {i})
  1288. for (i, val) in enumerate(results.results[curr_row])
  1289. )