Debian Codegraph @

Doc/tutorial/errors.rst

raw
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 >>>