contextlib — Utilidades para declaraciones de contexto with

Código fuente: Lib/contextlib.py

---

Este módulo proporciona utilidades para tareas comunes que involucran la declaración with. Para obtener más información, consulte también Tipos gestores de contexto y Gestores de Contexto en la Declaración with.

Utilidades

Funciones y clases proporcionadas:

class contextlib.AbstractContextManager

Una clase base abstracta para clases que implementan object.__enter__() y object.__exit__(). Se proporciona una implementación predeterminada para object.__enter__() que retorna self mientras que object.__exit__() es un método abstracto que por defecto retorna None. Véase también la definición de Tipos gestores de contexto.

Added in version 3.6.

class contextlib.AbstractAsyncContextManager

Una clase base abstracta para clases que implementan object.__aenter__() y object.__aexit__(). Se proporciona una implementación predeterminada para object.__aenter__() que retorna self mientras que object.__aexit__() es un método abstracto que por defecto retorna None. Véase también la definición de Gestores de contexto asíncronos.

Added in version 3.7.

@contextlib.contextmanager

This function is a decorator that can be used to define a factory function for with statement context managers, without needing to create a class or separate __enter__() and __exit__() methods.

Si bien muchos objetos admiten de forma nativa el uso con declaraciones, a veces es necesario administrar un recurso que no sea un administrador de contexto por sí mismo y no implemente un método close() para usar con contextlib.close

Un ejemplo abstracto sería el siguiente para garantizar la gestión correcta de los recursos:

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)

La función se puede usar así:

>>> 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

La función que se está decorando debe retornar un iterador generador cuando se llama. Este iterador debe producir exactamente un valor, que estará vinculado a los objetivos en la with declaración de la cláusula as, si existe.

En el punto donde el generador cede, se ejecuta el bloque anidado en la palabra clave with. El generador se reanuda luego de salir del bloque. Si se produce una excepción no controlada en el bloque, se vuelve a plantear dentro del generador en el punto donde se produjo el rendimiento. Por lo tanto, puede usar una declaración try…except…finally para atrapar el error (si lo hay), o asegurarse de que se realice una limpieza. Si una excepción queda atrapada simplemente para registrarla o realizar alguna acción (en lugar de suprimirla por completo), el generador debe volver a generar esa excepción. De lo contrario, el administrador de contexto del generador indicará a la palabra clave with que se ha manejado la excepción, y la ejecución se reanudará con la declaración inmediatamente siguiente a la palabra clave with.

contextmanager() usa ContextDecorator para que los gestores de contexto que crea se puedan usar como decoradores, así como en declaraciones with. Cuando se usa como decorador, se crea implícitamente una nueva instancia de generador en cada llamada de función (esto permite que los gestores de contexto «de-un-tiro» creados por contextmanager() cumplan el requisito de que los gestores de contexto admitan múltiples invocaciones para ser utilizado como decoradores).

Distinto en la versión 3.2: Uso de ContextDecorator.

@contextlib.asynccontextmanager

Similar a contextmanager(), pero crea un administrador de contexto asíncrono.

This function is a decorator that can be used to define a factory function for async with statement asynchronous context managers, without needing to create a class or separate __aenter__() and __aexit__() methods. It must be applied to an asynchronous generator function.

Un ejemplo simple:

from contextlib import asynccontextmanager

@asynccontextmanager
async def get_connection():
    conn = await acquire_db_connection()
    try:
        yield conn
    finally:
        await release_db_connection(conn)

async def get_all_users():
    async with get_connection() as conn:
        return conn.query('SELECT ...')

Added in version 3.7.

Los administradores de contexto definidos con asynccontextmanager() se pueden utilizar como decoradores o con declaraciones async with:

import time
from contextlib import asynccontextmanager

@asynccontextmanager
async def timeit():
    now = time.monotonic()
    try:
        yield
    finally:
        print(f'it took {time.monotonic() - now}s to run')

@timeit()
async def main():
    # ... async code ...

Cuando se utiliza como decorador, se crea implícitamente una nueva instancia de generador en cada llamada de función. Esto permite que los administradores de contexto de otro modo «únicos» creados por asynccontextmanager() cumplan con el requisito de que los administradores de contexto admitan múltiples invocaciones para ser utilizados como decoradores.

Distinto en la versión 3.10: Los administradores de contexto asíncronos creados con asynccontextmanager() se pueden utilizar como decoradores.

contextlib.closing(thing)

retorna un gestor de contexto que cierra thing al completar el bloque. Esto es básicamente equivalente a:

from contextlib import contextmanager

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

Y te permite escribir código como este:

from contextlib import closing
from urllib.request import urlopen

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

sin necesidad de cerrar explícitamente la page. Incluso si se produce un error, se llamará a page.close() cuando salga el bloque with.

Nota

Most types managing resources support the context manager protocol, which closes thing on leaving the with statement. As such, closing() is most useful for third party types that don’t support context managers. This example is purely for illustration purposes, as urlopen() would normally be used in a context manager.

contextlib.aclosing(thing)

Retorna un administrador de contexto asíncrono que llama al método aclose() de thing una vez completado el bloque. Esto es básicamente equivalente a:

from contextlib import asynccontextmanager

@asynccontextmanager
async def aclosing(thing):
    try:
        yield thing
    finally:
        await thing.aclose()

Significativamente, aclosing() admite la limpieza determinista de generadores asincrónicos cuando salen temprano por break o una excepción. Por ejemplo:

from contextlib import aclosing

async with aclosing(my_generator()) as values:
    async for value in values:
        if value == 42:
            break

Este patrón garantiza que el código de salida asíncrono del generador se ejecute en el mismo contexto que sus iteraciones (de modo que las excepciones y las variables de contexto funcionen como se esperaba, y el código de salida no se ejecute después de la vida útil de alguna tarea de la que depende).

Added in version 3.10.

contextlib.nullcontext(enter_result=None)

retorna un gestor de contexto que retorna enter_result de __enter__, pero de lo contrario no hace nada. Está destinado a ser utilizado como un sustituto para un administrador de contexto opcional, por ejemplo:

def myfunction(arg, ignore_exceptions=False):
    if ignore_exceptions:
        # Use suppress to ignore all exceptions.
        cm = contextlib.suppress(Exception)
    else:
        # Do not ignore any exceptions, cm has no effect.
        cm = contextlib.nullcontext()
    with cm:
        # Do something

Un ejemplo usando enter_result:

def process_file(file_or_path):
    if isinstance(file_or_path, str):
        # If string, open file
        cm = open(file_or_path)
    else:
        # Caller is responsible for closing file
        cm = nullcontext(file_or_path)

    with cm as file:
        # Perform processing on the file

También se puede utilizar como sustituto de asynchronous context managers:

async def send_http(session=None):
    if not session:
        # If no http session, create it with aiohttp
        cm = aiohttp.ClientSession()
    else:
        # Caller is responsible for closing the session
        cm = nullcontext(session)

    async with cm as session:
        # Send http requests with session

Added in version 3.7.

Distinto en la versión 3.10: Se agregó compatibilidad con asynchronous context manager.

contextlib.suppress(*exceptions)

Retorna un administrador de contexto que suprime cualquiera de las excepciones especificadas si ocurren en el cuerpo de una instrucción with y luego reanuda la ejecución con la primera instrucción que sigue al final de la instrucción with.

Al igual que con cualquier otro mecanismo que suprima completamente las excepciones, este administrador de contexto debe usarse solo para cubrir errores muy específicos en los que se sabe que continuar silenciosamente con la ejecución del programa es lo correcto.

Por ejemplo:

from contextlib import suppress

with suppress(FileNotFoundError):
    os.remove('somefile.tmp')

with suppress(FileNotFoundError):
    os.remove('someotherfile.tmp')

Este código es equivalente a:

try:
    os.remove('somefile.tmp')
except FileNotFoundError:
    pass

try:
    os.remove('someotherfile.tmp')
except FileNotFoundError:
    pass

Este gestor de contexto es reentrant.

If the code within the with block raises a BaseExceptionGroup, suppressed exceptions are removed from the group. Any exceptions of the group which are not suppressed are re-raised in a new group which is created using the original group’s derive() method.

Added in version 3.4.

Distinto en la versión 3.12: suppress now supports suppressing exceptions raised as part of a BaseExceptionGroup.

contextlib.redirect_stdout(new_target)

Administrador de contexto para redirigir temporalmente sys.stdout a otro archivo u objeto similar a un archivo.

Esta herramienta agrega flexibilidad a las funciones o clases existentes cuya salida está programada para stdout.

Por ejemplo, la salida de help() normalmente se envía a sys.stdout. Puede capturar esa salida en una cadena redirigiendo la salida a un objeto io.StringIO. La secuencia de reemplazo se retorna desde el método __enter__ y, por lo tanto, está disponible como destino de la declaración with:

with redirect_stdout(io.StringIO()) as f:
    help(pow)
s = f.getvalue()

Para enviar la salida de help() a un archivo en el disco, redirija la salida a un archivo normal:

with open('help.txt', 'w') as f:
    with redirect_stdout(f):
        help(pow)

Para enviar la salida de help() a sys.stderr:

with redirect_stdout(sys.stderr):
    help(pow)

Tenga en cuenta que el efecto secundario global en sys.stdout significa que este administrador de contexto no es adecuado para su uso en el código de la biblioteca y en la mayoría de las aplicaciones con subprocesos. Tampoco tiene efecto en la salida de subprocesos. Sin embargo, sigue siendo un enfoque útil para muchos scripts de utilidad.

Este gestor de contexto es reentrant.

Added in version 3.4.

contextlib.redirect_stderr(new_target)

Similar a redirect_stdout() pero redirigiendo sys.stderr a otro archivo u objeto similar a un archivo.

Este gestor de contexto es reentrant.

Added in version 3.5.

contextlib.chdir(path)

Administrador de contexto no seguro en paralelo para cambiar el directorio de trabajo actual. Como esto cambia un estado global, el directorio de trabajo, no es adecuado para su uso en la mayoría de los contextos asincrónicos o de subprocesos. Tampoco es adecuado para la mayoría de las ejecuciones de código no lineal, como los generadores, donde la ejecución del programa se abandona temporalmente; a menos que se desee explícitamente, no debe ceder el paso cuando este administrador de contexto está activo.

Este es un contenedor simple alrededor de chdir(), cambia el directorio de trabajo actual al ingresar y restaura el anterior al salir.

Este gestor de contexto es reentrant.

Added in version 3.11.

class contextlib.ContextDecorator

Una clase base que permite que un administrador de contexto también se use como decorador.

Los gestores de contexto que heredan de ContextDecorator tienen que implementar __enter__ y __exit__ de manera normal. __exit__ conserva su manejo opcional de excepciones incluso cuando se usa como decorador.

ContextDecorator es utilizado por contextmanager(), por lo que obtiene esta funcionalidad automáticamente.

Ejemplo de ContextDecorator:

from contextlib import ContextDecorator

class mycontext(ContextDecorator):
    def __enter__(self):
        print('Starting')
        return self

    def __exit__(self, *exc):
        print('Finishing')
        return False

La clase se puede usar así:

>>> @mycontext()
... def function():
...     print('The bit in the middle')
...
>>> function()
Starting
The bit in the middle
Finishing

>>> with mycontext():
...     print('The bit in the middle')
...
Starting
The bit in the middle
Finishing

Este cambio es solo azúcar sintáctico para cualquier construcción de la siguiente forma:

def f():
    with cm():
        # Do stuff

ContextDecorator le permite escribir en su lugar:

@cm()
def f():
    # Do stuff

Deja en claro que el cm se aplica a toda la función, en lugar de solo una parte de ella (y guardar un nivel de sangría también es bueno).

Los gestores de contexto existentes que ya tienen una clase base pueden ampliarse utilizando ContextDecorator como una clase mezcla (mixin):

from contextlib import ContextDecorator

class mycontext(ContextBaseClass, ContextDecorator):
    def __enter__(self):
        return self

    def __exit__(self, *exc):
        return False

Nota

Como la función decorada debe poder llamarse varias veces, el gestor de contexto subyacente debe admitir el uso en múltiples declaraciones with. Si este no es el caso, se debe utilizar la construcción original con la declaración explícita with dentro de la función.

Added in version 3.2.

class contextlib.AsyncContextDecorator

Similar a ContextDecorator pero solo para funciones asincrónicas.

Ejemplo de AsyncContextDecorator:

from asyncio import run
from contextlib import AsyncContextDecorator

class mycontext(AsyncContextDecorator):
    async def __aenter__(self):
        print('Starting')
        return self

    async def __aexit__(self, *exc):
        print('Finishing')
        return False

La clase se puede usar así:

>>> @mycontext()
... async def function():
...     print('The bit in the middle')
...
>>> run(function())
Starting
The bit in the middle
Finishing

>>> async def function():
...    async with mycontext():
...         print('The bit in the middle')
...
>>> run(function())
Starting
The bit in the middle
Finishing

Added in version 3.10.

class contextlib.ExitStack

Un gestor de contexto que está diseñado para facilitar la combinación programática de otros gestores de contexto y funciones de limpieza, especialmente aquellas que son opcionales o que de otro modo son impulsadas por los datos de entrada.

Por ejemplo, un conjunto de archivos puede manejarse fácilmente en una sola declaración de la siguiente manera:

with ExitStack() as stack:
    files = [stack.enter_context(open(fname)) for fname in filenames]
    # All opened files will automatically be closed at the end of
    # the with statement, even if attempts to open files later
    # in the list raise an exception

The __enter__() method returns the ExitStack instance, and performs no additional operations.

Cada instancia mantiene una pila de retrollamadas registradas que se llaman en orden inverso cuando la instancia se cierra (ya sea explícita o implícitamente al final de una instrucción with). Tenga en cuenta que las retrollamadas no se invocan implícitamente cuando la instancia de la pila de contexto se recolecta basura.

Este modelo de pila se utiliza para que los administradores de contexto que adquieren sus recursos en su método __init__ (como los objetos de archivo) se puedan manejar correctamente.

Dado que las retrollamadas registradas se invocan en el orden inverso del registro, esto termina comportándose como si se hubieran utilizado múltiples instrucciones anidadas with con el conjunto registrado de retrollamadas. Esto incluso se extiende al manejo de excepciones: si una retrollamada interna suprime o reemplaza una excepción, las retrollamadas externas se pasarán argumentos basados en ese estado actualizado.

Esta es una API de nivel relativamente bajo que se ocupa de los detalles de desenrollar correctamente la pila de retrollamadas de salida. Proporciona una base adecuada para administradores de contexto de nivel superior que manipulan la pila de salida en formas específicas de la aplicación.

Added in version 3.3.

enter_context(cm)

Enters a new context manager and adds its __exit__() method to the callback stack. The return value is the result of the context manager’s own __enter__() method.

Estos administradores de contexto pueden suprimir excepciones tal como lo harían normalmente si se usaran directamente como parte de una declaración with.

Distinto en la versión 3.11: Lanza TypeError en lugar de AttributeError si cm no es un administrador de contexto.

push(exit)

Adds a context manager’s __exit__() method to the callback stack.

As __enter__ is not invoked, this method can be used to cover part of an __enter__() implementation with a context manager’s own __exit__() method.

If passed an object that is not a context manager, this method assumes it is a callback with the same signature as a context manager’s __exit__() method and adds it directly to the callback stack.

By returning true values, these callbacks can suppress exceptions the same way context manager __exit__() methods can.

El objeto pasado se retorna desde la función, lo que permite que este método se use como decorador de funciones.

callback(callback, /, *args, **kwds)

Acepta una función de retrollamada arbitraria y argumentos y la agrega a la pila de retrollamada.

A diferencia de los otros métodos, las retrollamadas agregadas de esta manera no pueden suprimir excepciones (ya que nunca se pasan los detalles de excepción).

La retrollamada pasada se retorna desde la función, lo que permite que este método se use como decorador de funciones.

pop_all()

Transfiere la pila de retrollamada a una instancia fresca ExitStack y la retorna. Esta operación no invoca retrollamadas; en cambio, ahora se invocarán cuando se cierre la nueva pila (ya sea explícita o implícitamente al final de una instrucción with).

Por ejemplo, un grupo de archivos se puede abrir como una operación de «todo o nada» de la siguiente manera:

with ExitStack() as stack:
    files = [stack.enter_context(open(fname)) for fname in filenames]
    # Hold onto the close method, but don't call it yet.
    close_files = stack.pop_all().close
    # If opening any file fails, all previously opened files will be
    # closed automatically. If all files are opened successfully,
    # they will remain open even after the with statement ends.
    # close_files() can then be invoked explicitly to close them all.

close()

Inmediatamente desenrolla la pila de retrollamada, invocando retrollamadas en el orden inverso de registro. Para los administradores de contexto y las retrollamadas de salida registradas, los argumentos pasados indicarán que no se produjo ninguna excepción.

class contextlib.AsyncExitStack

Un gestor de contexto asíncrono, similar a ExitStack, que admite la combinación de gestores de contexto síncrono y asíncrono, además de tener rutinas para la lógica de limpieza.

The close() method is not implemented; aclose() must be used instead.

coroutine enter_async_context(cm)

Similar to ExitStack.enter_context() but expects an asynchronous context manager.

Distinto en la versión 3.11: Lanza TypeError en lugar de AttributeError si cm no es un administrador de contexto asíncrono.

push_async_exit(exit)

Similar to ExitStack.push() but expects either an asynchronous context manager or a coroutine function.

push_async_callback(callback, /, *args, **kwds)

Similar to ExitStack.callback() but expects a coroutine function.

coroutine aclose()

Similar to ExitStack.close() but properly handles awaitables.

Continuando con el ejemplo para asynccontextmanager():

async with AsyncExitStack() as stack:
    connections = [await stack.enter_async_context(get_connection())
        for i in range(5)]
    # All opened connections will automatically be released at the end of
    # the async with statement, even if attempts to open a connection
    # later in the list raise an exception.

Added in version 3.7.

Ejemplos y recetas

Esta sección describe algunos ejemplos y recetas para hacer un uso efectivo de las herramientas proporcionadas por contextlib.

Apoyando un número variable de gestores de contexto

El caso de uso principal para ExitStack es el que se proporciona en la documentación de la clase: admite un número variable de gestores de contexto y otras operaciones de limpieza en una sola with. La variabilidad puede provenir de la cantidad de gestores de contexto que necesitan ser impulsados por la entrada del usuario (como abrir una colección de archivos especificada por el usuario), o de que algunos de los gestores de contexto sean opcionales:

with ExitStack() as stack:
    for resource in resources:
        stack.enter_context(resource)
    if need_special_resource():
        special = acquire_special_resource()
        stack.callback(release_special_resource, special)
    # Perform operations that use the acquired resources

Como se muestra, ExitStack también hace que sea bastante fácil de usar with para administrar recursos arbitrarios que no admiten de forma nativa el protocolo de gestión de contexto.

Capturando excepciones de los métodos __enter__

Ocasionalmente es deseable capturar excepciones de una implementación del método __enter__, sin capturar inadvertidamente excepciones del cuerpo de la declaración with o el método __exit__ del gestor de contexto. Al usar ExitStack, los pasos en el protocolo de gestor de contexto se pueden separar ligeramente para permitir esto:

stack = ExitStack()
try:
    x = stack.enter_context(cm)
except Exception:
    # handle __enter__ exception
else:
    with stack:
        # Handle normal case

Es probable que la necesidad de hacer esto indique que la API subyacente debería proporcionar una interfaz de administración de recursos directa para usar con try/except/finally, pero no todas las API están bien diseñados en ese sentido. Cuando un administrador de contexto es la única API de administración de recursos proporcionada, entonces ExitStack puede facilitar el manejo de diversas situaciones que no se pueden manejar directamente en una declaración with.

Limpieza en una implementación __enter__

As noted in the documentation of ExitStack.push(), this method can be useful in cleaning up an already allocated resource if later steps in the __enter__() implementation fail.

Aquí hay un ejemplo de cómo hacer esto para un administrador de contexto que acepta funciones de adquisición y liberación de recursos, junto con una función de validación opcional, y las asigna al protocolo de administración de contexto:

from contextlib import contextmanager, AbstractContextManager, ExitStack

class ResourceManager(AbstractContextManager):

    def __init__(self, acquire_resource, release_resource, check_resource_ok=None):
        self.acquire_resource = acquire_resource
        self.release_resource = release_resource
        if check_resource_ok is None:
            def check_resource_ok(resource):
                return True
        self.check_resource_ok = check_resource_ok

    @contextmanager
    def _cleanup_on_error(self):
        with ExitStack() as stack:
            stack.push(self)
            yield
            # The validation check passed and didn't raise an exception
            # Accordingly, we want to keep the resource, and pass it
            # back to our caller
            stack.pop_all()

    def __enter__(self):
        resource = self.acquire_resource()
        with self._cleanup_on_error():
            if not self.check_resource_ok(resource):
                msg = "Failed validation for {!r}"
                raise RuntimeError(msg.format(resource))
        return resource

    def __exit__(self, *exc_details):
        # We don't need to duplicate any of our resource release logic
        self.release_resource()

Reemplazar cualquier uso de try-finally y marcar variables

Un patrón que a veces verá es una declaración de try-finally con una variable de indicador para indicar si el cuerpo de la cláusula finally debe ejecutarse o no. En su forma más simple (que ya no puede manejarse simplemente usando una cláusula except en su lugar), se parece a esto:

cleanup_needed = True
try:
    result = perform_operation()
    if result:
        cleanup_needed = False
finally:
    if cleanup_needed:
        cleanup_resources()

Al igual que con cualquier código basado en la declaración try, esto puede causar problemas de desarrollo y revisión, porque el código de configuración y el código de limpieza pueden terminar separados por secciones de código arbitrariamente largas.

ExitStack hace posible registrar una retrollamada para su ejecución al final de una instrucción with, y luego decide omitir la ejecución de esa retrollamada:

from contextlib import ExitStack

with ExitStack() as stack:
    stack.callback(cleanup_resources)
    result = perform_operation()
    if result:
        stack.pop_all()

This allows the intended cleanup behaviour to be made explicit up front, rather than requiring a separate flag variable.

Si una aplicación particular usa mucho este patrón, puede simplificarse aún más por medio de una pequeña clase auxiliar:

from contextlib import ExitStack

class Callback(ExitStack):
    def __init__(self, callback, /, *args, **kwds):
        super().__init__()
        self.callback(callback, *args, **kwds)

    def cancel(self):
        self.pop_all()

with Callback(cleanup_resources) as cb:
    result = perform_operation()
    if result:
        cb.cancel()

Si la limpieza del recurso no está bien agrupada en una función independiente, entonces todavía es posible usar la forma decoradora de ExitStack.callback() para declarar la limpieza del recurso por adelantado:

from contextlib import ExitStack

with ExitStack() as stack:
    @stack.callback
    def cleanup_resources():
        ...
    result = perform_operation()
    if result:
        stack.pop_all()

Debido a la forma en que funciona el protocolo decorador, una función de retrollamada declarada de esta manera no puede tomar ningún parámetro. En cambio, se debe acceder a los recursos que se liberarán como variables de cierre.

Usar un gestor de contexto como decorador de funciones

ContextDecorator hace posible usar un gestor de contexto tanto en una instrucción ordinaria with como también como decorador de funciones.

Por ejemplo, a veces es útil envolver funciones o grupos de declaraciones con un registrador que puede rastrear la hora de entrada y la hora de salida. En lugar de escribir tanto un decorador de funciones como un administrador de contexto para la tarea, heredar de ContextDecorator proporciona ambas capacidades en una sola definición:

from contextlib import ContextDecorator
import logging

logging.basicConfig(level=logging.INFO)

class track_entry_and_exit(ContextDecorator):
    def __init__(self, name):
        self.name = name

    def __enter__(self):
        logging.info('Entering: %s', self.name)

    def __exit__(self, exc_type, exc, exc_tb):
        logging.info('Exiting: %s', self.name)

Las instancias de esta clase se pueden usar como un gestor de contexto:

with track_entry_and_exit('widget loader'):
    print('Some time consuming activity goes here')
    load_widget()

Y también como decorador de funciones:

@track_entry_and_exit('widget loader')
def activity():
    print('Some time consuming activity goes here')
    load_widget()

Note that there is one additional limitation when using context managers as function decorators: there’s no way to access the return value of __enter__(). If that value is needed, then it is still necessary to use an explicit with statement.

Ver también

PEP 343 - La declaración «with»

La especificación, antecedentes y ejemplos de la declaración de Python with.

Gestores de contexto de uso único, reutilizables y reentrantes

La mayoría de los gestores de contexto están escritos de una manera que significa que solo se pueden usar de manera efectiva en una declaración with una vez. Estos administradores de contexto de un solo uso deben crearse de nuevo cada vez que se usan; si intenta usarlos por segunda vez, se activará una excepción o, de lo contrario, no funcionará correctamente.

Esta limitación común significa que generalmente es aconsejable crear gestores de contexto directamente en el encabezado de la palabra clave with donde se usan (como se muestra en todos los ejemplos de uso anteriores).

Los archivos son un ejemplo de gestores de contexto de un solo uso, ya que la primera with cerrará el archivo, evitando cualquier otra operación de E/S que use ese objeto de archivo.

Los gestores de contexto creados usando contextmanager() también son gestores de contexto de un solo uso, y se quejarán de la falla del generador subyacente si se intenta usarlos por segunda vez:

>>> from contextlib import contextmanager
>>> @contextmanager
... def singleuse():
...     print("Before")
...     yield
...     print("After")
...
>>> cm = singleuse()
>>> with cm:
...     pass
...
Before
After
>>> with cm:
...     pass
...
Traceback (most recent call last):
    ...
RuntimeError: generator didn't yield

Gestores contextuales reentrantes

Los gestores de contexto más sofisticados pueden ser «reentrantes». Estos administradores de contexto no solo se pueden usar en múltiples declaraciones with, sino que también se pueden usar inside a with que ya está usando el mismo gestor de contexto.

threading.RLock es un ejemplo de administrador de contexto reentrante, al igual que suppress(), redirect_stdout() y chdir(). Aquí hay un ejemplo muy simple de uso de reentrada:

>>> from contextlib import redirect_stdout
>>> from io import StringIO
>>> stream = StringIO()
>>> write_to_stream = redirect_stdout(stream)
>>> with write_to_stream:
...     print("This is written to the stream rather than stdout")
...     with write_to_stream:
...         print("This is also written to the stream")
...
>>> print("This is written directly to stdout")
This is written directly to stdout
>>> print(stream.getvalue())
This is written to the stream rather than stdout
This is also written to the stream

Es más probable que los ejemplos del mundo real de reentrada impliquen múltiples funciones que se llaman entre sí y, por lo tanto, sean mucho más complicadas que este ejemplo.

Tenga en cuenta también que ser reentrante no es lo mismo que ser seguro para subprocesos. redirect_stdout(), por ejemplo, definitivamente no es seguro para subprocesos, ya que realiza una modificación global al estado del sistema al vincular sys.stdout a una secuencia diferente.

Gestores contextuales reutilizables

Distintos de los administradores de contexto de uso único y reentrante son los administradores de contexto «reutilizables» (o, para ser completamente explícitos, los administradores de contexto «reutilizables, pero no reentrantes», ya que los administradores de contexto reentrantes también son reutilizables). Estos administradores de contexto admiten que se usen varias veces, pero fallarán (o de lo contrario no funcionarán correctamente) si la instancia específica del administrador de contexto ya se ha utilizado en una declaración que contiene.

threading.Lock es un ejemplo de un gestor de contexto reutilizable, pero no reentrante (para un bloqueo reentrante, es necesario usar threading.RLock en su lugar).

Otro ejemplo de un administrador de contexto reutilizable, pero no reentrante es ExitStack, ya que invoca all las retrollamadas registradas actualmente al dejar cualquier con declaración, independientemente de dónde se agregaron esas retrollamadas:

>>> from contextlib import ExitStack
>>> stack = ExitStack()
>>> with stack:
...     stack.callback(print, "Callback: from first context")
...     print("Leaving first context")
...
Leaving first context
Callback: from first context
>>> with stack:
...     stack.callback(print, "Callback: from second context")
...     print("Leaving second context")
...
Leaving second context
Callback: from second context
>>> with stack:
...     stack.callback(print, "Callback: from outer context")
...     with stack:
...         stack.callback(print, "Callback: from inner context")
...         print("Leaving inner context")
...     print("Leaving outer context")
...
Leaving inner context
Callback: from inner context
Callback: from outer context
Leaving outer context

Como muestra el resultado del ejemplo, la reutilización de un solo objeto de pila en múltiples con declaraciones funciona correctamente, pero intentar anidarlos hará que la pila se borre al final de la declaración más interna, lo que es poco probable que sea un comportamiento deseable.

El uso de instancias separadas ExitStack en lugar de reutilizar una sola instancia evita ese problema:

>>> from contextlib import ExitStack
>>> with ExitStack() as outer_stack:
...     outer_stack.callback(print, "Callback: from outer context")
...     with ExitStack() as inner_stack:
...         inner_stack.callback(print, "Callback: from inner context")
...         print("Leaving inner context")
...     print("Leaving outer context")
...
Leaving inner context
Callback: from inner context
Leaving outer context
Callback: from outer context