[Python-checkins] bpo-33468: Add try-finally contextlib.contextmanager example (GH-7816) (GH-8426)

Mon Jul 23 17:38:27 EDT 2018

https://github.com/python/cpython/commit/5b3643d1a5114551350a9d17fb0aaab2d503c290
commit: 5b3643d1a5114551350a9d17fb0aaab2d503c290
branch: 3.6
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Tal Einat <taleinat+github at gmail.com>
date: 2018年07月24日T00:38:24+03:00
summary:
bpo-33468: Add try-finally contextlib.contextmanager example (GH-7816) (GH-8426)
(cherry picked from commit bde782bb594edffeabe978abeee2b7082ab9bc2a)
Co-authored-by: Matthias Bussonnier <bussonniermatthias at gmail.com>
files:
M Doc/library/contextlib.rst

diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst
index dd34c96c8f8d..49eaba3d01ed 100644
--- a/Doc/library/contextlib.rst
+++ b/Doc/library/contextlib.rst
@@ -36,22 +36,28 @@ Functions and classes provided:
 function for :keyword:`with` statement context managers, without needing to
 create a class or separate :meth:`__enter__` and :meth:`__exit__` methods.
 
- A simple example (this is not recommended as a real way of generating HTML!)::
+ While many objects natively support use in with statements, sometimes a
+ resource needs to be managed that isn't a context manager in its own right,
+ and doesn't implement a ``close()`` method for use with ``contextlib.closing``
+
+ An abstract example would be the following to ensure correct resource
+ management::
 
 from contextlib import contextmanager
 
 @contextmanager
- def tag(name):
- print("<%s>" % name)
- yield
- print("</%s>" % name)
+ def managed_resource(*args, **kwds):
+ # Code to acquire resource, e.g.:
+ resource = acquire_resource(*args, **kwds)
+ try:
+ yield resource
+ finally:
+ # Code to release resource, e.g.:
+ release_resource(resource)
 
- >>> with tag("h1"):
- ... print("foo")
- ...
- <h1>
- foo
- </h1>
+ >>> with managed_resource(timeout=3600) as resource:
+ ... # Resource is released at the end of this block,
+ ... # even if code in the block raises an exception
 
 The function being decorated must return a :term:`generator`-iterator when
 called. This iterator must yield exactly one value, which will be bound to
