From 6464d558fd80a714643de42270e32881d5bb4b17 Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Wed, 18 Sep 2019 19:33:33 -0300 Subject: [PATCH 1/7] Improvements in how try clause works section --- Doc/tutorial/errors.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index 75a49259d44022..b0173b93580dda 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -101,10 +101,10 @@ The :keyword:`try` statement works as follows. * If no exception occurs, the *except clause* is skipped and execution of the :keyword:`try` statement is finished. -* If an exception occurs during execution of the try clause, the rest of the +* If an exception occurs during execution of the *try clause*, the rest of the clause is skipped. Then if its type matches the exception named after the - :keyword:`except` keyword, the except clause is executed, and then execution - continues after the :keyword:`try` statement. + :keyword:`except` keyword, the *except clause* is executed, and then execution + continues after the *try/except* block. * If an exception occurs which does not match the exception named in the except clause, it is passed on to outer :keyword:`try` statements; if no handler is From 240b622fcb4a7205f8c59f81ebe0e37a70e08133 Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Wed, 18 Sep 2019 19:57:00 -0300 Subject: [PATCH 2/7] Surrounding some keywords with *...* Review all try/except/raise/finally and surrounding those without any mark (like :keyword:) with *...*. --- Doc/tutorial/errors.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index b0173b93580dda..7d6d910779ef3d 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -106,24 +106,24 @@ The :keyword:`try` statement works as follows. :keyword:`except` keyword, the *except clause* is executed, and then execution continues after the *try/except* block. -* If an exception occurs which does not match the exception named in the except - clause, it is passed on to outer :keyword:`try` statements; if no handler is +* If an exception occurs which does not match the exception named in the *except + clause*, it is passed on to outer :keyword:`try` statements; if no handler is found, it is an *unhandled exception* and execution stops with a message as shown above. -A :keyword:`try` statement may have more than one except clause, to specify +A :keyword:`try` statement may have more than one *except clause*, to specify handlers for different exceptions. At most one handler will be executed. -Handlers only handle exceptions that occur in the corresponding try clause, not -in other handlers of the same :keyword:`!try` statement. An except clause may -name multiple exceptions as a parenthesized tuple, for example:: +Handlers only handle exceptions that occur in the corresponding *try clause*, +not in other handlers of the same :keyword:`!try` statement. An *except clause* +may name multiple exceptions as a parenthesized tuple, for example:: ... except (RuntimeError, TypeError, NameError): ... pass A class in an :keyword:`except` clause is compatible with an exception if it is the same class or a base class thereof (but not the other way around --- an -except clause listing a derived class is not compatible with a base class). For -example, the following code will print B, C, D in that order:: +*except clause* listing a derived class is not compatible with a base class). +For example, the following code will print B, C, D in that order:: class B(Exception): pass @@ -144,10 +144,10 @@ example, the following code will print B, C, D in that order:: except B: print("B") -Note that if the except clauses were reversed (with ``except B`` first), it -would have printed B, B, B --- the first matching except clause is triggered. +Note that if the *except clauses* were reversed (with ``except B`` first), it +would have printed B, B, B --- the first matching *except clause* is triggered. -The last except clause may omit the exception name(s), to serve as a wildcard. +The last *except clause* may omit the exception name(s), to serve as a wildcard. Use this with extreme caution, since it is easy to mask a real programming error in this way! It can also be used to print an error message and then re-raise the exception (allowing a caller to handle the exception as well):: @@ -167,9 +167,9 @@ the exception (allowing a caller to handle the exception as well):: raise The :keyword:`try` ... :keyword:`except` statement has an optional *else -clause*, which, when present, must follow all except clauses. It is useful for -code that must be executed if the try clause does not raise an exception. For -example:: +clause*, which, when present, must follow all *except clauses*. It is useful +for code that must be executed if the *try clause* does not raise an exception. +For example:: for arg in sys.argv[1:]: try: @@ -189,7 +189,7 @@ When an exception occurs, it may have an associated value, also known as the exception's *argument*. The presence and type of the argument depend on the exception type. -The except clause may specify a variable after the exception name. The +The *except clause* may specify a variable after the exception name. The variable is bound to an exception instance with the arguments stored in ``instance.args``. For convenience, the exception instance defines :meth:`__str__` so the arguments can be printed directly without having to @@ -217,8 +217,8 @@ If an exception has arguments, they are printed as the last part ('detail') of the message for unhandled exceptions. Exception handlers don't just handle exceptions if they occur immediately in the -try clause, but also if they occur inside functions that are called (even -indirectly) in the try clause. For example:: +*try clause*, but also if they occur inside functions that are called (even +indirectly) in the *try clause*. For example:: >>> def this_fails(): ... x = 1/0 From 692036c8d2049e3f4084c30520a30c6a1c4dc07b Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Wed, 18 Sep 2019 20:05:51 -0300 Subject: [PATCH 3/7] Doc: adjust the number of chars per line to 80 --- Doc/tutorial/errors.rst | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index 7d6d910779ef3d..37864e9a29ba48 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -388,15 +388,28 @@ example:: File "", line 2, in KeyboardInterrupt -If a :keyword:`finally` clause is present, the :keyword:`finally` clause will execute as the last task before the :keyword:`try` statement completes. The :keyword:`finally` clause runs whether or not the :keyword:`try` statement produces an exception. The following points discuss more complex cases when an exception occurs: - -* If an exception occurs during execution of the :keyword:`!try` clause, the exception may be handled by an :keyword:`except` clause. In all cases, the exception is re-raised after the :keyword:`!finally` clause has been executed. - -* An exception could occur during execution of an :keyword:`!except` or :keyword:`!else` clause. Again, the exception is re-raised after the :keyword:`!finally` clause has been executed. - -* If the :keyword:`!try` statement reaches a :keyword:`break`, :keyword:`continue` or :keyword:`return` statement, the :keyword:`finally` clause will execute just prior to the :keyword:`break`, :keyword:`continue` or :keyword:`return` statement's execution. - -* If a :keyword:`finally` clause includes a :keyword:`return` statement, the :keyword:`finally` clause's :keyword:`return` statement will execute before, and instead of, the :keyword:`return` statement in a :keyword:`try` clause. +If a :keyword:`finally` clause is present, the :keyword:`finally` clause will +execute as the last task before the :keyword:`try` statement completes. The +:keyword:`finally` clause runs whether or not the :keyword:`try` statement +produces an exception. The following points discuss more complex cases when an +exception occurs: + +* If an exception occurs during execution of the :keyword:`!try` clause, the + exception may be handled by an :keyword:`except` clause. In all cases, the + exception is re-raised after the :keyword:`!finally` clause has been executed. + +* An exception could occur during execution of an :keyword:`!except` or + :keyword:`!else` clause. Again, the exception is re-raised after the + :keyword:`!finally` clause has been executed. + +* If the :keyword:`!try` statement reaches a :keyword:`break`, + :keyword:`continue` or :keyword:`return` statement, the :keyword:`finally` + clause will execute just prior to the :keyword:`break`, :keyword:`continue` + or :keyword:`return` statement's execution. + +* If a :keyword:`finally` clause includes a :keyword:`return` statement, the + :keyword:`finally` clause's :keyword:`return` statement will execute before, + and instead of, the :keyword:`return` statement in a :keyword:`try` clause. For example:: From 442d31679c19a40d73aedc629ece743be6b074ee Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Thu, 19 Sep 2019 22:11:16 -0300 Subject: [PATCH 4/7] Update Doc/tutorial/errors.rst Co-Authored-By: Kyle Stanley --- Doc/tutorial/errors.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index 37864e9a29ba48..613b994d96637e 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -101,7 +101,7 @@ The :keyword:`try` statement works as follows. * If no exception occurs, the *except clause* is skipped and execution of the :keyword:`try` statement is finished. -* If an exception occurs during execution of the *try clause*, the rest of the +* If an exception occurs during execution of the :keyword:`try` clause, the rest of the clause is skipped. Then if its type matches the exception named after the :keyword:`except` keyword, the *except clause* is executed, and then execution continues after the *try/except* block. From ec6d09739ff080e429b0127ff16868148dc104c5 Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Thu, 19 Sep 2019 22:11:52 -0300 Subject: [PATCH 5/7] Update Doc/tutorial/errors.rst Co-Authored-By: Kyle Stanley --- Doc/tutorial/errors.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index 613b994d96637e..318b9b77c2b662 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -102,7 +102,7 @@ The :keyword:`try` statement works as follows. :keyword:`try` statement is finished. * If an exception occurs during execution of the :keyword:`try` clause, the rest of the - clause is skipped. Then if its type matches the exception named after the + clause is skipped. Then, if its type matches the exception named after the :keyword:`except` keyword, the *except clause* is executed, and then execution continues after the *try/except* block. From 84fb2aacc7e1c5bf8911c8a317d3a7792adac3d3 Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Thu, 19 Sep 2019 22:12:04 -0300 Subject: [PATCH 6/7] Update Doc/tutorial/errors.rst Co-Authored-By: Kyle Stanley --- Doc/tutorial/errors.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index 318b9b77c2b662..e4ae4bb1e3a27c 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -104,7 +104,7 @@ The :keyword:`try` statement works as follows. * If an exception occurs during execution of the :keyword:`try` clause, the rest of the clause is skipped. Then, if its type matches the exception named after the :keyword:`except` keyword, the *except clause* is executed, and then execution - continues after the *try/except* block. + continues after the try/except block. * If an exception occurs which does not match the exception named in the *except clause*, it is passed on to outer :keyword:`try` statements; if no handler is From 0dc43dc9b7b98588e48d5840b0e9623597807c74 Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Thu, 19 Sep 2019 22:30:14 -0300 Subject: [PATCH 7/7] Update Doc/tutorial/errors.rst Co-Authored-By: Kyle Stanley --- Doc/tutorial/errors.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index e4ae4bb1e3a27c..c69d022b921592 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -102,7 +102,7 @@ The :keyword:`try` statement works as follows. :keyword:`try` statement is finished. * If an exception occurs during execution of the :keyword:`try` clause, the rest of the - clause is skipped. Then, if its type matches the exception named after the + clause is skipped. Then, if its type matches the exception named after the :keyword:`except` keyword, the *except clause* is executed, and then execution continues after the try/except block.