The current example for contextlib.contextmanager doesn't use try/finally, which sets folks up for writing resource management context managers that don't clean up after exceptions properly.

There's an example with try/finally down in the contextlib.closing docs, but I'm thinking it would be worthwhile to change the presentation of contextmanager itself.

It doesn't look as a good example. It is not always good to write a closing tag if an error was occurred while write an inner content. In many cases it is better to stop writing after error.

Right, the HTML example was always a bit cutesy (hence the disclaimer in the header), but it's hard to come up with a good illustrative example that isn't already a native context manager in the standard library.

Perhaps it would make sense to change the example text completely, and write something entirely abstract like:

    from contextlib import contextmanager

    @contextmanager
    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 managed_resource(*args, **kwds) as resource:
    ...     # Resource is released at the end of this block,
    ...     # even if code in the block raises an exception

Then the introductory text could be updated to say something like "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``.".

A possible concrete example: Capturing sys.stdout and/or sys.stderr for testing, as in test.support.captured_output.

Similar to closing, we have dedicated context managers for stdout and stderr redirection now: https://docs.python.org/3/library/contextlib.html#contextlib.redirect_stdout

Redirecting stdin could be a good example though, since we've so far chosen not to provide a standard context manager for that (it's a sufficiently uncommon use case that we haven't seen the need to add it directly).

The entirely abstract example LGTM.

As for concrete real word examples, the possible one is changing the current working directory:

    cwd = os.getcwd()
    try:
        os.chdir(target_dir)
        yield
    finally:
        os.chdir(cwd)

Nick's abstract example LGTM as well.

New changeset bde782bb594edffeabe978abeee2b7082ab9bc2a by Tal Einat (Matthias Bussonnier) in branch 'master':
bpo-33468: Add try-finally contextlib.contextmanager example (GH-7816)
https://github.com/python/cpython/commit/bde782bb594edffeabe978abeee2b7082ab9bc2a

New changeset 4e166ffd29b675238ccd94964743f6cb206d2235 by Tal Einat (Miss Islington (bot)) in branch '3.7':
bpo-33468: Add try-finally contextlib.contextmanager example (GH-7816) (GH-8425)
https://github.com/python/cpython/commit/4e166ffd29b675238ccd94964743f6cb206d2235

New changeset 5b3643d1a5114551350a9d17fb0aaab2d503c290 by Tal Einat (Miss Islington (bot)) in branch '3.6':
bpo-33468: Add try-finally contextlib.contextmanager example (GH-7816) (GH-8426)
https://github.com/python/cpython/commit/5b3643d1a5114551350a9d17fb0aaab2d503c290

New changeset f7e60a69485097dc28f000c55615038278f84333 by Tal Einat in branch '2.7':
[2.7] bpo-33468: Add try-finally contextlib.contextmanager example (GH-7816) (GH-8427)
https://github.com/python/cpython/commit/f7e60a69485097dc28f000c55615038278f84333

Thanks for the PR, Matthias Bussonnier!