gh-126664: Use else instead of finally in "The with statement" documentation.

[vivodi]

Documentation

In 8.5 The with statement, we can use else instead of finally.

manager = (EXPRESSION)
enter = type(manager).__enter__
exit = type(manager).__exit__
value = enter(manager)
hit_except = False

try:
    TARGET = value
    SUITE
except:
    hit_except = True
    if not exit(manager, *sys.exc_info()):
        raise
finally:
    if not hit_except:
        exit(manager, None, None, None)

is semantically equivalent to:

  manager = (EXPRESSION)
  enter = type(manager).__enter__
  exit = type(manager).__exit__
  value = enter(manager)

  try:
      TARGET = value
      SUITE
  except:
      if not exit(manager, *sys.exc_info()):
          raise
  else:
      exit(manager, None, None, None)

• Issue: Use else instead of finally in "The with statement" documentation. #126664

---

📚 Documentation preview 📚: https://cpython-previews--126665.org.readthedocs.build/

[cpython-cla-bot]

All commit authors signed the Contributor License Agreement.

[miss-islington-app]

Thanks @vivodi for the PR, and @gpshead for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[miss-islington-app]

Thanks @vivodi for the PR, and @gpshead for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

[bedevere-app]

GH-126670 is a backport of this pull request to the 3.13 branch.

[bedevere-app]

GH-126671 is a backport of this pull request to the 3.12 branch.

[rrevans]

The try statement example is confusing and/or incorrect after this PR, at least when SUITE contains any return, continue, or break statement. In those cases the else clause of the try statement is not executed.

But with statements invoke the __exit__ function in all cases after the __enter__ function returns without raising an exception, so the given example does not match the actual semantics of with statements if SUITE contains such a statement.

I think this should be reverted. The semantically-equivalent sample code is not helpful if it applies only to suites without those kinds of statements (or it would be confusing to qualify when the semantics are correct).

Example:

for _ in range(1):
    try:
        break
    except:
        pass
    else:
        print('exit')

produces no output (as expected for a try-else statement)

but this does (as expected for a with statement)

class Context:
    def __enter__(self):
        pass
    def __exit__(self, *args):
        print('exit')

for _ in range(1):
    with Context():
        break

[gpshead]

thanks! yes, you are correct. revert PRs in flight.