ADR-0034: Type exception args by the raises that create them¶
Status¶
Accepted
Date¶
2026-11-15
Context¶
EXC-15 asks for args of an exception and code of a SystemExit as
values of their own: stored, passed, indexed and iterated. ADR-0030 left
them to the uses the runtime can answer without a type, such as printing
and comparing, and deferred the rest until TyPy had a type for them.
CPython types them as tuple[Any, ...] and Any. TyPy has no type of
any value, and TYP-10 keeps one type per value. But a TyPy program is
compiled whole, so every place an exception can be created is known: each
raise and call of an exception class in the program, and each exception
the runtime raises, whose arguments the runtime fixes. Most programs give
an exception class one shape of arguments, often a single message, so
args has one tuple type in practice.
Two facts constrain the design. Modules are checked one after another, so
when one module reads error.args, a raise in a later module is not
typed yet. And a union that holds tuples is a tag with a slot per member
(ADR-0027), not an object, so args is read from the exception's argument
tuple item by item, by its layout's descriptor (ADR-0013).
Options considered¶
- Infer the types from the raises that create the exception.
argsof a value of exception classChas the union of the argument tuples of every way the program and the runtime create aCor a class derived from it. Every value keeps one type, andargscan be passed to a parameter annotated with that type. - One opaque kind of value for exception parts, whose items the runtime reads by their descriptor. Stored, indexed and iterated, but no annotation can name it, so it cannot be passed to a typed parameter.
- A value of any type for 1.0, with EXC-15 moved there.
Decision¶
TyPy uses option 1.
- What creates an exception. A call of an exception class in the
program gives a tuple of its arguments' types; for a class whose
__init__callssuper().__init__(...), the arguments of that call (CLS-14).raise Cwithout a call givestuple[()]. The runtime's own raises are a table: a message,tuple[str], for most classes;KeyError, the key, of each key type of a dict and item type of a set in the program;OSErrorand its subclasses,(int, str)and(int, str, str); the Unicode errors, their five arguments;StopIterationfromnext(),tuple[()]; andSystemExitandAssertionError, the program'ssys.exitandassertvalues. - The type of
args. For a value whose static type is classC, the union of the tuples of every creation ofCand of each class derived from it, members in a fixed order.codeof aSystemExitis the union ofNonefor no argument, the argument's type for one, and the tuple for several. - The order of checking. A first check of the program records each
creation, and whether any use of
argsorcodeneeds its type. Only when one does, the program is checked again with the types the first check found, and again while a check finds a creation the one before did not, so a raise whose arguments come fromargssettles. A program that never readsargsorcodeas a value is checked once, as before. - Reading the value. Lowering reads
argsfrom the exception's argument tuple: it compares the tuple's descriptor with each member of the union and reads the items of the matching one, each a word of the runtime. An item that is itself a tuple is E0201, planned for 1.0. ADR-0030's operations, such asprint(error.args), keep their runtime calls.
Consequences¶
argsandcodeare typed values that a program stores, passes, indexes, unpacks and iterates, with no new kind of value and no boxing.- A program that reads them as values is checked two or more times, which lengthens its check by the time of each extra pass; others are not.
- A raise added anywhere in the program can change the type of
argselsewhere, as a new member of a union, which may refuse an operation that was accepted before, such as an index past a shorter tuple's end. - Iteration over a union of tuples, needed for
for item in error.args, is added for every union of tuples. - The runtime's table of its own raises is part of the design; each new raise of the runtime adds its row.
Related requirements¶
EXC-11, EXC-13, EXC-14, EXC-15, CLS-14, TYP-10, TYP-14, ADR-0013, ADR-0027, ADR-0030.