Exceptions¶
Exceptions are standard Python exceptions. You raise them with raise,
catch them with try and except, build them by calling an exception
class, and an exception nothing catches ends the program as CPython ends
it.
What TyPy accepts¶
| Item | Rule |
|---|---|
raise with an exception, or with a class, which is called with no arguments |
SMT-06 |
raise ... from cause and raise ... from None |
EXC-04 |
try with except clauses, else and finally |
CST-04 |
except C, except (A, B), except C as name and a bare except |
EXC-01, EXC-09 |
A bare raise inside an except clause, which re-raises the exception |
EXC-07 |
| The built-in exception classes below, as values, annotations and calls | EXC-02, EXC-10 |
| An exception stored where one of its bases is declared | EXC-01 |
str, repr, print and f-strings of an exception, from its arguments |
EXC-08 |
type(e), the class the exception was made from |
CLS-12 |
| Classes of your own derived from an exception class, with attributes and methods | CLS-03 |
__init__, __str__ and __repr__ defined again in such a class |
CLS-13 |
super().__init__(...) in the __init__ of such a class |
CLS-14 |
assert test and assert test, message, in every build mode |
SMT-04 |
An except clause catches an exception of the class it names or of any
class derived from it, so except LookupError catches a KeyError. The
clauses are tried in order. The name after as holds the exception while
the clause runs and is deleted when it ends, as in CPython; with several
classes it is a union of them, such as ValueError | KeyError, whose
attributes and methods are those of their nearest common base. An exception no
clause catches goes on to the code around the try. else runs when the
body raised nothing. finally runs on every way out of the try: after
the body, a clause or else, on return, break and continue, and
before an exception goes on. While an exception waits for finally, an
exception raised in the block keeps it as its context.
An exception raised while another is handled keeps it as its context. An
uncaught exception prints a traceback on standard error whose last line
matches CPython's, and the program exits with status 1 (STD-05). A cause
named with from is printed first, followed by The above exception was
the direct cause of the following exception:, and a context is printed
first, followed by During handling of the above exception, another
exception occurred:, as CPython prints them.
assert test, message raises AssertionError(message) when the test is
false, and evaluates the message only then. TyPy keeps every assert in
every build mode, as CPython does without -O. What the test shows holds
after it, so assert value is not None lets the code below use value
as its base type.
Exception classes of your own¶
A class derived from a built-in exception class, or from another such
class defined before it, is an exception class. It holds its base's
attributes first, then its own, and finds a method it does not define in
its nearest base. Calling it makes an exception whose arguments are the
values passed by position, as CPython's BaseException keeps them, then
runs __init__. super().__init__(...) in __init__ calls the base's
__init__, or sets the arguments when the base is built in, and after it
the base's attributes count as assigned.
class HttpError(Exception):
def __init__(self, status: int, reason: str) -> None:
super().__init__(f"{status} {reason}")
self.status = status
class NotFound(HttpError):
def __str__(self) -> str:
return f"not found ({self.status})"
try:
raise NotFound(404, "missing")
except HttpError as error:
print(error, repr(error), error.status)
Built-in exception classes¶
| Class | Base |
|---|---|
BaseException |
object |
Exception, SystemExit |
BaseException |
ArithmeticError, AssertionError, AttributeError, EOFError, ImportError, LookupError, NameError |
Exception |
OSError, RuntimeError, StopIteration, TypeError, ValueError |
Exception |
OverflowError, ZeroDivisionError |
ArithmeticError |
IndexError, KeyError |
LookupError |
NotImplementedError, RecursionError |
RuntimeError |
UnicodeError |
ValueError |
UnicodeDecodeError, UnicodeEncodeError |
UnicodeError |
BlockingIOError, ChildProcessError, ConnectionError, FileExistsError, FileNotFoundError, InterruptedError |
OSError |
IsADirectoryError, NotADirectoryError, PermissionError, ProcessLookupError, TimeoutError |
OSError |
BrokenPipeError, ConnectionAbortedError, ConnectionRefusedError, ConnectionResetError |
ConnectionError |
IOError and EnvironmentError are other names of OSError, as in
CPython. An OSError that open raises reads as CPython's, such as
[Errno 2] No such file or directory: 'notes.txt', and the class is the
one the error number gives, such as FileNotFoundError. Reading a file
opened for writing raises io.UnsupportedOperation: not readable, which
both except OSError and except ValueError catch.
An exception class takes positional arguments of any type. The text of the
exception follows them as in CPython: no argument gives an empty text, one
gives its str, and several give the tuple. A KeyError shows the repr
of its key.
Example¶
def withdraw(balance: int, amount: int) -> int:
if amount > balance:
raise ValueError("insufficient funds", amount - balance)
return balance - amount
def try_withdraw(balance: int, amount: int) -> int:
try:
return withdraw(balance, amount)
except ValueError as error:
print("refused:", error)
return balance
error: LookupError = KeyError("owner")
print(error, repr(error), type(error).__name__)
print(try_withdraw(10, 3), try_withdraw(10, 30))
What TyPy refuses¶
raise takes an exception or an exception class, so raising a message
fails with E0415:
raise "insufficient funds"
An except clause names classes, so except "ValueError": fails with
E0418. A return, break or continue that would leave a finally
block drops the exception on its way out, so it fails with E0419, as
CPython 3.14 warns about it. A bare raise re-raises the exception being
handled, so it is refused outside an except clause with E0416.
UnicodeDecodeError and UnicodeEncodeError take five arguments that
TyPy does not check, so a program cannot call them (E0417); it can still
catch them.
Overriding methods¶
An exception class may define a method of its base again, as any class may (CLS-04). The exception's own class decides which method runs:
class AppError(Exception):
def code(self) -> int:
return 1
class OtherError(AppError):
def code(self) -> int:
return 2
try:
raise OtherError("busy")
except AppError as error:
print(error, error.code())
The arguments and the exit code¶
error.args is the tuple of the arguments an exception was built with
(EXC-11), and stop.code of a SystemExit is None, its one argument,
or the tuple of several (EXC-13). Either may hold any value, so TyPy
reads them where a program writes, compares or tests them: print,
str, repr, bool, an f-string field, == and != with any value, a
condition, not, and len of args (ADR-0030):
import sys
try:
raise ValueError("bad value", 3)
except ValueError as error:
print(error.args, len(error.args), error.args == ("bad value", 3))
try:
sys.exit(2)
except SystemExit as stop:
if stop.code == 2:
print(f"exit code {stop.code!r}")
Each is also a value of its own, which you store, pass, index, unpack
and loop over (EXC-15). Its type comes from every place the program and
TyPy itself create an exception of the class or of a class derived from
it: ValueError("bad", 3) gives tuple[str, int], and the message of a
ValueError TyPy raises, such as the one of int("x"), gives
tuple[str]. So args of a ValueError here is
tuple[str, int] | tuple[str], and error.args[1] raises IndexError
when the exception holds one argument, as CPython does. The five items of
a UnicodeEncodeError or UnicodeDecodeError, both ValueError
classes, join only when the program encodes, decodes or opens a file:
def parse(text: str) -> int:
if not text:
raise ValueError("empty input", 0)
return int(text)
for text in ["", "x"]:
try:
parse(text)
except ValueError as error:
message = error.args[0]
print(message.upper(), len(error.args))
for item in error.args:
print(item)
code of a SystemExit is None for sys.exit(), the argument for
one, and the tuple for several. A KeyError TyPy raises holds the
missing key, so args of a KeyError includes tuple[K] for the key
type K of each dict the program looks up. An exception whose arguments
hold args of an exception of a related class, such as
raise ValueError(error.args) in an except ValueError clause, has a
type without end; it is planned for 1.0 (E0201, EXC-17).
OS errors¶
OSError and its subclasses built with two to five arguments read them
as CPython does (EXC-14): errno, strerror, filename, winerror and
filename2. OSError itself becomes the subclass for errno, so
OSError(2, "gone") is a FileNotFoundError. The attributes errno,
strerror, filename and filename2 are None when not given, as for
an OSError of one argument, and open gives them too:
try:
raise OSError(2, "No such file or directory", "data.txt")
except FileNotFoundError as error:
print(error, repr(error))
print(error.errno, error.strerror, error.filename)
The arguments may be of any type, as in CPython (EXC-16):
OSError("a", "b") is written [Errno a] b, an OSError of more than
five arguments reads none of them, and a subclass with an __init__ of its
own starts with no arguments, which super().__init__(...) gives it. The
type of each attribute comes from every place the program and TyPy create
an exception of the class, as the type of args does, so errno is
int | None unless the program builds an OSError with another errno:
class ConfigError(OSError):
def __init__(self, path: str) -> None:
super().__init__(2, "missing setting", path)
try:
raise ConfigError("app.toml")
except OSError as error:
print(error, error.args)
code = error.errno
if code is not None:
print(code + 100, error.filename)
A number as the third argument of OSError or BlockingIOError is
planned for 1.0 (E0201, EXC-18): a BlockingIOError reads it as
characters_written, and OSError becomes one for errno 11.
Planned¶
Exception groups and except* are planned for after 1.0.