cpython-lru_cache-weakref: Doc/tutorial/errors.rst annotate

annotate Doc/tutorial/errors.rst @ 54132:d2732ea99ba0

#4144: fix output of console sessions.

author	Georg Brandl <georg@python.org>
date	Sun, 17 May 2009 08:14:39 +0000
parents	93cf3a6ead63
children	fa91270b6087

rev	line source
48667 949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	1 .. _tut-errors:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 *********************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 Errors and Exceptions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 *********************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 Until now error messages haven't been more than mentioned, but if you have tried
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 out the examples you have probably seen some. There are (at least) two
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9 distinguishable kinds of errors: syntax errors and exceptions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 .. _tut-syntaxerrors:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 Syntax Errors
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 =============
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 Syntax errors, also known as parsing errors, are perhaps the most common kind of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 complaint you get while you are still learning Python::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	20 >>> while True print('Hello world')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 File "<stdin>", line 1, in ?
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	22 while True print('Hello world')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 ^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 SyntaxError: invalid syntax
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 The parser repeats the offending line and displays a little 'arrow' pointing at
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 the earliest point in the line where the error was detected. The error is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 caused by (or at least detected at) the token preceding the arrow: in the
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43115 diff changeset	29 example, the error is detected at the function :func:`print`, since a colon
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 (``':'``) is missing before it. File name and line number are printed so you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 know where to look in case the input came from a script.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 .. _tut-exceptions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 Exceptions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 ==========
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 Even if a statement or expression is syntactically correct, it may cause an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 error when an attempt is made to execute it. Errors detected during execution
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 are called exceptions and are not unconditionally fatal: you will soon learn
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 how to handle them in Python programs. Most exceptions are not handled by
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 programs, however, and result in error messages as shown here::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 >>> 10 * (1/0)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 File "<stdin>", line 1, in ?
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	48 ZeroDivisionError: int division or modulo by zero
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 >>> 4 + spam*3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 NameError: name 'spam' is not defined
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 >>> '2' + 2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 File "<stdin>", line 1, in ?
54132 d2732ea99ba0 #4144: fix output of console sessions. Georg Brandl <georg@python.org> parents: 50563 diff changeset	56 TypeError: Can't convert 'int' object to str implicitly
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 The last line of the error message indicates what happened. Exceptions come in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 different types, and the type is printed as part of the message: the types in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 the example are :exc:`ZeroDivisionError`, :exc:`NameError` and :exc:`TypeError`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 The string printed as the exception type is the name of the built-in exception
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 that occurred. This is true for all built-in exceptions, but need not be true
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 for user-defined exceptions (although it is a useful convention). Standard
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 exception names are built-in identifiers (not reserved keywords).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 The rest of the line provides detail based on the type of exception and what
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 caused it.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 The preceding part of the error message shows the context where the exception
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 happened, in the form of a stack traceback. In general it contains a stack
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 traceback listing source lines; however, it will not display lines read from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 standard input.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 :ref:`bltin-exceptions` lists the built-in exceptions and their meanings.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 .. _tut-handling:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 Handling Exceptions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 ===================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 It is possible to write programs that handle selected exceptions. Look at the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83 following example, which asks the user for input until a valid integer has been
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 entered, but allows the user to interrupt the program (using :kbd:`Control-C` or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 whatever the operating system supports); note that a user-generated interruption
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 is signalled by raising the :exc:`KeyboardInterrupt` exception. ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 >>> while True:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 ... try:
42642 9fc21c8babb9 No need to define raw_input(), input() does the same. Georg Brandl <georg@python.org> parents: 42604 diff changeset	90 ... x = int(input("Please enter a number: "))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 ... break
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 ... except ValueError:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	93 ... print("Oops! That was no valid number. Try again...")
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49215 diff changeset	94 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 The :keyword:`try` statement works as follows.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 * First, the try clause (the statement(s) between the :keyword:`try` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 :keyword:`except` keywords) is executed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 * If no exception occurs, the except clause is skipped and execution of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 :keyword:`try` statement is finished.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 * If an exception occurs during execution of the try clause, the rest of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 clause is skipped. Then if its type matches the exception named after the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 :keyword:`except` keyword, the except clause is executed, and then execution
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 continues after the :keyword:`try` statement.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 * If an exception occurs which does not match the exception named in the except
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 clause, it is passed on to outer :keyword:`try` statements; if no handler is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 found, it is an unhandled exception and execution stops with a message as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 shown above.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 A :keyword:`try` statement may have more than one except clause, to specify
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 handlers for different exceptions. At most one handler will be executed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 Handlers only handle exceptions that occur in the corresponding try clause, not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 in other handlers of the same :keyword:`try` statement. An except clause may
43447 0ff46ef946b1 Revert r58075 (incorrect docs patch). Collin Winter <collinw@gmail.com> parents: 43309 diff changeset	118 name multiple exceptions as a parenthesized tuple, for example::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
43447 0ff46ef946b1 Revert r58075 (incorrect docs patch). Collin Winter <collinw@gmail.com> parents: 43309 diff changeset	120 ... except (RuntimeError, TypeError, NameError):
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 ... pass
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 The last except clause may omit the exception name(s), to serve as a wildcard.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 Use this with extreme caution, since it is easy to mask a real programming error
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125 in this way! It can also be used to print an error message and then re-raise
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 the exception (allowing a caller to handle the exception as well)::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 import sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 try:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131 f = open('myfile.txt')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 s = f.readline()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 i = int(s.strip())
48667 949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	134 except IOError as err:
949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	135 print("I/O error: {0}".format(err))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 except ValueError:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	137 print("Could not convert data to an integer.")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 except:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	139 print("Unexpected error:", sys.exc_info()[0])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 raise
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 The :keyword:`try` ... :keyword:`except` statement has an optional *else
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 clause*, which, when present, must follow all except clauses. It is useful for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 code that must be executed if the try clause does not raise an exception. For
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147 for arg in sys.argv[1:]:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148 try:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 f = open(arg, 'r')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 except IOError:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	151 print('cannot open', arg)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 else:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	153 print(arg, 'has', len(f.readlines()), 'lines')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 f.close()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156 The use of the :keyword:`else` clause is better than adding additional code to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 the :keyword:`try` clause because it avoids accidentally catching an exception
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 that wasn't raised by the code being protected by the :keyword:`try` ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 :keyword:`except` statement.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 When an exception occurs, it may have an associated value, also known as the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 exception's argument. The presence and type of the argument depend on the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163 exception type.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164
48667 949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	165 The except clause may specify a variable after the exception name. The
949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	166 variable is bound to an exception instance with the arguments stored in
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 ``instance.args``. For convenience, the exception instance defines
48667 949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	168 :meth:`__str__` so the arguments can be printed directly without having to
949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	169 reference ``.args``. One may also instantiate an exception first before
949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	170 raising it and add any attributes to it as desired. ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172 >>> try:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173 ... raise Exception('spam', 'eggs')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 ... except Exception as inst:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	175 ... print(type(inst)) # the exception instance
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	176 ... print(inst.args) # arguments stored in .args
48667 949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	177 ... print(inst) # __str__ allows args to be printed directly,
949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	178 ... # but may be overridden in exception subclasses
949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	179 ... x, y = inst.args # unpack args
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43115 diff changeset	180 ... print('x =', x)
655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43115 diff changeset	181 ... print('y =', y)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182 ...
46336 56e49952d1a4 Bug #2565: The repr() of type objects now calls them 'class', Martin v. Löwis <martin@v.loewis.de> parents: 45056 diff changeset	183 <class 'Exception'>
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 ('spam', 'eggs')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 ('spam', 'eggs')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 x = spam
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187 y = eggs
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188
48667 949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	189 If an exception has arguments, they are printed as the last part ('detail') of
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190 the message for unhandled exceptions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 Exception handlers don't just handle exceptions if they occur immediately in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193 try clause, but also if they occur inside functions that are called (even
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194 indirectly) in the try clause. For example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 >>> def this_fails():
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 ... x = 1/0
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49215 diff changeset	198 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 >>> try:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 ... this_fails()
48667 949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	201 ... except ZeroDivisionError as err:
949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	202 ... print('Handling run-time error:', err)
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49215 diff changeset	203 ...
48667 949b9a2b9867 #3525: 3.0 exception changes in tutorial. Georg Brandl <georg@python.org> parents: 47283 diff changeset	204 Handling run-time error: int division or modulo by zero
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 .. _tut-raising:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 Raising Exceptions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 ==================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 The :keyword:`raise` statement allows the programmer to force a specified
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 exception to occur. For example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214
43306 9f7f3147031c Fix more two-arg raise statements. Collin Winter <collinw@gmail.com> parents: 43219 diff changeset	215 >>> raise NameError('HiThere')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 NameError: HiThere
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219
43308 b27d349162bd More two-argument raise cleanup in the tutorial. Collin Winter <collinw@gmail.com> parents: 43307 diff changeset	220 The sole argument to :keyword:`raise` indicates the exception to be raised.
b27d349162bd More two-argument raise cleanup in the tutorial. Collin Winter <collinw@gmail.com> parents: 43307 diff changeset	221 This must be either an exception instance or an exception class (a class that
b27d349162bd More two-argument raise cleanup in the tutorial. Collin Winter <collinw@gmail.com> parents: 43307 diff changeset	222 derives from :class:`Exception`).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 If you need to determine whether an exception was raised but don't intend to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 handle it, a simpler form of the :keyword:`raise` statement allows you to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 re-raise the exception::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 >>> try:
43306 9f7f3147031c Fix more two-arg raise statements. Collin Winter <collinw@gmail.com> parents: 43219 diff changeset	229 ... raise NameError('HiThere')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 ... except NameError:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	231 ... print('An exception flew by!')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 ... raise
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 An exception flew by!
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 File "<stdin>", line 2, in ?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 NameError: HiThere
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 .. _tut-userexceptions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 User-defined Exceptions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 =======================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 Programs may name their own exceptions by creating a new exception class.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 Exceptions should typically be derived from the :exc:`Exception` class, either
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 directly or indirectly. For example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 >>> class MyError(Exception):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 ... def __init__(self, value):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 ... self.value = value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252 ... def __str__(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253 ... return repr(self.value)
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49215 diff changeset	254 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255 >>> try:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 ... raise MyError(2*2)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 ... except MyError as e:
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43115 diff changeset	258 ... print('My exception occurred, value:', e.value)
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49215 diff changeset	259 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 My exception occurred, value: 4
43309 09287f2055ab Fix more raise statments in the docs. Collin Winter <collinw@gmail.com> parents: 43308 diff changeset	261 >>> raise MyError('oops!')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 __main__.MyError: 'oops!'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 In this example, the default :meth:`__init__` of :class:`Exception` has been
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267 overridden. The new behavior simply creates the value attribute. This
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268 replaces the default behavior of creating the args attribute.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270 Exception classes can be defined which do anything any other class can do, but
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271 are usually kept simple, often only offering a number of attributes that allow
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272 information about the error to be extracted by handlers for the exception. When
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 creating a module that can raise several distinct errors, a common practice is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 to create a base class for exceptions defined by that module, and subclass that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275 to create specific exception classes for different error conditions::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 class Error(Exception):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 """Base class for exceptions in this module."""
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 pass
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 class InputError(Error):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282 """Exception raised for errors in the input.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 Attributes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285 expression -- input expression in which the error occurred
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 message -- explanation of the error
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 """
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 def __init__(self, expression, message):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290 self.expression = expression
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 self.message = message
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 class TransitionError(Error):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 """Raised when an operation attempts a state transition that's not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295 allowed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297 Attributes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298 previous -- state at beginning of transition
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 next -- attempted new state
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300 message -- explanation of why the specific transition is not allowed
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301 """
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303 def __init__(self, previous, next, message):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 self.previous = previous
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305 self.next = next
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306 self.message = message
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308 Most exceptions are defined with names that end in "Error," similar to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 naming of the standard exceptions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 Many standard modules define their own exceptions to report errors that may
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 occur in functions they define. More information on classes is presented in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 chapter :ref:`tut-classes`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316 .. _tut-cleanup:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 Defining Clean-up Actions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 =========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 The :keyword:`try` statement has another optional clause which is intended to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 define clean-up actions that must be executed under all circumstances. For
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323 example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 >>> try:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 ... raise KeyboardInterrupt
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327 ... finally:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	328 ... print('Goodbye, world!')
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49215 diff changeset	329 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330 Goodbye, world!
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332 File "<stdin>", line 2, in ?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 KeyboardInterrupt
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 A finally clause is always executed before leaving the :keyword:`try`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 statement, whether an exception has occurred or not. When an exception has
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337 occurred in the :keyword:`try` clause and has not been handled by an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 :keyword:`except` clause (or it has occurred in a :keyword:`except` or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339 :keyword:`else` clause), it is re-raised after the :keyword:`finally` clause has
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340 been executed. The :keyword:`finally` clause is also executed "on the way out"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 when any other clause of the :keyword:`try` statement is left via a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 :keyword:`break`, :keyword:`continue` or :keyword:`return` statement. A more
46963 03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 46336 diff changeset	343 complicated example::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 >>> def divide(x, y):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346 ... try:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 ... result = x / y
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348 ... except ZeroDivisionError:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	349 ... print("division by zero!")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350 ... else:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	351 ... print("result is", result)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352 ... finally:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	353 ... print("executing finally clause")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 >>> divide(2, 1)
54132 d2732ea99ba0 #4144: fix output of console sessions. Georg Brandl <georg@python.org> parents: 50563 diff changeset	356 result is 2.0
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 executing finally clause
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 >>> divide(2, 0)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359 division by zero!
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 executing finally clause
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361 >>> divide("2", "1")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362 executing finally clause
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 File "<stdin>", line 3, in divide
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 TypeError: unsupported operand type(s) for /: 'str' and 'str'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 As you can see, the :keyword:`finally` clause is executed in any event. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369 :exc:`TypeError` raised by dividing two strings is not handled by the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370 :keyword:`except` clause and therefore re-raised after the :keyword:`finally`
49215 30ef22a80267 Merged revisions 66457-66459,66465-66468,66483-66485,66487-66491 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48667 diff changeset	371 clause has been executed.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 In real world applications, the :keyword:`finally` clause is useful for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374 releasing external resources (such as files or network connections), regardless
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 of whether the use of the resource was successful.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 .. _tut-cleanup-with:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380 Predefined Clean-up Actions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 ===========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 Some objects define standard clean-up actions to be undertaken when the object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 is no longer needed, regardless of whether or not the operation using the object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385 succeeded or failed. Look at the following example, which tries to open a file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386 and print its contents to the screen. ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 for line in open("myfile.txt"):
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	389 print(line)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391 The problem with this code is that it leaves the file open for an indeterminate
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49215 diff changeset	392 amount of time after this part of the code has finished executing.
93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49215 diff changeset	393 This is not an issue in simple scripts, but can be a problem for larger
93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49215 diff changeset	394 applications. The :keyword:`with` statement allows objects like files to be
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	395 used in a way that ensures they are always cleaned up promptly and correctly. ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 with open("myfile.txt") as f:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398 for line in f:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	399 print(line)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401 After the statement is executed, the file f is always closed, even if a
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	402 problem was encountered while processing the lines. Objects which, like files,
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42642 diff changeset	403 provide predefined clean-up actions will indicate this in their documentation.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405

Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/errors.rst @ 54132:d2732ea99ba0