8000 gh-95975: Move except/*/finally ref labels to more precise locations … · python/cpython@d79a412 · GitHub
[go: up one dir, main page]

Skip to content

Commit d79a412

Browse files
miss-islingtonCAM-Gerlach
authored andcommitted
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 <ezio.melotti@gmail.com> * 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 <ezio.melotti@gmail.com> (cherry picked from commit dcc8233) Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
1 parent eb5cdf6 commit d79a412

File tree

1 file changed

+76
-46
lines changed

1 file changed

+76
-46
lines changed

Doc/reference/compound_stmts.rst

Lines changed: 76 additions & 46 deletions
< 8000 ul aria-label="File view" class="prc-SegmentedControl-SegmentedControl-e7570 mx-2" data-size="small">
  • +
    until one is found that matches the exception.
    Original file line numberDiff line numberDiff line change
    @@ -199,10 +199,8 @@ returns the list ``[0, 1, 2]``.
    199199
    .. versionchanged:: 3.11
    200200
    Starred elements are now allowed in the expression list.
    201201

    202+
    202203
    .. _try:
    203-
    .. _except:
    204-
    .. _except_star:
    205-
    .. _finally:
    206204

    207205
    The :keyword:`!try` statement
    208206
    =============================
    @@ -215,7 +213,7 @@ The :keyword:`!try` statement
    215213
    keyword: as
    216214
    single: : (colon); compound statement
    217215

    218-
    The :keyword:`try` statement specifies exception handlers and/or cleanup code
    216+
    The :keyword:`!try` statement specifies exception handlers and/or cleanup code
    219217
    for a group of statements:
    220218

    221219
    .. productionlist:: python-grammar
    @@ -231,40 +229,56 @@ for a group of statements:
    231229
    try3_stmt: "try" ":" `suite`
    232230
    : "finally" ":" `suite`
    233231

    232+
    Additional information on exceptions can be found in section :ref:`exceptions`,
    233+
    and information on using the :keyword:`raise` statement to generate exceptions
    234+
    may be found in section :ref:`raise`.
    234235

    235-
    The :keyword:`except` clause(s) specify one or more exception handlers. When no
    236+
    237+
    .. _except:
    238+
    239+
    :keyword:`!except` clause
    240+
    -------------------------
    241+
    242+
    The :keyword:`!except` clause(s) specify one or more exception handlers. When no
    236243
    exception occurs in the :keyword:`try` clause, no exception handler is executed.
    237244
    When an exception occurs in the :keyword:`!try` suite, a search for an exception
    238-
    handler is started. This search inspects the except clauses in turn until one
    239-
    is found that matches the exception. An expression-less except clause, if
    240-
    present, must be last; it matches any exception. For an except clause with an
    241-
    expression, that expression is evaluated, and the clause matches the exception
    245+
    handler is started. This search inspects the :keyword:`!except` clauses in turn
    246
    247+
    An expression-less :keyword:`!except` clause, if present, must be last;
    248+
    it matches any exception.
    249+
    For an :keyword:`!except` clause with an expression,
    250+
    that expression is evaluated, and the clause matches the exception
    242251
    if the resulting object is "compatible" with the exception. An object is
    243252
    compatible with an exception if the object is the class or a
    244253
    :term:`non-virtual base class <abstract base class>` of the exception object,
    245254
    or a tuple containing an item that is the class or a non-virtual base class
    246255
    of the exception object.
    247256

    248-
    If no except clause matches the exception, the search for an exception handler
    257+
    If no :keyword:`!except` clause matches the exception,
    258+
    the search for an exception handler
    249259
    continues in the surrounding code and on the invocation stack. [#]_
    250260

    251-
    If the evaluation of an expression in the header of an except clause raises an
    252-
    exception, the original search for a handler is canceled and a search starts for
    261+
    If the evaluation of an expression
    262+
    in the header of an :keyword:`!except` clause raises an exception,
    263+
    the original search for a handler is canceled and a search starts for
    253264
    the new exception in the surrounding code and on the call stack (it is treated
    254265
    as if the entire :keyword:`try` statement raised the exception).
    255266

    256267
    .. index:: single: as; except clause
    257268

    258-
    When a matching except clause is found, the exception is assigned to the target
    259-
    specified after the :keyword:`!as` keyword in that except clause, if present, and
    260-
    the except clause's suite is executed. All except clauses must have an
    261-
    executable block. When the end of this block is reached, execution continues
    262-
    normally after the entire try statement. (This means that if two nested
    263-
    handlers exist for the same exception, and the exception occurs in the try
    264-
    clause of the inner handler, the outer handler will not handle the exception.)
    269+
    When a matching :keyword:`!except` clause is found,
    270+
    the exception is assigned to the target
    271+
    specified after the :keyword:`!as` keyword in that :keyword:`!except` clause,
    272+
    if present, and the :keyword:`!except` clause's suite is executed.
    273+
    All :keyword:`!except` clauses must have an executable block.
    274+
    When the end of this block is reached, execution continues
    275+
    normally after the entire :keyword:`try` statement.
    276+
    (This means that if two nested handlers exist for the same exception,
    277+
    and the exception occurs in the :keyword:`!try` clause of the inner handler,
    278+
    the outer handler will not handle the exception.)
    265279

    266280
    When an exception has been assigned using ``as target``, it is cleared at the
    267-
    end of the except clause. This is as if ::
    281+
    end of the :keyword:`!except` clause. This is as if ::
    268282

    269283
    except E as N:
    270284
    foo
    @@ -278,15 +292,17 @@ was translated to ::
    278292
    del N
    279293

    280294
    This means the exception must be assigned to a different name to be able to
    281-
    refer to it after the except clause. Exceptions are cleared because with the
    295+
    refer to it after the :keyword:`!except` clause.
    296+
    Exceptions are cleared because with the
    282297
    traceback attached to them, they form a reference cycle with the stack frame,
    283298
    keeping all locals in that frame alive until the next garbage collection occurs.
    284299

    285300
    .. index::
    286301
    module: sys
    287302
    object: traceback
    288303

    289-
    Before an except clause's suite is executed, details about the exception are
    304+
    Before an :keyword:`!except` clause's suite is executed,
    305+
    details about the exception are
    290306
    stored in the :mod:`sys` module and can be accessed via :func:`sys.exc_info`.
    291307
    :func:`sys.exc_info` returns a 3-tuple consisting of the exception class, the
    292308
    exception instance and a traceback object (see section :ref:`types`) identifying
    @@ -312,17 +328,24 @@ when leaving an exception handler::
    312328
    >>> print(sys.exc_info())
    313329
    (None, None, None)
    314330

    331+
    315332
    .. index::
    316333
    keyword: except_star
    317334

    318-
    The :keyword:`except*<except_star>` clause(s) are used for handling
    319-
    :exc:`ExceptionGroup`\ s. The exception type for matching is interpreted as in
    335+
    .. _except_star:
    336+
    337+
    :keyword:`!except*` clause
    338+
    --------------------------
    339+
    340+
    The :keyword:`!except*` clause(s) are used for handling
    341+
    :exc:`ExceptionGroup`\s. The exception type for matching is interpreted as in
    320342
    the case of :keyword:`except`, but in the case of exception groups we can have
    321343
    partial matches when the type matches some of the exceptions in the group.
    322-
    This means that multiple except* clauses can execute, each handling part of
    323-
    the exception group. Each clause executes once and handles an exception group
    344+
    This means that multiple :keyword:`!except*` clauses can execute,
    345+
    each handling part of the exception group.
    346+
    Each clause executes once and handles an exception group
    324347
    of all matching exceptions. Each exception in the group is handled by at most
    325-
    one except* clause, the first that matches it. ::
    348+
    one :keyword:`!except*` clause, the first that matches it. ::
    326349

    327350
    >>> try:
    328351
    ... raise ExceptionGroup("eg",
    @@ -341,16 +364,16 @@ one except* clause, the first that matches it. ::
    341364
    | ValueError: 1
    342365
    +------------------------------------
    343366

    344-
    Any remaining exceptions that were not handled by any :keyword:`!except*`
    345-
    clause are re-raised at the end, combined into an exception group along with
    346-
    all exceptions that were raised from within :keyword:`!except*` clauses.
    367+
    Any remaining exceptions that were not handled by any :keyword:`!except*`
    368+
    clause are re-raised at the end, combined into an exception group along with
    369+
    all exceptions that were raised from within :keyword:`!except*` clauses.
    347370

    348-
    An :keyword:`!except*` clause must have a matching type,
    349-
    and this type cannot be a subclass of :exc:`BaseExceptionGroup`.
    350-
    It is not possible to mix :keyword:`except` and :keyword:`!except*`
    351-
    in the same :keyword:`try`.
    352-
    :keyword:`break`, :keyword:`continue` and :keyword:`return`
    353-
    cannot appear in an :keyword:`!except*` clause.
    371+
    An :keyword:`!except*` clause must have a matching type,
    372+
    and this type cannot be a subclass of :exc:`BaseExceptionGroup`.
    373+
    It is not possible to mix :keyword:`except` and :keyword:`!except*`
    374+
    in the same :keyword:`try`.
    375+
    :keyword:`break`, :keyword:`continue` and :keyword:`return`
    376+
    cannot appear in an :keyword:`!except*` clause.
    354377

    355378

    356379
    .. index::
    @@ -359,17 +382,28 @@ cannot appear in an :keyword:`!except*` clause.
    359382
    statement: break
    360383
    statement: continue
    361384

    385+
    .. _except_else:
    386+
    387+
    :keyword:`!else` clause
    388+
    -----------------------
    389+
    362390
    The optional :keyword:`!else` clause is executed if the control flow leaves the
    363391
    :keyword:`try` suite, no exception was raised, and no :keyword:`return`,
    364392
    :keyword:`continue`, or :keyword:`break` statement was executed. Exceptions in
    365393
    the :keyword:`!else` clause are not handled by the preceding :keyword:`except`
    366394
    clauses.
    367395

    396+
    368397
    .. index:: keyword: finally
    369398

    370-
    If :keyword:`finally` is present, it specifies a 'cleanup' handler. The
    399+
    .. _finally:
    400+
    401+
    :keyword:`!finally` clause
    402+
    --------------------------
    403+
    404+
    If :keyword:`!finally` is present, it specifies a 'cleanup' handler. The
    371405
    :keyword:`try` clause is executed, including any :keyword:`except` and
    372-
    :keyword:`!else` clauses. If an exception occurs in any of the clauses and is
    406+
    :keyword:`else` clauses. If an exception occurs in any of the clauses and is
    373407
    not handled, the exception is temporarily saved. The :keyword:`!finally` clause
    374408
    is executed. If there is a saved exception it is re-raised at the end of the
    375409
    :keyword:`!finally` clause. If the :keyword:`!finally` clause raises another
    @@ -387,7 +421,7 @@ or :keyword:`continue` statement, the saved exception is discarded::
    387421
    42
    388422

    389423
    The exception information is not available to the program during execution of
    390-
    the :keyword:`finally` clause.
    424+
    the :keyword:`!finally` clause.
    391425

    392426
    .. index::
    393427
    statement: return
    @@ -396,10 +430,10 @@ the :keyword:`finally` clause.
    396430

    397431
    When a :keyword:`return`, :keyword:`break` or :keyword:`continue` statement is
    398432
    executed in the :keyword:`try` suite of a :keyword:`!try`...\ :keyword:`!finally`
    399-
    statement, the :keyword:`finally` clause is also executed 'on the way out.'
    433+
    statement, the :keyword:`!finally` clause is also executed 'on the way out.'
    400434

    401435
    The return value of a function is determined by the last :keyword:`return`
    402-
    statement executed. Since the :keyword:`finally` clause always executes, a
    436+
    statement executed. Since the :keyword:`!finally` clause always executes, a
    403437
    :keyword:`!return` statement executed in the :keyword:`!finally` clause will
    404438
    always be the last one executed::
    405439

    @@ -412,13 +446,9 @@ always be the last one executed::
    412446
    >>> foo()
    413447
    'finally'
    414448

    415-
    Additional information on exceptions can be found in section :ref:`exceptions`,
    416-
    and information on using the :keyword:`raise` statement to generate exceptions
    417-
    may be found in section :ref:`raise`.
    418-
    419449
    .. versionchanged:: 3.8
    420450
    Prior to Python 3.8, a :keyword:`continue` statement was illegal in the
    421-
    :keyword:`finally` clause due to a problem with the implementation.
    451+
    :keyword:`!finally` clause due to a problem with the implementation.
    422452

    423453

    424454
    .. _with:

    0 commit comments

    Comments
     (0)
    0