28.7. contextlib — Utilities for with-statement contexts

Nouveau dans la version 2.5.

Code source : Lib/contextlib.py

Ce module fournit des utilitaires pour les tâches impliquant le mot-clé with. Pour plus d’informations voir aussi Le type gestionnaire de contexte et Gestionnaire de contexte With.

Functions provided:

contextlib.contextmanager(func)

Cette fonction est un decorator qui peut être utilisé pour définir une fonction fabriquant des gestionnaires de contexte à utiliser avec with, sans nécessiter de créer une classe ou des méthodes __enter__() et __exit__() séparées.

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 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(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 generator-iterator when called. This iterator must yield exactly one value, which will be bound to the targets in the with statement’s as clause, if any.

At the point where the generator yields, the block nested in the with statement is executed. The generator is then resumed after the block is exited. If an unhandled exception occurs in the block, it is reraised inside the generator at the point where the yield occurred. Thus, you can use a try…except…finally statement to trap the error (if any), or ensure that some cleanup takes place. If an exception is trapped merely in order to log it or to perform some action (rather than to suppress it entirely), the generator must reraise that exception. Otherwise the generator context manager will indicate to the with statement that the exception has been handled, and execution will resume with the statement immediately following the with statement.

contextlib.nested(mgr1[, mgr2[, ...]])

Combine multiple context managers into a single nested context manager.

This function has been deprecated in favour of the multiple manager form of the with statement.

The one advantage of this function over the multiple manager form of the with statement is that argument unpacking allows it to be used with a variable number of context managers as follows:

from contextlib import nested

with nested(*managers):
    do_something()

Note that if the __exit__() method of one of the nested context managers indicates an exception should be suppressed, no exception information will be passed to any remaining outer context managers. Similarly, if the __exit__() method of one of the nested managers raises an exception, any previous exception state will be lost; the new exception will be passed to the __exit__() methods of any remaining outer context managers. In general, __exit__() methods should avoid raising exceptions, and in particular they should not re-raise a passed-in exception.

This function has two major quirks that have led to it being deprecated. Firstly, as the context managers are all constructed before the function is invoked, the __new__() and __init__() methods of the inner context managers are not actually covered by the scope of the outer context managers. That means, for example, that using nested() to open two files is a programming error as the first file will not be closed promptly if an exception is thrown when opening the second file.

Secondly, if the __enter__() method of one of the inner context managers raises an exception that is caught and suppressed by the __exit__() method of one of the outer context managers, this construct will raise RuntimeError rather than skipping the body of the with statement.

Developers that need to support nesting of a variable number of context managers can either use the warnings module to suppress the DeprecationWarning raised by this function or else use this function as a model for an application specific implementation.

Obsolète depuis la version 2.7: The with-statement now supports this functionality directly (without the confusing error prone quirks).

contextlib.closing(thing)

Renvoie un gestionnaire de contexte qui ferme thing à la fin du bloc. C’est essentiellement équivalent à :

from contextlib import contextmanager

@contextmanager
def closing(thing):
    try:
        yield thing
    finally:
        thing.close()

Et cela vous permet d’écrire du code tel que :

from contextlib import closing
import urllib

with closing(urllib.urlopen('http://www.python.org')) as page:
    for line in page:
        print line

sans besoin de fermer explicitement page. Même si une erreur survient, page.close() est appelée à la fermeture du bloc with.

Voir aussi

PEP 343 - The « with » statement

La spécification, les motivations et des exemples de l’instruction with en Python.