ADR-0031: Type a file by its literal mode, and a mode value as text¶
Status¶
Accepted
Date¶
2026-11-14
Context¶
CPython's open gives an object whose class depends on its arguments:
TextIOWrapper for a text mode, BufferedReader, BufferedWriter or
BufferedRandom for a binary mode, and FileIO for a binary mode with
buffering=0. typeshed types open by overloads on literal modes and a
literal buffering, and gives IO[Any] or BinaryIO when either is a
value only known when the program runs.
TyPy checks every type when it compiles, and has no Any (TYP-10) or
typing.IO yet. LIB-14 asks for binary modes and for a mode that is not
a literal.
Options considered¶
- One type per class, from the literal mode and
buffering. A mode or a binarybufferingthat is not a literal has no type and is refused. - A union of the five classes for any
open, which a program narrows withisinstancebefore it reads or writes. - Option 1, and a mode that is not a literal types as text. Such a
mode is checked when the program runs, and one with
bis refused then, since a text file cannot hold bytes.
Decision¶
TyPy uses option 3.
Type::BinaryFilehas aBinaryKindfor each binary class, shown by CPython's class name. A literal binary mode givesBufferedReader,BufferedWriterorBufferedRandom; with the literalbuffering=0it givesFileIO.- A binary mode with a
bufferingthat is not a literal is E0201, planned for 1.0 withtyping.BinaryIO(LIB-19).buffering=1makes CPython warn with the program's file and line, so it is E0404. - A mode that is not a literal gives a
TextIOWrapper. The runtime checks it with CPython'sValueErrormessages, and a mode withbraisesTypeError, which CPython would not raise. - All five classes are one runtime object, the text file of ADR-0019,
with flags for binary and for
FileIO.
Consequences¶
- Programs that open text files with a mode held in a variable, a common pattern, are accepted.
- A program that opens a binary file through a mode held in a variable fails when it runs, where CPython gives a binary file. The guide says so.
- Assigning files of two classes to one variable is refused, as mypy refuses it.
Related requirements¶
LIB-04, LIB-14, LIB-19, TYP-10, ADR-0019.