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

Tal Einat webhook-mailer at python.org
Mon Jul 23 17:38:21 EDT 2018


https://github.com/python/cpython/commit/4e166ffd29b675238ccd94964743f6cb206d2235
commit: 4e166ffd29b675238ccd94964743f6cb206d2235
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Tal Einat <taleinat+github at gmail.com>
date: 2018-07-24T00:38:18+03:00
summary:

bpo-33468: Add try-finally contextlib.contextmanager example (GH-7816) (GH-8425)

(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 0b1f4f77dcc8..793bd63f673f 100644
--- a/Doc/library/contextlib.rst
+++ b/Doc/library/contextlib.rst
@@ -47,22 +47,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



More information about the Python-checkins mailing list