Files
Carl Meyer f076cb67a1 [ty] Preserve exception types after tuple truthiness checks (#30018)
Checking that a tuple of exception classes is nonempty can make ty
forget which exceptions it matches in `isinstance`, `issubclass`, and
`except`. Use the positive members of the narrowed type to retain the
exception types. Keep failed checks conservative when an intersection
excludes some class-info values, and cap the work of distributing
intersections over unions.

Closes astral-sh/ty#4895.

## Test plan

Ran ty on synthetic flat and nested class-info intersections with eleven
union-valued tuple members. Both checks completed promptly.

## Ecosystem report

The public ecosystem run at `2be8ff992a286ee82fca80daf4fad88cac7bb305`
found eight expected diagnostic removals from more precise exception
inference and class narrowing. Apprise loses one valid
`redundant-condition-strict` warning because the existing truthiness
evaluator treats the correctly narrowed union as ambiguous. The warning
loss is accepted for this PR. [Full ecosystem
report](https://github.com/astral-sh/ruff/pull/30018#issuecomment-6636630648)
2026-11-04 11:33:17 -08:00

9.2 KiB

Exception Handling

Single Exception

import re

try:
    help()
except NameError as e:
    reveal_type(e)  # revealed: NameError
except re.error as f:
    reveal_type(f)  # revealed: error

Unknown type in except handler does not cause spurious diagnostic

from nonexistent_module import foo  # error: [import-not-found]

try:
    help()
except foo as e:
    reveal_type(foo)  # revealed: Unknown
    reveal_type(e)  # revealed: Unknown

Multiple Exceptions in a Tuple

EXCEPTIONS = (AttributeError, TypeError)

try:
    help()
except (RuntimeError, OSError) as e:
    reveal_type(e)  # revealed: RuntimeError | OSError
except EXCEPTIONS as f:
    reveal_type(f)  # revealed: AttributeError | TypeError

Dynamic exception types

def foo(
    x: type[AttributeError],
    y: tuple[type[OSError], type[RuntimeError]],
    z: tuple[type[BaseException], ...],
    zz: tuple[type[TypeError | RuntimeError], ...],
    zzz: type[BaseException] | tuple[type[BaseException], ...],
    v: type[ValueError] | tuple[type[ValueError], ...],
):
    try:
        help()
    except x as e:
        reveal_type(e)  # revealed: AttributeError
    except y as f:
        reveal_type(f)  # revealed: OSError | RuntimeError
    except z as g:
        reveal_type(g)  # revealed: BaseException
    except zz as h:
        reveal_type(h)  # revealed: TypeError | RuntimeError
    except zzz as i:
        reveal_type(i)  # revealed: BaseException
    except v as j:
        reveal_type(j)  # revealed: ValueError

Previously narrowed tuple of exception classes

Checking that the tuple is nonempty preserves the type of the caught exception.

def catch(classes: tuple[type[ValueError], ...]):
    assert classes
    try:
        help()
    except classes as exc:
        reveal_type(exc)  # revealed: ValueError

Previously narrowed union of exception tuples

The caught exception can come from any tuple in the union.

def catch(classes: tuple[type[ValueError], ...] | tuple[type[RuntimeError], ...]):
    assert classes
    try:
        help()
    except classes as exc:
        reveal_type(exc)  # revealed: ValueError | RuntimeError

Type alias for a narrowed tuple of exception classes

The caught type comes from the tuple described by the alias.

[environment]
python-version = "3.12"
from ty_extensions import AlwaysFalsy, Intersection, Not

type NonemptyErrors = Intersection[tuple[type[ValueError], ...], Not[AlwaysFalsy]]

def catch(classes: NonemptyErrors):
    try:
        help()
    except classes as exc:
        reveal_type(exc)  # revealed: ValueError

Negated dynamic type aliases

A negated alias of Any behaves like Any in both single and tuple exception handlers.

[environment]
python-version = "3.12"
from typing import Any
from ty_extensions import Not

type Dynamic = Any

def catch_negated_alias(exc: Not[Dynamic]) -> None:
    try:
        raise ValueError
    except exc as single:
        reveal_type(single)  # revealed: Any

    try:
        raise ValueError
    except (exc,) as tuple_element:
        reveal_type(tuple_element)  # revealed: Any

Exception-class expressions

Exception-class expressions can produce intersections, gradual refinements, or unions. Positive class-object constraints project into the caught instance type; unmappable positive constraints and exact-class negatives do not exclude valid subclass instances.

from typing import Any
from ty_extensions import Intersection

class FirstError(Exception): ...
class SecondError(Exception): ...

def catch_intersection(exc: Intersection[type[FirstError], type[SecondError]]) -> None:
    try:
        help()
    except exc as caught:
        reveal_type(caught)  # revealed: FirstError & SecondError

def catch_proper_subclass(exc: Any) -> None:
    if exc != ValueError and issubclass(exc, ValueError):
        reveal_type(exc)  # revealed: Any & type[ValueError] & ~<class 'ValueError'>
        try:
            help()
        except exc as caught:
            reveal_type(caught)  # revealed: Any & ValueError

try:
    help()
except ZeroDivisionError and ValueError as caught:
    reveal_type(caught)  # revealed: ZeroDivisionError | ValueError

We do not emit an invalid-exception-caught if a class is caught that has Any or Unknown in its MRO, as the dynamic element in the MRO could materialize to some subclass of BaseException:

from compat import BASE_EXCEPTION_CLASS  # error: [import-not-found] "Cannot resolve imported module `compat`"

class Error(BASE_EXCEPTION_CLASS): ...

try:
    pass
except Error as err:
    pass

Exception with no captured type

try:
    {}.get("foo")
except TypeError:
    pass

Exception which catches typevar

[environment]
python-version = "3.12"
from typing import Callable, TypeVar

E = TypeVar("E", bound=Exception)

def silence[T: type[BaseException]](
    func: Callable[[], None],
    exception_type: T,
):
    try:
        func()
    except exception_type as e:
        reveal_type(e)  # revealed: T'instance@silence

def silence2[T: (type[ValueError], type[TypeError])](func: Callable[[], None], exception_type: T):
    try:
        func()
    except exception_type as e:
        reveal_type(e)  # revealed: T'instance@silence2

def silence3(func: Callable[[], None], exception_types: type[E] | tuple[type[E], ...]):
    try:
        func()
    except exception_types as e:
        reveal_type(e)  # revealed: E@silence3

def silence4[T: type[BaseException] | tuple[type[BaseException], ...]](
    func: Callable[[], None],
    exception_types: T,
):
    try:
        func()
    except exception_types as e:
        # TODO: Should reveal something more like `T'instance@silence4`.
        reveal_type(e)  # revealed: BaseException

Invalid exception handlers

try:
    raise Exception
# error: [invalid-exception-caught]
except 3 as e:
    reveal_type(e)  # revealed: Unknown

try:
    raise Exception
# error: [invalid-exception-caught]
except (ValueError, OSError, "foo", b"bar") as e:
    reveal_type(e)  # revealed: ValueError | OSError | Unknown

def foo(
    x: type[str],
    y: tuple[type[OSError], type[RuntimeError], int],
    z: tuple[type[str], ...],
):
    try:
        help()
    # error: [invalid-exception-caught]
    except x as e:
        reveal_type(e)  # revealed: Unknown
    # error: [invalid-exception-caught]
    except y as f:
        reveal_type(f)  # revealed: OSError | RuntimeError | Unknown
    # error: [invalid-exception-caught]
    except z as g:
        reveal_type(g)  # revealed: Unknown

try:
    {}.get("foo")
# error: [invalid-exception-caught]
except int:
    pass

Object raised is not an exception

try:
    raise AttributeError()  # fine
except:
    pass

try:
    raise FloatingPointError  # fine
except:
    pass

try:
    raise 1  # error: [invalid-raise]
except:
    pass

try:
    raise int  # error: [invalid-raise]
except:
    pass

def _(e: Exception | type[Exception]):
    raise e  # fine

def _(e: Exception | type[Exception] | None):
    raise e  # error: [invalid-raise]

Exception cause is not an exception

def _():
    try:
        raise EOFError() from GeneratorExit  # fine
    except:
        pass

def _():
    try:
        raise StopIteration from MemoryError()  # fine
    except:
        pass

def _():
    try:
        raise BufferError() from None  # fine
    except:
        pass

def _():
    try:
        raise ZeroDivisionError from False  # error: [invalid-raise]
    except:
        pass

def _():
    try:
        raise SystemExit from bool()  # error: [invalid-raise]
    except:
        pass

def _():
    try:
        raise
    except KeyboardInterrupt as e:  # fine
        reveal_type(e)  # revealed: KeyboardInterrupt
        raise LookupError from e  # fine

def _():
    try:
        raise
    except int as e:  # error: [invalid-exception-caught]
        reveal_type(e)  # revealed: Unknown
        raise KeyError from e

def _(e: Exception | type[Exception]):
    raise ModuleNotFoundError from e  # fine

def _(e: Exception | type[Exception] | None):
    raise IndexError from e  # fine

def _(e: int | None):
    raise IndexError from e  # error: [invalid-raise]

The caught exception is cleared at the end of the except clause

e = None
reveal_type(e)  # revealed: None

try:
    raise ValueError()
except ValueError as e:
    reveal_type(e)  # revealed: ValueError
# error: [unresolved-reference]
reveal_type(e)  # revealed: Unknown

e = None

def cond() -> bool:
    return True

try:
    if cond():
        raise ValueError()
except ValueError as e:
    reveal_type(e)  # revealed: ValueError
# error: [possibly-unresolved-reference]
reveal_type(e)  # revealed: None

def f(x: type[Exception]):
    e = None
    try:
        raise x
    except ValueError as e:
        pass
    except:
        pass
    # error: [possibly-unresolved-reference]
    reveal_type(e)  # revealed: None

Special-cased diagnostics for NotImplemented

try:
    # error: [invalid-raise]
    # error: [invalid-raise]
    raise NotImplemented from NotImplemented
# error: [invalid-exception-caught]
except NotImplemented:
    pass
# error: [invalid-exception-caught]
except (TypeError, NotImplemented):
    pass