From 4fee86bd914f7705684a583f2cfa3e6fcb703230 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Sun, 2 Oct 2022 00:12:56 -0500 Subject: [PATCH] gh-95975: Move except/*/finally ref labels to more precise locations (GH-95976) * gh-95975: Move except/*/finally ref labels to more precise locations * Add section headers to fix :keyword: role and aid navigation * Move see also to the introduction rather than a particular subsection * Fix other minor Sphinx syntax issues with except Co-authored-by: Ezio Melotti * Suppress redundant link to same section for except too * Don't link try/except/else/finally keywords if in the same section * Format try/except/finally as keywords in modified sections Co-authored-by: Ezio Melotti (cherry picked from commit dcc82331c8f05a6a149ac15c519d4fbae72692b2) Co-authored-by: C.A.M. Gerlach --- Doc/reference/compound_stmts.rst | 121 +++++++++++++++++++------------ 1 file changed, 76 insertions(+), 45 deletions(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 751c7c2dbcf257..d914686c0a1ad9 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -199,10 +199,8 @@ returns the list ``[0, 1, 2]``. .. versionchanged:: 3.11 Starred elements are now allowed in the expression list. + .. _try: -.. _except: -.. _except_star: -.. _finally: The :keyword:`!try` statement ============================= @@ -215,7 +213,7 @@ The :keyword:`!try` statement keyword: as single: : (colon); compound statement -The :keyword:`try` statement specifies exception handlers and/or cleanup code +The :keyword:`!try` statement specifies exception handlers and/or cleanup code for a group of statements: .. productionlist:: python-grammar @@ -231,40 +229,56 @@ for a group of statements: try3_stmt: "try" ":" `suite` : "finally" ":" `suite` +Additional information on exceptions can be found in section :ref:`exceptions`, +and information on using the :keyword:`raise` statement to generate exceptions +may be found in section :ref:`raise`. -The :keyword:`except` clause(s) specify one or more exception handlers. When no + +.. _except: + +:keyword:`!except` clause +------------------------- + +The :keyword:`!except` clause(s) specify one or more exception handlers. When no exception occurs in the :keyword:`try` clause, no exception handler is executed. When an exception occurs in the :keyword:`!try` suite, a search for an exception -handler is started. This search inspects the except clauses in turn until one -is found that matches the exception. An expression-less except clause, if -present, must be last; it matches any exception. For an except clause with an -expression, that expression is evaluated, and the clause matches the exception +handler is started. This search inspects the :keyword:`!except` clauses in turn +until one is found that matches the exception. +An expression-less :keyword:`!except` clause, if present, must be last; +it matches any exception. +For an :keyword:`!except` clause with an expression, +that expression is evaluated, and the clause matches the exception if the resulting object is "compatible" with the exception. An object is compatible with an exception if the object is the class or a :term:`non-virtual base class ` of the exception object, or a tuple containing an item that is the class or a non-virtual base class of the exception object. -If no except clause matches the exception, the search for an exception handler +If no :keyword:`!except` clause matches the exception, +the search for an exception handler continues in the surrounding code and on the invocation stack. [#]_ -If the evaluation of an expression in the header of an except clause raises an -exception, the original search for a handler is canceled and a search starts for +If the evaluation of an expression +in the header of an :keyword:`!except` clause raises an exception, +the original search for a handler is canceled and a search starts for the new exception in the surrounding code and on the call stack (it is treated as if the entire :keyword:`try` statement raised the exception). .. index:: single: as; except clause -When a matching except clause is found, the exception is assigned to the target -specified after the :keyword:`!as` keyword in that except clause, if present, and -the except clause's suite is executed. All except clauses must have an -executable block. When the end of this block is reached, execution continues -normally after the entire try statement. (This means that if two nested -handlers exist for the same exception, and the exception occurs in the try -clause of the inner handler, the outer handler will not handle the exception.) +When a matching :keyword:`!except` clause is found, +the exception is assigned to the target +specified after the :keyword:`!as` keyword in that :keyword:`!except` clause, +if present, and the :keyword:`!except` clause's suite is executed. +All :keyword:`!except` clauses must have an executable block. +When the end of this block is reached, execution continues +normally after the entire :keyword:`try` statement. +(This means that if two nested handlers exist for the same exception, +and the exception occurs in the :keyword:`!try` clause of the inner handler, +the outer handler will not handle the exception.) When an exception has been assigned using ``as target``, it is cleared at the -end of the except clause. This is as if :: +end of the :keyword:`!except` clause. This is as if :: except E as N: foo @@ -278,7 +292,8 @@ was translated to :: del N This means the exception must be assigned to a different name to be able to -refer to it after the except clause. Exceptions are cleared because with the +refer to it after the :keyword:`!except` clause. +Exceptions are cleared because with the traceback attached to them, they form a reference cycle with the stack frame, keeping all locals in that frame alive until the next garbage collection occurs. @@ -286,7 +301,8 @@ keeping all locals in that frame alive until the next garbage collection occurs. module: sys object: traceback -Before an except clause's suite is executed, details about the exception are +Before an :keyword:`!except` clause's suite is executed, +details about the exception are stored in the :mod:`sys` module and can be accessed via :func:`sys.exc_info`. :func:`sys.exc_info` returns a 3-tuple consisting of the exception class, the exception instance and a traceback object (see section :ref:`types`) identifying @@ -312,17 +328,24 @@ when leaving an exception handler:: >>> print(sys.exc_info()) (None, None, None) + .. index:: keyword: except_star -The :keyword:`except*` clause(s) are used for handling -:exc:`ExceptionGroup`\ s. The exception type for matching is interpreted as in +.. _except_star: + +:keyword:`!except*` clause +-------------------------- + +The :keyword:`!except*` clause(s) are used for handling +:exc:`ExceptionGroup`\s. The exception type for matching is interpreted as in the case of :keyword:`except`, but in the case of exception groups we can have partial matches when the type matches some of the exceptions in the group. -This means that multiple except* clauses can execute, each handling part of -the exception group. Each clause executes once and handles an exception group +This means that multiple :keyword:`!except*` clauses can execute, +each handling part of the exception group. +Each clause executes once and handles an exception group of all matching exceptions. Each exception in the group is handled by at most -one except* clause, the first that matches it. :: +one :keyword:`!except*` clause, the first that matches it. :: >>> try: ... raise ExceptionGroup("eg", @@ -342,15 +365,16 @@ one except* clause, the first that matches it. :: +------------------------------------ >>> - Any remaining exceptions that were not handled by any except* clause - are re-raised at the end, combined into an exception group along with - all exceptions that were raised from within except* clauses. + Any remaining exceptions that were not handled by any :keyword:`!except*` + clause are re-raised at the end, combined into an exception group along with + all exceptions that were raised from within :keyword:`!except*` clauses. - An except* clause must have a matching type, and this type cannot be a - subclass of :exc:`BaseExceptionGroup`. It is not possible to mix except - and except* in the same :keyword:`try`. :keyword:`break`, - :keyword:`continue` and :keyword:`return` cannot appear in an except* - clause. + An :keyword:`!except*` clause must have a matching type, + and this type cannot be a subclass of :exc:`BaseExceptionGroup`. + It is not possible to mix :keyword:`except` and :keyword:`!except*` + in the same :keyword:`try`. + :keyword:`break`, :keyword:`continue` and :keyword:`return` + cannot appear in an :keyword:`!except*` clause. .. index:: @@ -359,17 +383,28 @@ one except* clause, the first that matches it. :: statement: break statement: continue +.. _except_else: + +:keyword:`!else` clause +----------------------- + The optional :keyword:`!else` clause is executed if the control flow leaves the :keyword:`try` suite, no exception was raised, and no :keyword:`return`, :keyword:`continue`, or :keyword:`break` statement was executed. Exceptions in the :keyword:`!else` clause are not handled by the preceding :keyword:`except` clauses. + .. index:: keyword: finally -If :keyword:`finally` is present, it specifies a 'cleanup' handler. The +.. _finally: + +:keyword:`!finally` clause +-------------------------- + +If :keyword:`!finally` is present, it specifies a 'cleanup' handler. The :keyword:`try` clause is executed, including any :keyword:`except` and -:keyword:`!else` clauses. If an exception occurs in any of the clauses and is +:keyword:`else` clauses. If an exception occurs in any of the clauses and is not handled, the exception is temporarily saved. The :keyword:`!finally` clause is executed. If there is a saved exception it is re-raised at the end of the :keyword:`!finally` clause. If the :keyword:`!finally` clause raises another @@ -387,7 +422,7 @@ or :keyword:`continue` statement, the saved exception is discarded:: 42 The exception information is not available to the program during execution of -the :keyword:`finally` clause. +the :keyword:`!finally` clause. .. index:: statement: return @@ -396,10 +431,10 @@ the :keyword:`finally` clause. When a :keyword:`return`, :keyword:`break` or :keyword:`continue` statement is executed in the :keyword:`try` suite of a :keyword:`!try`...\ :keyword:`!finally` -statement, the :keyword:`finally` clause is also executed 'on the way out.' +statement, the :keyword:`!finally` clause is also executed 'on the way out.' The return value of a function is determined by the last :keyword:`return` -statement executed. Since the :keyword:`finally` clause always executes, a +statement executed. Since the :keyword:`!finally` clause always executes, a :keyword:`!return` statement executed in the :keyword:`!finally` clause will always be the last one executed:: @@ -412,13 +447,9 @@ always be the last one executed:: >>> foo() 'finally' -Additional information on exceptions can be found in section :ref:`exceptions`, -and information on using the :keyword:`raise` statement to generate exceptions -may be found in section :ref:`raise`. - .. versionchanged:: 3.8 Prior to Python 3.8, a :keyword:`continue` statement was illegal in the - :keyword:`finally` clause due to a problem with the implementation. + :keyword:`!finally` clause due to a problem with the implementation. .. _with: