typing_raises_group.py

Overview

This file provides extensive type checking and validation utilities focused on the `pytest` framework's exception-raising context managers, specifically `RaisesExc` and `RaisesGroup`. It contains a series of test-like functions that verify the correct typing behavior, constructor usage, type narrowing, and matching logic of these classes. These checks ensure type safety, proper covariance and contravariance in generics, and correct behavior when dealing with Python 3.11's `ExceptionGroup` and its backport `exceptiongroup`.

Key points:

• It verifies the interaction between pytest's exception context managers and Python's ExceptionGroups.

• It tests type narrowing and matching behavior for exceptions, especially nested exception groups.

• It explores usage scenarios including nested RaisesGroup instances, multiple exceptions, and constructor argument variations.

• It highlights some typing limitations and discrepancies (noted with FIXME and type: ignore comments).

This file is primarily useful for maintainers of `pytest` or typing-related tooling to ensure that the exception-raising utilities behave correctly with static type checkers.

Classes, Functions, and Methods

Imported Entities

• RaisesExc, RaisesGroup — Context managers from pytest for testing raised exceptions.

• Failed, main_Failed — Exception classes related to test failures in pytest.

• ExceptionGroup, BaseExceptionGroup — Python 3.11+ exception groups or their backport.

• assert_type — Utility from typing_extensions to assert static types in tests.

Functions

All functions are scoped tests or usage examples demonstrating typing and behavior of `RaisesExc` and `RaisesGroup`.

check_raisesexc_typevar_default(e: RaisesExc) -> None

• Purpose:
  Validates that the expected_exceptions attribute of a RaisesExc instance is properly typed and not None. Also demonstrates that calling exception_type() returns a type that supports attribute access (though .blah() is a dummy call to illustrate typing).

• Parameters:

  • e: Instance of RaisesExc.

• Returns:
  None.

• Usage:
  Used to verify static typing of RaisesExc's internal types.

check_basic_contextmanager() -> None

• Purpose:
  Tests the basic usage of RaisesGroup as a context manager with a single exception type (ValueError), raising an ExceptionGroup. It asserts the type of the caught exception.

• Returns:
  None.

• Example:

  with RaisesGroup(ValueError) as e:
      raise ExceptionGroup("foo", (ValueError(),))
  assert_type(e.value, ExceptionGroup[ValueError])
  

check_basic_matches() -> None

• Purpose:
  Verifies that the .matches() method of RaisesGroup properly narrows types when matching exceptions, including unions and base classes.

• Returns:
  None.

• Details:
  Shows how RaisesGroup(ValueError).matches() narrows an exception union and how BaseExceptionGroup is recognized for base exceptions.

check_matches_with_different_exception_type() -> None

• Purpose:
  Examines behavior when RaisesGroup is used with an exception type that differs from the actual exception group's type. It notes that type checkers cannot warn about this mismatch currently.

• Returns:
  None.

check_raisesexc_init() -> None

• Purpose:
  Tests various constructor signatures of RaisesExc, including positional and keyword arguments, and verifies type constraints on the check callable parameter.

• Details:

  • Shows that expected_exception must be positional-only.

  • match and check are keyword-only.

  • Demonstrates correct and incorrect usage with type: ignore for invalid cases.

• Returns:
  None.

raisesgroup_check_type_narrowing() -> None

• Purpose:
  Tests type narrowing logic on the check argument of RaisesGroup for different exception types.

• Details:

  • Defines handlers for various exception groups.

  • Verifies which handlers are allowed or disallowed by the type checker.

• Returns:
  None.

raisesgroup_narrow_baseexceptiongroup() -> None

• Purpose:
  Verifies type narrowing for container exception groups (ExceptionGroup) specifically when used with RaisesGroup.

• Returns:
  None.

check_raisesexc_transparent() -> None

• Purpose:
  Demonstrates transparent usage of RaisesGroup with a nested RaisesExc and asserts the type of the caught exception.

• Returns:
  None.

check_nested_raisesgroups_contextmanager() -> None

• Purpose:
  Tests nested RaisesGroup context managers and verifies proper typing of nested ExceptionGroup structures.

• Returns:
  None.

check_nested_raisesgroups_matches() -> None

• Purpose:
  Tests nested RaisesGroup usage with .matches() method and verifies type narrowing on nested exception groups.

• Returns:
  None.

check_multiple_exceptions_1() -> None

• Purpose:
  Tests that RaisesGroup can be constructed with multiple exceptions or RaisesExc instances and that type assignments are valid for a single exception type.

• Returns:
  None.

check_multiple_exceptions_2() -> None

• Purpose:
  Ensures that covariance in the type variable of RaisesGroup correctly allows assignment of multiple exception types to a broader exception type.

• Returns:
  None.

check_raisesgroup_overloads() -> None

• Purpose:
  Tests different constructor argument combinations of RaisesGroup, focusing on allow_unwrapped and flatten_subgroups flags, and verifies which combinations are allowed or disallowed by type checkers.

• Returns:
  None.

check_triple_nested_raisesgroup() -> None

• Purpose:
  Demonstrates triple nested RaisesGroup usage and verifies the deeply nested exception group typing.

• Returns:
  None.

check_check_typing() -> None

• Purpose:
  Asserts the typing of the check attribute on a RaisesGroup instance, verifying it is a callable or None.

• Returns:
  None.

Important Implementation Details and Algorithms

• Type Narrowing and Matching:
  The core focus of this file is on how RaisesGroup and RaisesExc narrow exception types through their .matches() methods and context manager usage. This involves Python 3.11's ExceptionGroup and its generic typing to ensure that exceptions are properly identified and matched in nested groups.

• Covariance and Contravariance:
  Tests show that RaisesGroup is designed with covariance in mind, allowing broader exception types to be assigned to narrower ones under certain conditions, which is critical for sound static typing in dynamic exception testing.

• Constructor Argument Validation:
  The file documents, through examples, the expected usage of RaisesExc and RaisesGroup constructors, noting positional-only and keyword-only parameters, and how match strings and check callables interact.

• Backport Compatibility:
  For Python versions prior to 3.11, the file imports BaseExceptionGroup and ExceptionGroup from the third-party exceptiongroup package to maintain compatibility.

• Type Assertions:
  The use of assert_type from typing_extensions throughout the file helps verify that the runtime types align with the expected static types, providing a form of "tests for the type checker."

Interaction with Other System Components

• pytest Framework:
  This file directly interacts with pytest's exception testing utilities (RaisesExc, RaisesGroup), which are used widely in test code to assert that exceptions occur as expected.

• Python Standard Library:
  Uses Python 3.11's ExceptionGroup and BaseExceptionGroup types where available, or falls back on the exceptiongroup package for earlier versions.

• Static Type Checking Tools:
  The file is intended to be used with static type checkers such as mypy or pyright to validate type correctness of exception group handling in pytest.

• Type Hints and Typing Extensions:
  Relies on typing_extensions.assert_type for runtime assertions of static types, enhancing confidence in type correctness.

Visual Diagram

classDiagram
    class RaisesExc {
        +__init__(expected_exception: BaseException | None = ..., match: str | None = ..., check: Callable | None = ...)
        +expected_exceptions: type[BaseException] | tuple[type[BaseException], ...] | None
        +exception_type() -> type[BaseException]
    }

    class RaisesGroup {
        +__init__(*exceptions: RaisesExc | type[BaseException], match: str | None = ..., check: Callable | None = ..., allow_unwrapped: bool = False, flatten_subgroups: bool = False)
        +matches(exc: BaseException | BaseExceptionGroup) -> bool
        +check: Callable[[BaseExceptionGroup], bool] | None
        +value: BaseExceptionGroup
    }

    class ExceptionGroup {
        +exceptions: tuple[BaseException, ...]
        +message: str
    }

    class BaseExceptionGroup {
        +exceptions: tuple[BaseException, ...]
        +message: str
    }

    RaisesExc --> BaseException
    RaisesGroup --> RaisesExc
    RaisesGroup --> BaseExceptionGroup
    RaisesGroup --> BaseException
    RaisesGroup --> ExceptionGroup

Summary

This file serves as a comprehensive set of static typing and usage tests for `pytest`'s advanced exception handling utilities, focusing on the interplay with Python’s `ExceptionGroup` mechanism. It is an essential aid in ensuring that exception-raising assertions in tests are both type-safe and semantically correct, particularly as Python’s exception grouping features evolve.

**End of documentation for `typing_raises_group.py`**