| 1 |
.. _tut-errors: |
| 2 |
|
| 3 |
********************* |
| 4 |
Errors and Exceptions |
| 5 |
********************* |
| 6 |
|
| 7 |
Until now error messages haven't been more than mentioned, but if you have tried |
| 8 |
out the examples you have probably seen some. There are (at least) two |
| 9 |
distinguishable kinds of errors: *syntax errors* and *exceptions*. |
| 10 |
|
| 11 |
|
| 12 |
.. _tut-syntaxerrors: |
| 13 |
|
| 14 |
Syntax Errors |
| 15 |
============= |
| 16 |
|
| 17 |
Syntax errors, also known as parsing errors, are perhaps the most common kind of |
| 18 |
complaint you get while you are still learning Python:: |
| 19 |
|
| 20 |
>>> while True print('Hello world') |
| 21 |
File "<stdin>", line 1 |
| 22 |
while True print('Hello world') |
| 23 |
^^^^^ |
| 24 |
SyntaxError: invalid syntax |
| 25 |
|
| 26 |
The parser repeats the offending line and displays little arrows pointing |
| 27 |
at the place where the error was detected. Note that this is not always the |
| 28 |
place that needs to be fixed. In the example, the error is detected at the |
| 29 |
function :func:`print`, since a colon (``':'``) is missing just before it. |
| 30 |
|
| 31 |
The file name (``<stdin>`` in our example) and line number are printed so you |
| 32 |
know where to look in case the input came from a file. |
| 33 |
|
| 34 |
|
| 35 |
.. _tut-exceptions: |
| 36 |
|
| 37 |
Exceptions |
| 38 |
========== |
| 39 |
|
| 40 |
Even if a statement or expression is syntactically correct, it may cause an |
| 41 |
error when an attempt is made to execute it. Errors detected during execution |
| 42 |
are called *exceptions* and are not unconditionally fatal: you will soon learn |
| 43 |
how to handle them in Python programs. Most exceptions are not handled by |
| 44 |
programs, however, and result in error messages as shown here:: |
| 45 |
|
| 46 |
>>> 10 * (1/0) |
| 47 |
Traceback (most recent call last): |
| 48 |
File "<stdin>", line 1, in <module> |
| 49 |
10 * (1/0) |
| 50 |
~^~ |
| 51 |
ZeroDivisionError: division by zero |
| 52 |
>>> 4 + spam*3 |
| 53 |
Traceback (most recent call last): |
| 54 |
File "<stdin>", line 1, in <module> |
| 55 |
4 + spam*3 |
| 56 |
^^^^ |
| 57 |
NameError: name 'spam' is not defined |
| 58 |
>>> '2' + 2 |
| 59 |
Traceback (most recent call last): |
| 60 |
File "<stdin>", line 1, in <module> |
| 61 |
'2' + 2 |
| 62 |
~~~~^~~ |
| 63 |
TypeError: can only concatenate str (not "int") to str |
| 64 |
|
| 65 |
The last line of the error message indicates what happened. Exceptions come in |
| 66 |
different types, and the type is printed as part of the message: the types in |
| 67 |
the example are :exc:`ZeroDivisionError`, :exc:`NameError` and :exc:`TypeError`. |
| 68 |
The string printed as the exception type is the name of the built-in exception |
| 69 |
that occurred. This is true for all built-in exceptions, but need not be true |
| 70 |
for user-defined exceptions (although it is a useful convention). Standard |
| 71 |
exception names are built-in identifiers (not reserved keywords). |
| 72 |
|
| 73 |
The rest of the line provides detail based on the type of exception and what |
| 74 |
caused it. |
| 75 |
|
| 76 |
The preceding part of the error message shows the context where the exception |
| 77 |
occurred, in the form of a stack traceback. In general it contains a stack |
| 78 |
traceback listing source lines; however, it will not display lines read from |
| 79 |
standard input. |
| 80 |
|
| 81 |
:ref:`bltin-exceptions` lists the built-in exceptions and their meanings. |
| 82 |
|
| 83 |
|
| 84 |
.. _tut-handling: |
| 85 |
|
| 86 |
Handling Exceptions |
| 87 |
=================== |
| 88 |
|
| 89 |
It is possible to write programs that handle selected exceptions. Look at the |
| 90 |
following example, which asks the user for input until a valid integer has been |
| 91 |
entered, but allows the user to interrupt the program (using :kbd:`Control-C` or |
| 92 |
whatever the operating system supports); note that a user-generated interruption |
| 93 |
is signalled by raising the :exc:`KeyboardInterrupt` exception. :: |
| 94 |
|
| 95 |
>>> while True: |
| 96 |
... try: |
| 97 |
... x = int(input("Please enter a number: ")) |
| 98 |
... break |
| 99 |
... except ValueError: |
| 100 |
... print("Oops! That was no valid number. Try again...") |
| 101 |
... |
| 102 |
|
| 103 |
The :keyword:`try` statement works as follows. |
| 104 |
|
| 105 |
* First, the *try clause* (the statement(s) between the :keyword:`try` and |
| 106 |
:keyword:`except` keywords) is executed. |
| 107 |
|
| 108 |
* If no exception occurs, the *except clause* is skipped and execution of the |
| 109 |
:keyword:`try` statement is finished. |
| 110 |
|
| 111 |
* If an exception occurs during execution of the :keyword:`try` clause, the rest of the |
| 112 |
clause is skipped. Then, if its type matches the exception named after the |
| 113 |
:keyword:`except` keyword, the *except clause* is executed, and then execution |
| 114 |
continues after the try/except block. |
| 115 |
|
| 116 |
* If an exception occurs which does not match the exception named in the *except |
| 117 |
clause*, it is passed on to outer :keyword:`try` statements; if no handler is |
| 118 |
found, it is an *unhandled exception* and execution stops with an error message. |
| 119 |
|
| 120 |
A :keyword:`try` statement may have more than one *except clause*, to specify |
| 121 |
handlers for different exceptions. At most one handler will be executed. |
| 122 |
Handlers only handle exceptions that occur in the corresponding *try clause*, |
| 123 |
not in other handlers of the same :keyword:`!try` statement. An *except clause* |
| 124 |
may name multiple exceptions, for example:: |
| 125 |
|
| 126 |
... except RuntimeError, TypeError, NameError: |
| 127 |
... pass |
| 128 |
|
| 129 |
A class in an :keyword:`except` clause matches exceptions which are instances of the |
| 130 |
class itself or one of its derived classes (but not the other way around --- an |
| 131 |
*except clause* listing a derived class does not match instances of its base classes). |
| 132 |
For example, the following code will print B, C, D in that order:: |
| 133 |
|
| 134 |
class B(Exception): |
| 135 |
pass |
| 136 |
|
| 137 |
class C(B): |
| 138 |
pass |
| 139 |
|
| 140 |
class D(C): |
| 141 |
pass |
| 142 |
|
| 143 |
for cls in [B, C, D]: |
| 144 |
try: |
| 145 |
raise cls() |
| 146 |
except D: |
| 147 |
print("D") |
| 148 |
except C: |
| 149 |
print("C") |
| 150 |
except B: |
| 151 |
print("B") |
| 152 |
|
| 153 |
Note that if the *except clauses* were reversed (with ``except B`` first), it |
| 154 |
would have printed B, B, B --- the first matching *except clause* is triggered. |
| 155 |
|
| 156 |
When an exception occurs, it may have associated values, also known as the |
| 157 |
exception's *arguments*. The presence and types of the arguments depend on the |
| 158 |
exception type. |
| 159 |
|
| 160 |
The *except clause* may specify a variable after the exception name. The |
| 161 |
variable is bound to the exception instance which typically has an ``args`` |
| 162 |
attribute that stores the arguments. For convenience, builtin exception |
| 163 |
types define :meth:`~object.__str__` to print all the arguments without explicitly |
| 164 |
accessing ``.args``. :: |
| 165 |
|
| 166 |
>>> try: |
| 167 |
... raise Exception('spam', 'eggs') |
| 168 |
... except Exception as inst: |
| 169 |
... print(type(inst)) # the exception type |
| 170 |
... print(inst.args) # arguments stored in .args |
| 171 |
... print(inst) # __str__ allows args to be printed directly, |
| 172 |
... # but may be overridden in exception subclasses |
| 173 |
... x, y = inst.args # unpack args |
| 174 |
... print('x =', x) |
| 175 |
... print('y =', y) |
| 176 |
... |
| 177 |
<class 'Exception'> |
| 178 |
('spam', 'eggs') |
| 179 |
('spam', 'eggs') |
| 180 |
x = spam |
| 181 |
y = eggs |
| 182 |
|
| 183 |
The exception's :meth:`~object.__str__` output is printed as the last part ('detail') |
| 184 |
of the message for unhandled exceptions. |
| 185 |
|
| 186 |
:exc:`BaseException` is the common base class of all exceptions. One of its |
| 187 |
subclasses, :exc:`Exception`, is the base class of all the non-fatal exceptions. |
| 188 |
Exceptions which are not subclasses of :exc:`Exception` are not typically |
| 189 |
handled, because they are used to indicate that the program should terminate. |
| 190 |
They include :exc:`SystemExit` which is raised by :meth:`sys.exit` and |
| 191 |
:exc:`KeyboardInterrupt` which is raised when a user wishes to interrupt |
| 192 |
the program. |
| 193 |
|
| 194 |
:exc:`Exception` can be used as a wildcard that catches (almost) everything. |
| 195 |
However, it is good practice to be as specific as possible with the types |
| 196 |
of exceptions that we intend to handle, and to allow any unexpected |
| 197 |
exceptions to propagate on. |
| 198 |
|
| 199 |
The most common pattern for handling :exc:`Exception` is to print or log |
| 200 |
the exception and then re-raise it (allowing a caller to handle the |
| 201 |
exception as well):: |
| 202 |
|
| 203 |
import sys |
| 204 |
|
| 205 |
try: |
| 206 |
f = open('myfile.txt') |
| 207 |
s = f.readline() |
| 208 |
i = int(s.strip()) |
| 209 |
except OSError as err: |
| 210 |
print("OS error:", err) |
| 211 |
except ValueError: |
| 212 |
print("Could not convert data to an integer.") |
| 213 |
except Exception as err: |
| 214 |
print(f"Unexpected {err=}, {type(err)=}") |
| 215 |
raise |
| 216 |
|
| 217 |
The :keyword:`try` ... :keyword:`except` statement has an optional *else |
| 218 |
clause*, which, when present, must follow all *except clauses*. It is useful |
| 219 |
for code that must be executed if the *try clause* does not raise an exception. |
| 220 |
For example:: |
| 221 |
|
| 222 |
for arg in sys.argv[1:]: |
| 223 |
try: |
| 224 |
f = open(arg, 'r') |
| 225 |
except OSError: |
| 226 |
print('cannot open', arg) |
| 227 |
else: |
| 228 |
print(arg, 'has', len(f.readlines()), 'lines') |
| 229 |
f.close() |
| 230 |
|
| 231 |
The use of the :keyword:`!else` clause is better than adding additional code to |
| 232 |
the :keyword:`try` clause because it avoids accidentally catching an exception |
| 233 |
that wasn't raised by the code being protected by the :keyword:`!try` ... |
| 234 |
:keyword:`!except` statement. |
| 235 |
|
| 236 |
Exception handlers do not handle only exceptions that occur immediately in the |
| 237 |
*try clause*, but also those that occur inside functions that are called (even |
| 238 |
indirectly) in the *try clause*. For example:: |
| 239 |
|
| 240 |
>>> def this_fails(): |
| 241 |
... x = 1/0 |
| 242 |
... |
| 243 |
>>> try: |
| 244 |
... this_fails() |
| 245 |
... except ZeroDivisionError as err: |
| 246 |
... print('Handling run-time error:', err) |
| 247 |
... |
| 248 |
Handling run-time error: division by zero |
| 249 |
|
| 250 |
|
| 251 |
.. _tut-raising: |
| 252 |
|
| 253 |
Raising Exceptions |
| 254 |
================== |
| 255 |
|
| 256 |
The :keyword:`raise` statement allows the programmer to force a specified |
| 257 |
exception to occur. For example:: |
| 258 |
|
| 259 |
>>> raise NameError('HiThere') |
| 260 |
Traceback (most recent call last): |
| 261 |
File "<stdin>", line 1, in <module> |
| 262 |
raise NameError('HiThere') |
| 263 |
NameError: HiThere |
| 264 |
|
| 265 |
The sole argument to :keyword:`raise` indicates the exception to be raised. |
| 266 |
This must be either an exception instance or an exception class (a class that |
| 267 |
derives from :class:`BaseException`, such as :exc:`Exception` or one of its |
| 268 |
subclasses). If an exception class is passed, it will be implicitly |
| 269 |
instantiated by calling its constructor with no arguments:: |
| 270 |
|
| 271 |
raise ValueError # shorthand for 'raise ValueError()' |
| 272 |
|
| 273 |
If you need to determine whether an exception was raised but don't intend to |
| 274 |
handle it, a simpler form of the :keyword:`raise` statement allows you to |
| 275 |
re-raise the exception:: |
| 276 |
|
| 277 |
>>> try: |
| 278 |
... raise NameError('HiThere') |
| 279 |
... except NameError: |
| 280 |
... print('An exception flew by!') |
| 281 |
... raise |
| 282 |
... |
| 283 |
An exception flew by! |
| 284 |
Traceback (most recent call last): |
| 285 |
File "<stdin>", line 2, in <module> |
| 286 |
raise NameError('HiThere') |
| 287 |
NameError: HiThere |
| 288 |
|
| 289 |
|
| 290 |
.. _tut-exception-chaining: |
| 291 |
|
| 292 |
Exception Chaining |
| 293 |
================== |
| 294 |
|
| 295 |
If an unhandled exception occurs inside an :keyword:`except` section, it will |
| 296 |
have the exception being handled attached to it and included in the error |
| 297 |
message:: |
| 298 |
|
| 299 |
>>> try: |
| 300 |
... open("database.sqlite") |
| 301 |
... except OSError: |
| 302 |
... raise RuntimeError("unable to handle error") |
| 303 |
... |
| 304 |
Traceback (most recent call last): |
| 305 |
File "<stdin>", line 2, in <module> |
| 306 |
open("database.sqlite") |
| 307 |
~~~~^^^^^^^^^^^^^^^^^^^ |
| 308 |
FileNotFoundError: [Errno 2] No such file or directory: 'database.sqlite' |
| 309 |
<BLANKLINE> |
| 310 |
During handling of the above exception, another exception occurred: |
| 311 |
<BLANKLINE> |
| 312 |
Traceback (most recent call last): |
| 313 |
File "<stdin>", line 4, in <module> |
| 314 |
raise RuntimeError("unable to handle error") |
| 315 |
RuntimeError: unable to handle error |
| 316 |
|
| 317 |
To indicate that an exception is a direct consequence of another, the |
| 318 |
:keyword:`raise` statement allows an optional :keyword:`from<raise>` clause:: |
| 319 |
|
| 320 |
# exc must be exception instance or None. |
| 321 |
raise RuntimeError from exc |
| 322 |
|
| 323 |
This can be useful when you are transforming exceptions. For example:: |
| 324 |
|
| 325 |
>>> def func(): |
| 326 |
... raise ConnectionError |
| 327 |
... |
| 328 |
>>> try: |
| 329 |
... func() |
| 330 |
... except ConnectionError as exc: |
| 331 |
... raise RuntimeError('Failed to open database') from exc |
| 332 |
... |
| 333 |
Traceback (most recent call last): |
| 334 |
File "<stdin>", line 2, in <module> |
| 335 |
func() |
| 336 |
~~~~^^ |
| 337 |
File "<stdin>", line 2, in func |
| 338 |
ConnectionError |
| 339 |
<BLANKLINE> |
| 340 |
The above exception was the direct cause of the following exception: |
| 341 |
<BLANKLINE> |
| 342 |
Traceback (most recent call last): |
| 343 |
File "<stdin>", line 4, in <module> |
| 344 |
raise RuntimeError('Failed to open database') from exc |
| 345 |
RuntimeError: Failed to open database |
| 346 |
|
| 347 |
It also allows disabling automatic exception chaining using the ``from None`` |
| 348 |
idiom:: |
| 349 |
|
| 350 |
>>> try: |
| 351 |
... open('database.sqlite') |
| 352 |
... except OSError: |
| 353 |
... raise RuntimeError from None |
| 354 |
... |
| 355 |
Traceback (most recent call last): |
| 356 |
File "<stdin>", line 4, in <module> |
| 357 |
raise RuntimeError from None |
| 358 |
RuntimeError |
| 359 |
|
| 360 |
For more information about chaining mechanics, see :ref:`bltin-exceptions`. |
| 361 |
|
| 362 |
|
| 363 |
.. _tut-userexceptions: |
| 364 |
|
| 365 |
User-defined Exceptions |
| 366 |
======================= |
| 367 |
|
| 368 |
Programs may name their own exceptions by creating a new exception class (see |
| 369 |
:ref:`tut-classes` for more about Python classes). Exceptions should typically |
| 370 |
be derived from the :exc:`Exception` class, either directly or indirectly. |
| 371 |
|
| 372 |
Exception classes can be defined which do anything any other class can do, but |
| 373 |
are usually kept simple, often only offering a number of attributes that allow |
| 374 |
information about the error to be extracted by handlers for the exception. |
| 375 |
|
| 376 |
Most exceptions are defined with names that end in "Error", similar to the |
| 377 |
naming of the standard exceptions. |
| 378 |
|
| 379 |
Many standard modules define their own exceptions to report errors that may |
| 380 |
occur in functions they define. |
| 381 |
|
| 382 |
|
| 383 |
.. _tut-cleanup: |
| 384 |
|
| 385 |
Defining Clean-up Actions |
| 386 |
========================= |
| 387 |
|
| 388 |
The :keyword:`try` statement has another optional clause which is intended to |
| 389 |
define clean-up actions that must be executed under all circumstances. For |
| 390 |
example:: |
| 391 |
|
| 392 |
>>> try: |
| 393 |
... raise KeyboardInterrupt |
| 394 |
... finally: |
| 395 |
... print('Goodbye, world!') |
| 396 |
... |
| 397 |
Goodbye, world! |
| 398 |
Traceback (most recent call last): |
| 399 |
File "<stdin>", line 2, in <module> |
| 400 |
raise KeyboardInterrupt |
| 401 |
KeyboardInterrupt |
| 402 |
|
| 403 |
If a :keyword:`finally` clause is present, the :keyword:`!finally` |
| 404 |
clause will execute as the last task before the :keyword:`try` |
| 405 |
statement completes. The :keyword:`!finally` clause runs whether or |
| 406 |
not the :keyword:`!try` statement produces an exception. The following |
| 407 |
points discuss more complex cases when an exception occurs: |
| 408 |
|
| 409 |
* If an exception occurs during execution of the :keyword:`!try` |
| 410 |
clause, the exception may be handled by an :keyword:`except` |
| 411 |
clause. If the exception is not handled by an :keyword:`!except` |
| 412 |
clause, the exception is re-raised after the :keyword:`!finally` |
| 413 |
clause has been executed. |
| 414 |
|
| 415 |
* An exception could occur during execution of an :keyword:`!except` |
| 416 |
or :keyword:`!else` clause. Again, the exception is re-raised after |
| 417 |
the :keyword:`!finally` clause has been executed. |
| 418 |
|
| 419 |
* If the :keyword:`!finally` clause executes a :keyword:`break`, |
| 420 |
:keyword:`continue` or :keyword:`return` statement, exceptions are not |
| 421 |
re-raised. This can be confusing and is therefore discouraged. From |
| 422 |
version 3.14 the compiler emits a :exc:`SyntaxWarning` for it |
| 423 |
(see :pep:`765`). |
| 424 |
|
| 425 |
* If the :keyword:`!try` statement reaches a :keyword:`break`, |
| 426 |
:keyword:`continue` or :keyword:`return` statement, the |
| 427 |
:keyword:`!finally` clause will execute just prior to the |
| 428 |
:keyword:`!break`, :keyword:`!continue` or :keyword:`!return` |
| 429 |
statement's execution. |
| 430 |
|
| 431 |
* If a :keyword:`!finally` clause includes a :keyword:`!return` |
| 432 |
statement, the returned value will be the one from the |
| 433 |
:keyword:`!finally` clause's :keyword:`!return` statement, not the |
| 434 |
value from the :keyword:`!try` clause's :keyword:`!return` |
| 435 |
statement. This can be confusing and is therefore discouraged. From |
| 436 |
version 3.14 the compiler emits a :exc:`SyntaxWarning` for it |
| 437 |
(see :pep:`765`). |
| 438 |
|
| 439 |
For example:: |
| 440 |
|
| 441 |
>>> def bool_return(): |
| 442 |
... try: |
| 443 |
... return True |
| 444 |
... finally: |
| 445 |
... return False |
| 446 |
... |
| 447 |
>>> bool_return() |
| 448 |
False |
| 449 |
|
| 450 |
A more complicated example:: |
| 451 |
|
| 452 |
>>> def divide(x, y): |
| 453 |
... try: |
| 454 |
... result = x / y |
| 455 |
... except ZeroDivisionError: |
| 456 |
... print("division by zero!") |
| 457 |
... else: |
| 458 |
... print("result is", result) |
| 459 |
... finally: |
| 460 |
... print("executing finally clause") |
| 461 |
... |
| 462 |
>>> divide(2, 1) |
| 463 |
result is 2.0 |
| 464 |
executing finally clause |
| 465 |
>>> divide(2, 0) |
| 466 |
division by zero! |
| 467 |
executing finally clause |
| 468 |
>>> divide("2", "1") |
| 469 |
executing finally clause |
| 470 |
Traceback (most recent call last): |
| 471 |
File "<stdin>", line 1, in <module> |
| 472 |
divide("2", "1") |
| 473 |
~~~~~~^^^^^^^^^^ |
| 474 |
File "<stdin>", line 3, in divide |
| 475 |
result = x / y |
| 476 |
~~^~~ |
| 477 |
TypeError: unsupported operand type(s) for /: 'str' and 'str' |
| 478 |
|
| 479 |
As you can see, the :keyword:`finally` clause is executed in any event. The |
| 480 |
:exc:`TypeError` raised by dividing two strings is not handled by the |
| 481 |
:keyword:`except` clause and therefore re-raised after the :keyword:`!finally` |
| 482 |
clause has been executed. |
| 483 |
|
| 484 |
In real world applications, the :keyword:`finally` clause is useful for |
| 485 |
releasing external resources (such as files or network connections), regardless |
| 486 |
of whether the use of the resource was successful. |
| 487 |
|
| 488 |
|
| 489 |
.. _tut-cleanup-with: |
| 490 |
|
| 491 |
Predefined Clean-up Actions |
| 492 |
=========================== |
| 493 |
|
| 494 |
Some objects define standard clean-up actions to be undertaken when the object |
| 495 |
is no longer needed, regardless of whether or not the operation using the object |
| 496 |
succeeded or failed. Look at the following example, which tries to open a file |
| 497 |
and print its contents to the screen. :: |
| 498 |
|
| 499 |
for line in open("myfile.txt"): |
| 500 |
print(line, end="") |
| 501 |
|
| 502 |
The problem with this code is that it leaves the file open for an indeterminate |
| 503 |
amount of time after this part of the code has finished executing. |
| 504 |
This is not an issue in simple scripts, but can be a problem for larger |
| 505 |
applications. The :keyword:`with` statement allows objects like files to be |
| 506 |
used in a way that ensures they are always cleaned up promptly and correctly. :: |
| 507 |
|
| 508 |
with open("myfile.txt") as f: |
| 509 |
for line in f: |
| 510 |
print(line, end="") |
| 511 |
|
| 512 |
After the statement is executed, the file *f* is always closed, even if a |
| 513 |
problem was encountered while processing the lines. Objects which, like files, |
| 514 |
provide predefined clean-up actions will indicate this in their documentation. |
| 515 |
|
| 516 |
|
| 517 |
.. _tut-exception-groups: |
| 518 |
|
| 519 |
Raising and Handling Multiple Unrelated Exceptions |
| 520 |
================================================== |
| 521 |
|
| 522 |
There are situations where it is necessary to report several exceptions that |
| 523 |
have occurred. This is often the case in concurrency frameworks, when several |
| 524 |
tasks may have failed in parallel, but there are also other use cases where |
| 525 |
it is desirable to continue execution and collect multiple errors rather than |
| 526 |
raise the first exception. |
| 527 |
|
| 528 |
The builtin :exc:`ExceptionGroup` wraps a list of exception instances so |
| 529 |
that they can be raised together. It is an exception itself, so it can be |
| 530 |
caught like any other exception. :: |
| 531 |
|
| 532 |
>>> def f(): |
| 533 |
... excs = [OSError('error 1'), SystemError('error 2')] |
| 534 |
... raise ExceptionGroup('there were problems', excs) |
| 535 |
... |
| 536 |
>>> f() |
| 537 |
+ Exception Group Traceback (most recent call last): |
| 538 |
| File "<stdin>", line 1, in <module> |
| 539 |
| f() |
| 540 |
| ~^^ |
| 541 |
| File "<stdin>", line 3, in f |
| 542 |
| raise ExceptionGroup('there were problems', excs) |
| 543 |
| ExceptionGroup: there were problems (2 sub-exceptions) |
| 544 |
+-+---------------- 1 ---------------- |
| 545 |
| OSError: error 1 |
| 546 |
+---------------- 2 ---------------- |
| 547 |
| SystemError: error 2 |
| 548 |
+------------------------------------ |
| 549 |
>>> try: |
| 550 |
... f() |
| 551 |
... except Exception as e: |
| 552 |
... print(f'caught {type(e)}: {e}') |
| 553 |
... |
| 554 |
caught <class 'ExceptionGroup'>: there were problems (2 sub-exceptions) |
| 555 |
>>> |
| 556 |
|
| 557 |
By using ``except*`` instead of ``except``, we can selectively |
| 558 |
handle only the exceptions in the group that match a certain |
| 559 |
type. In the following example, which shows a nested exception |
| 560 |
group, each ``except*`` clause extracts from the group exceptions |
| 561 |
of a certain type while letting all other exceptions propagate to |
| 562 |
other clauses and eventually to be reraised. :: |
| 563 |
|
| 564 |
>>> def f(): |
| 565 |
... raise ExceptionGroup( |
| 566 |
... "group1", |
| 567 |
... [ |
| 568 |
... OSError(1), |
| 569 |
... SystemError(2), |
| 570 |
... ExceptionGroup( |
| 571 |
... "group2", |
| 572 |
... [ |
| 573 |
... OSError(3), |
| 574 |
... RecursionError(4) |
| 575 |
... ] |
| 576 |
... ) |
| 577 |
... ] |
| 578 |
... ) |
| 579 |
... |
| 580 |
>>> try: |
| 581 |
... f() |
| 582 |
... except* OSError as e: |
| 583 |
... print("There were OSErrors") |
| 584 |
... except* SystemError as e: |
| 585 |
... print("There were SystemErrors") |
| 586 |
... |
| 587 |
There were OSErrors |
| 588 |
There were SystemErrors |
| 589 |
+ Exception Group Traceback (most recent call last): |
| 590 |
| File "<stdin>", line 2, in <module> |
| 591 |
| f() |
| 592 |
| ~^^ |
| 593 |
| File "<stdin>", line 2, in f |
| 594 |
| raise ExceptionGroup( |
| 595 |
| ...<12 lines>... |
| 596 |
| ) |
| 597 |
| ExceptionGroup: group1 (1 sub-exception) |
| 598 |
+-+---------------- 1 ---------------- |
| 599 |
| ExceptionGroup: group2 (1 sub-exception) |
| 600 |
+-+---------------- 1 ---------------- |
| 601 |
| RecursionError: 4 |
| 602 |
+------------------------------------ |
| 603 |
>>> |
| 604 |
|
| 605 |
Note that the exceptions nested in an exception group must be instances, |
| 606 |
not types. This is because in practice the exceptions would typically |
| 607 |
be ones that have already been raised and caught by the program, along |
| 608 |
the following pattern:: |
| 609 |
|
| 610 |
>>> excs = [] |
| 611 |
... for test in tests: |
| 612 |
... try: |
| 613 |
... test.run() |
| 614 |
... except Exception as e: |
| 615 |
... excs.append(e) |
| 616 |
... |
| 617 |
>>> if excs: |
| 618 |
... raise ExceptionGroup("Test Failures", excs) |
| 619 |
... |
| 620 |
|
| 621 |
|
| 622 |
.. _tut-exception-notes: |
| 623 |
|
| 624 |
Enriching Exceptions with Notes |
| 625 |
=============================== |
| 626 |
|
| 627 |
When an exception is created in order to be raised, it is usually initialized |
| 628 |
with information that describes the error that has occurred. There are cases |
| 629 |
where it is useful to add information after the exception was caught. For this |
| 630 |
purpose, exceptions have a method ``add_note(note)`` that accepts a string and |
| 631 |
adds it to the exception's notes list. The standard traceback rendering |
| 632 |
includes all notes, in the order they were added, after the exception. :: |
| 633 |
|
| 634 |
>>> try: |
| 635 |
... raise TypeError('bad type') |
| 636 |
... except Exception as e: |
| 637 |
... e.add_note('Add some information') |
| 638 |
... e.add_note('Add some more information') |
| 639 |
... raise |
| 640 |
... |
| 641 |
Traceback (most recent call last): |
| 642 |
File "<stdin>", line 2, in <module> |
| 643 |
raise TypeError('bad type') |
| 644 |
TypeError: bad type |
| 645 |
Add some information |
| 646 |
Add some more information |
| 647 |
>>> |
| 648 |
|
| 649 |
For example, when collecting exceptions into an exception group, we may want |
| 650 |
to add context information for the individual errors. In the following each |
| 651 |
exception in the group has a note indicating when this error has occurred. :: |
| 652 |
|
| 653 |
>>> def f(): |
| 654 |
... raise OSError('operation failed') |
| 655 |
... |
| 656 |
>>> excs = [] |
| 657 |
>>> for i in range(3): |
| 658 |
... try: |
| 659 |
... f() |
| 660 |
... except Exception as e: |
| 661 |
... e.add_note(f'Happened in Iteration {i+1}') |
| 662 |
... excs.append(e) |
| 663 |
... |
| 664 |
>>> raise ExceptionGroup('We have some problems', excs) |
| 665 |
+ Exception Group Traceback (most recent call last): |
| 666 |
| File "<stdin>", line 1, in <module> |
| 667 |
| raise ExceptionGroup('We have some problems', excs) |
| 668 |
| ExceptionGroup: We have some problems (3 sub-exceptions) |
| 669 |
+-+---------------- 1 ---------------- |
| 670 |
| Traceback (most recent call last): |
| 671 |
| File "<stdin>", line 3, in <module> |
| 672 |
| f() |
| 673 |
| ~^^ |
| 674 |
| File "<stdin>", line 2, in f |
| 675 |
| raise OSError('operation failed') |
| 676 |
| OSError: operation failed |
| 677 |
| Happened in Iteration 1 |
| 678 |
+---------------- 2 ---------------- |
| 679 |
| Traceback (most recent call last): |
| 680 |
| File "<stdin>", line 3, in <module> |
| 681 |
| f() |
| 682 |
| ~^^ |
| 683 |
| File "<stdin>", line 2, in f |
| 684 |
| raise OSError('operation failed') |
| 685 |
| OSError: operation failed |
| 686 |
| Happened in Iteration 2 |
| 687 |
+---------------- 3 ---------------- |
| 688 |
| Traceback (most recent call last): |
| 689 |
| File "<stdin>", line 3, in <module> |
| 690 |
| f() |
| 691 |
| ~^^ |
| 692 |
| File "<stdin>", line 2, in f |
| 693 |
| raise OSError('operation failed') |
| 694 |
| OSError: operation failed |
| 695 |
| Happened in Iteration 3 |
| 696 |
+------------------------------------ |
| 697 |
>>> |