ADR-0035: Type OSError attributes by the raises that create them¶
Status¶
Accepted
Date¶
2026-11-15
Context¶
EXC-14 gave OSError and its subclasses CPython's reading of two to five
arguments as errno, strerror, filename, winerror and filename2,
with the attributes typed int | None and str | None. To keep those
types, it refused other argument types, more than five arguments, and two
or more through super().__init__, and EXC-16 plans them for 0.5.
CPython takes any object for each of them. OSError("a", "b") has
errno 'a' and is written [Errno a] b; OSError(1, 2, 3, 4, 5, 6)
reads none of its arguments and has every attribute None; and a subclass
with an __init__ of its own has its arguments read by OSError.__init__
when super().__init__(...) calls it, not by OSError.__new__. So the
type of errno depends on how the program creates its exceptions, as the
type of args does, which ADR-0034 infers from every creation.
One corner depends on a value known only when the program runs. CPython's
OSError.__init__ reads a number as the third argument of an exception
whose class is exactly BlockingIOError as characters_written, not as
the file name. OSError itself becomes BlockingIOError when errno is
EAGAIN, so OSError(code, "x", 3) has filename 3 or none depending
on code, and OSError(11, "x", 3.5) raises TypeError while
OSError(2, "x", 3.5) does not.
Options considered¶
- Infer the attributes from the raw arguments of every creation, as
ADR-0034 does for
args. Each creation of anOSErrorclass records the tuple of all its arguments, not only thoseargsshows, and each attribute is the item its position gives in each tuple, orNone. - Keep the attributes' EXC-14 types, and refuse an argument that does not fit them. Every attribute keeps one type with no inference, but EXC-16 stays unmet.
- Give the attributes the type of
args' items, the union of every item type. Simpler to infer, buterrnoofOSError(2, "x")would beint | str, and a program could not add 1 to it.
Decision¶
TyPy uses option 1.
- Raw arguments.
exception_arguments::Creationskeeps, for each creation, the tuple of every argument the exception holds, and givesargsfrom it by CPython's rule: a file name that is notNonekeeps onlyerrnoandstrerror.OSError's own text for a program's exception is written whenstrasks for it, from the items of any type, as CPython'sOSError_strdoes, and the runtime gives the class forerrnoonly when the first argument is anintor abool. - The attributes. For each layout of the raw arguments,
errnoandstrerrorare the first two items of two to five,filenamethe third of three to five, andfilename2the fifth of five when the third is notNone; any other layout givesNone. Lowering tests the layout of the exception's raw arguments against each, as it does forargs, and reading one of them makes the program checked again, as readingargsdoes. - A class with its own
__init__. Its exception starts with no arguments, andsuper().__init__(...)sets them, read as above. - The runtime's own
OSError. An error of a file opened from a descriptor keeps the descriptor as its third argument, sofilenameis theintCPython gives. - A number as the third argument of
OSErrororBlockingIOError, whose class may be exactlyBlockingIOErrorwhen the program runs, is E0201, planned for 1.0 withcharacters_written(EXC-18). A class derived from either, or another subclass, reads it as the file name.
Consequences¶
OSErrortakes arguments of any type, more than five of them, and two or more throughsuper().__init__, with CPython's attributes and text.errnoof a program that createsOSErroronly with anintand the runtime's raises staysint | None; one that also createsOSError("a", "b")haserrnoofint | str | None.- A program that reads
errno,strerror,filenameorfilename2is checked two or more times, as one that readsargsis. typy_rt_os_error_errnoandtypy_rt_os_error_textare no longer needed, and are removed.
Related requirements¶
EXC-14, EXC-15, EXC-16, EXC-18, CLS-14, ADR-0019, ADR-0034.