Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[3.11] gh-95975: Move except/*/finally ref labels to more precise locations (GH-95976) #97722

Merged
merged 1 commit into from
Oct 2, 2022
Merged

[3.11] gh-95975: Move except/*/finally ref labels to more precise locations (GH-95976) #97722

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 76 additions & 45 deletions Doc/reference/compound_stmts.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
=============================
Expand All @@ -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
Expand All @@ -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 <abstract 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
Expand All @@ -278,15 +292,17 @@ 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.

.. index::
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
Expand All @@ -312,17 +328,24 @@ when leaving an exception handler::
>>> print(sys.exc_info())
(None, None, None)


.. index::
keyword: except_star

The :keyword:`except*<except_star>` 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",
Expand All @@ -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::
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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::

Expand All @@ -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:
Expand Down