`contextlib.md`

721 строк · 51.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.9/library/contextlib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `contextlib` – Утилиты для контекстов оператора `with`89**Исходный код:** [Lib/contextlib.py](https://python-all.ru/src/3.9/Lib/contextlib.py)1011---1213Этот модуль предоставляет утилиты для типовых задач, связанных с оператором [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with). Для получения дополнительной информации см. также [Типы менеджеров контекста](https://python-all.ru/3.9/library/stdtypes.html#typecontextmanager) и [Менеджеры контекста оператора with](https://python-all.ru/3.9/reference/datamodel.html#context-managers).1415## Утилиты1617Предоставляемые функции и классы:1819#### `class contextlib.AbstractContextManager`2021[абстрактный базовый класс](https://python-all.ru/3.9/glossary.html#term-abstract-base-class) для классов, реализующих [`object.__enter__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__enter__) и [`object.__exit__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__exit__). Предоставляется реализация по умолчанию для [`object.__enter__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__enter__), которая возвращает `self`, а [`object.__exit__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__exit__) – это абстрактный метод, который по умолчанию возвращает `None`. См. также определение [Типов менеджеров контекста](https://python-all.ru/3.9/library/stdtypes.html#typecontextmanager).2223Новое в версии 3.6.2425#### `class contextlib.AbstractAsyncContextManager`2627[абстрактный базовый класс](https://python-all.ru/3.9/glossary.html#term-abstract-base-class) для классов, реализующих [`object.__aenter__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__aenter__) и [`object.__aexit__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__aexit__). Предоставляется реализация по умолчанию для [`object.__aenter__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__aenter__), которая возвращает `self`, а [`object.__aexit__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__aexit__) – это абстрактный метод, который по умолчанию возвращает `None`. См. также определение [Асинхронных менеджеров контекста](https://python-all.ru/3.9/reference/datamodel.html#async-context-managers).2829Добавлено в версии 3.7.3031#### `@contextlib.contextmanager`3233Эта функция – [декоратор](https://python-all.ru/3.9/glossary.html#term-decorator), который можно использовать для определения фабричной функции для контекстных менеджеров оператора [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with), без необходимости создавать класс или отдельные методы [`__enter__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__enter__) и [`__exit__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__exit__).3435Хотя многие объекты изначально поддерживают использование в with-выражениях, иногда требуется управлять ресурсом, который сам по себе не является менеджером контекста, и не реализует метод `close()` для использования с `contextlib.closing`3637Абстрактным примером может служить следующий код для обеспечения корректного управления ресурсами:3839```python40from contextlib import contextmanager4142@contextmanager43def managed_resource(*args, **kwds):44    # Код для получения ресурса, например:45    resource = acquire_resource(*args, **kwds)46    try:47        yield resource48    finally:49        # Код для освобождения ресурса, например:50        release_resource(resource)5152>>> with managed_resource(timeout=3600) as resource:53...     # Ресурс освобождается в конце этого блока,54...     # даже если код в блоке вызывает исключение55```5657Декорируемая функция при вызове должна возвращать [генератор](https://python-all.ru/3.9/glossary.html#term-generator)-итератор. Этот итератор должен возвращать ровно одно значение, которое будет связано с целями в предложении `as` оператора [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with), если таковые имеются.5859В момент, где генератор делает yield, выполняется блок, вложенный в оператор [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with). Затем генератор возобновляется после выхода из блока. Если в блоке возникает необработанное исключение, оно повторно возбуждается внутри генератора в точке, где произошел yield. Таким образом, можно использовать оператор [`try`](https://python-all.ru/3.9/reference/compound_stmts.html#try)…[`except`](https://python-all.ru/3.9/reference/compound_stmts.html#except)…[`finally`](https://python-all.ru/3.9/reference/compound_stmts.html#finally) для перехвата ошибки (если есть) или для выполнения очистки. Если исключение перехватывается только для того, чтобы зарегистрировать его или выполнить какое-либо действие (а не подавить полностью), генератор должен повторно возбудить это исключение. В противном случае контекстный менеджер генератора сообщит оператору `with`, что исключение обработано, и выполнение продолжится с оператора, следующего сразу за оператором `with`.6061[`contextmanager()`](https://python-all.ru/3.9/library/contextlib.html#contextlib.contextmanager) использует [`ContextDecorator`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ContextDecorator), поэтому создаваемые им контекстные менеджеры могут использоваться как в качестве декораторов, так и в операторах [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with). При использовании в качестве декоратора для каждого вызова функции неявно создается новый экземпляр генератора (это позволяет в противном случае «одноразовым» контекстным менеджерам, созданным с помощью [`contextmanager()`](https://python-all.ru/3.9/library/contextlib.html#contextlib.contextmanager), соответствовать требованию, согласно которому контекстные менеджеры должны поддерживать многократные вызовы, чтобы их можно было использовать в качестве декораторов).6263Изменено в версии 3.2: Использование [`ContextDecorator`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ContextDecorator).6465#### `@contextlib.asynccontextmanager`6667Аналог [`contextmanager()`](https://python-all.ru/3.9/library/contextlib.html#contextlib.contextmanager), но создает [асинхронный контекстный менеджер](https://python-all.ru/3.9/reference/datamodel.html#async-context-managers).6869Эта функция – [декоратор](https://python-all.ru/3.9/glossary.html#term-decorator), который можно использовать для определения фабричной функции для асинхронных контекстных менеджеров оператора [`async with`](https://python-all.ru/3.9/reference/compound_stmts.html#async-with), без необходимости создавать класс или отдельные методы [`__aenter__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__aenter__) и [`__aexit__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__aexit__). Она должна применяться к функции [асинхронного генератора](https://python-all.ru/3.9/glossary.html#term-asynchronous-generator).7071Простой пример:7273```python74from contextlib import asynccontextmanager7576@asynccontextmanager77async def get_connection():78    conn = await acquire_db_connection()79    try:80        yield conn81    finally:82        await release_db_connection(conn)8384async def get_all_users():85    async with get_connection() as conn:86        return conn.query('SELECT ...')87```8889Добавлено в версии 3.7.9091#### `contextlib.closing(thing)`9293Возвращает контекстный менеджер, который закрывает *thing* после завершения блока. По сути эквивалентно следующему:9495```python96from contextlib import contextmanager9798@contextmanager99def closing(thing):100    try:101        yield thing102    finally:103        thing.close()104```105106И позволяет писать код следующим образом:107108```python109from contextlib import closing110from urllib.request import urlopen111112with closing(urlopen('https://www.python.org')) as page:113    for line in page:114        print(line)115```116117без необходимости явно закрывать `page`. Даже если произойдет ошибка, `page.close()` будет вызван при выходе из блока [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with).118119#### `contextlib.nullcontext(enter_result=None)`120121Возвращает менеджер контекста, который возвращает *enter\_result* из `__enter__`, но в остальном ничего не делает. Предназначен для использования в качестве замены опционального менеджера контекста, например:122123```python124def myfunction(arg, ignore_exceptions=False):125    if ignore_exceptions:126        # Используйте suppress, чтобы игнорировать все исключения.127        cm = contextlib.suppress(Exception)128    else:129        # Не игнорируйте никакие исключения, cm не оказывает эффекта.130        cm = contextlib.nullcontext()131    with cm:132        # Выполнить действие133```134135Пример использования *enter\_result*:136137```python138def process_file(file_or_path):139    if isinstance(file_or_path, str):140        # Если строка, открыть файл141        cm = open(file_or_path)142    else:143        # Вызывающий отвечает за закрытие файла144        cm = nullcontext(file_or_path)145146    with cm as file:147        # Выполнить обработку файла148```149150Добавлено в версии 3.7.151152#### `contextlib.suppress(*exceptions)`153154Возвращает менеджер контекста, который подавляет любые из указанных исключений, если они возникают в теле оператора `with`, а затем возобновляет выполнение с первого оператора после завершения оператора `with`.155156Как и любой другой механизм, полностью подавляющий исключения, этот менеджер контекста следует использовать только для обработки очень специфических ошибок, когда молчаливое продолжение выполнения программы является правильным решением.157158Например:159160```python161from contextlib import suppress162163with suppress(FileNotFoundError):164    os.remove('somefile.tmp')165166with suppress(FileNotFoundError):167    os.remove('someotherfile.tmp')168```169170Этот код эквивалентен:171172```python173try:174    os.remove('somefile.tmp')175except FileNotFoundError:176    pass177178try:179    os.remove('someotherfile.tmp')180except FileNotFoundError:181    pass182```183184Этот менеджер контекста является [реентерабельным](https://python-all.ru/3.9/library/contextlib.html#reentrant-cms).185186Новое в версии 3.4.187188#### `contextlib.redirect_stdout(new_target)`189190Менеджер контекста для временного перенаправления [`sys.stdout`](https://python-all.ru/3.9/library/sys.html#sys.stdout) в другой файл или файлоподобный объект.191192Этот инструмент добавляет гибкость существующим функциям или классам, чей вывод жестко привязан к stdout.193194Например, вывод [`help()`](https://python-all.ru/3.9/library/functions.html#help) обычно отправляется в *sys.stdout*. Этот вывод можно захватить в строку, перенаправив его на объект [`io.StringIO`](https://python-all.ru/3.9/library/io.html#io.StringIO). Заменяющий поток данных возвращается из метода `__enter__` и поэтому доступен как цель оператора [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with):195196```python197with redirect_stdout(io.StringIO()) as f:198    help(pow)199s = f.getvalue()200```201202Чтобы отправить вывод [`help()`](https://python-all.ru/3.9/library/functions.html#help) в файл на диске, перенаправьте вывод в обычный файл:203204```python205with open('help.txt', 'w') as f:206    with redirect_stdout(f):207        help(pow)208```209210Чтобы отправить вывод [`help()`](https://python-all.ru/3.9/library/functions.html#help) в *sys.stderr*:211212```python213with redirect_stdout(sys.stderr):214    help(pow)215```216217Обратите внимание, что глобальный побочный эффект на [`sys.stdout`](https://python-all.ru/3.9/library/sys.html#sys.stdout) означает, что этот менеджер контекста не подходит для использования в библиотечном коде и большинстве многопоточных приложений. Он также не влияет на вывод подпроцессов. Тем не менее, это всё ещё полезный подход для многих вспомогательных скриптов.218219Этот менеджер контекста является [реентерабельным](https://python-all.ru/3.9/library/contextlib.html#reentrant-cms).220221Новое в версии 3.4.222223#### `contextlib.redirect_stderr(new_target)`224225Аналогично [`redirect_stdout()`](https://python-all.ru/3.9/library/contextlib.html#contextlib.redirect_stdout), но перенаправляет [`sys.stderr`](https://python-all.ru/3.9/library/sys.html#sys.stderr) в другой файл или файлоподобный объект.226227Этот менеджер контекста является [реентерабельным](https://python-all.ru/3.9/library/contextlib.html#reentrant-cms).228229Новое в версии 3.5.230231#### `class contextlib.ContextDecorator`232233Базовый класс, который позволяет менеджеру контекста также использоваться в качестве декоратора.234235Менеджеры контекста, наследующие от `ContextDecorator`, должны обычным образом реализовывать `__enter__` и `__exit__`. `__exit__` сохраняет необязательную обработку исключений даже при использовании в качестве декоратора.236237`ContextDecorator` используется [`contextmanager()`](https://python-all.ru/3.9/library/contextlib.html#contextlib.contextmanager), поэтому эта функциональность доступна автоматически.238239Пример `ContextDecorator`:240241```python242from contextlib import ContextDecorator243244class mycontext(ContextDecorator):245    def __enter__(self):246        print('Starting')247        return self248249    def __exit__(self, *exc):250        print('Finishing')251        return False252253>>> @mycontext()254... def function():255...     print('The bit in the middle')256...257>>> function()258Starting259The bit in the middle260Finishing261262>>> with mycontext():263...     print('The bit in the middle')264...265Starting266The bit in the middle267Finishing268```269270Это изменение – всего лишь синтаксический сахар для любой конструкции следующего вида:271272```python273def f():274    with cm():275        # Выполнить действия276```277278`ContextDecorator` позволяет вместо этого писать:279280```python281@cm()282def f():283    # Выполнить действия284```285286Становится ясно, что `cm` применяется ко всей функции, а не только к её части (и экономия уровня отступа тоже приятна).287288Существующие менеджеры контекста, уже имеющие базовый класс, можно расширить, используя `ContextDecorator` в качестве примеси (mixin):289290```python291from contextlib import ContextDecorator292293class mycontext(ContextBaseClass, ContextDecorator):294    def __enter__(self):295        return self296297    def __exit__(self, *exc):298        return False299```300301> **Примечание**302>303> Поскольку декорированная функция должна допускать многократный вызов, нижележащий менеджер контекста должен поддерживать использование в нескольких операторах [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with). Если это не так, следует использовать исходную конструкцию с явным оператором `with` внутри функции.304305Новое в версии 3.2.306307#### `class contextlib.ExitStack`308309Менеджер контекста, предназначенный для упрощения программного комбинирования других менеджеров контекста и функций очистки, особенно тех, которые являются необязательными или определяются входными данными.310311Например, набор файлов можно легко обработать в одном операторе with следующим образом:312313```python314with ExitStack() as stack:315    files = [stack.enter_context(open(fname)) for fname in filenames]316    # Все открытые файлы будут автоматически закрыты в конце317    # оператор with, даже если попытки открыть файлы, идущие далее318    # в списке, вызывают исключение319```320321Метод [`__enter__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__enter__) возвращает экземпляр [`ExitStack`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ExitStack) и не выполняет никаких дополнительных операций.322323Каждый экземпляр поддерживает стек зарегистрированных колбэков, которые вызываются в обратном порядке при закрытии экземпляра (явно или неявно в конце оператора [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with)). Обратите внимание, что колбэки *не* вызываются неявно при сборке мусора экземпляра стека контекста.324325Такая стековая модель используется, чтобы менеджеры контекста, получающие свои ресурсы в методе `__init__` (например, файловые объекты), могли обрабатываться корректно.326327Поскольку зарегистрированные колбэки вызываются в порядке, обратном регистрации, в итоге это ведёт себя так, как если бы с зарегистрированным набором колбэков использовалось несколько вложенных операторов [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with). Это распространяется даже на обработку исключений: если внутренний колбэк подавляет или заменяет исключение, то внешним колбэкам будут переданы аргументы, основанные на этом обновлённом состоянии.328329Это относительно низкоуровневый API, который заботится о деталях корректной размотки стека колбэков выхода. Он предоставляет подходящую основу для менеджеров контекста более высокого уровня, которые манипулируют стеком выхода специфичным для приложения образом.330331Новое в версии 3.3.332333#### `enter_context(cm)`334335Входит в новый менеджер контекста и добавляет его метод [`__exit__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__exit__) в стек колбэков. Возвращаемое значение – результат собственного метода [`__enter__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__enter__) менеджера контекста.336337Эти менеджеры контекста могут подавлять исключения точно так же, как они это делали бы при непосредственном использовании в операторе [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with).338339#### `push(exit)`340341Добавляет метод [`__exit__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__exit__) менеджера контекста в стек колбэков.342343Поскольку `__enter__` *не* вызывается, этот метод можно использовать для покрытия части реализации [`__enter__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__enter__) собственным методом [`__exit__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__exit__) менеджера контекста.344345Если передан объект, не являющийся менеджером контекста, этот метод считает его колбэком с той же сигнатурой, что и метод [`__exit__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__exit__) менеджера контекста, и добавляет его напрямую в стек колбэков.346347Возвращая истинные значения, эти колбэки могут подавлять исключения так же, как это делают методы [`__exit__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__exit__) менеджеров контекста.348349Переданный объект возвращается из функции, что позволяет использовать этот метод в качестве декоратора функции.350351#### `callback(callback, /, *args, **kwds)`352353Принимает произвольную функцию-колбэк и аргументы и добавляет её в стек колбэков.354355В отличие от других методов, колбэки, добавленные таким образом, не могут подавлять исключения (поскольку им никогда не передаются сведения об исключении).356357Переданный колбэк возвращается из функции, что позволяет использовать этот метод в качестве декоратора функции.358359#### `pop_all()`360361Перемещает стек колбэков в новый экземпляр [`ExitStack`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ExitStack) и возвращает его. При этой операции колбэки не вызываются – вместо этого они будут вызваны при закрытии нового стека (явно или неявно в конце оператора [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with)).362363Например, группу файлов можно открыть как операцию «всё или ничего» следующим образом:364365```python366with ExitStack() as stack:367    files = [stack.enter_context(open(fname)) for fname in filenames]368    # Сохраните метод close, но пока не вызывайте его.369    close_files = stack.pop_all().close370    # Если открытие любого файла завершается неудачей, все ранее открытые файлы будут371    # закрыты автоматически. Если все файлы открыты успешно,372    # они останутся открытыми даже после завершения оператора with.373    # close_files() затем можно вызвать явно, чтобы закрыть их все.374```375376#### `close()`377378Немедленно разворачивает стек колбэков, вызывая колбэки в порядке, обратном регистрации. Для любых зарегистрированных менеджеров контекста и колбэков выхода переданные аргументы будут указывать, что исключения не произошло.379380#### `class contextlib.AsyncExitStack`381382[Асинхронный менеджер контекста](https://python-all.ru/3.9/reference/datamodel.html#async-context-managers), аналогичный [`ExitStack`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ExitStack), который поддерживает объединение как синхронных, так и асинхронных менеджеров контекста, а также имеет корутины для логики очистки.383384Метод `close()` не реализован, [`aclose()`](https://python-all.ru/3.9/library/contextlib.html#contextlib.AsyncExitStack.aclose) должен использоваться вместо.385386#### `coroutine enter_async_context(cm)`387388Аналогично `enter_context()`, но ожидает асинхронный менеджер контекста.389390#### `push_async_exit(exit)`391392Аналогично `push()`, но ожидает либо асинхронный менеджер контекста, либо корутинную функцию.393394#### `push_async_callback(callback, /, *args, **kwds)`395396Аналогично `callback()`, но ожидает корутинную функцию.397398#### `coroutine aclose()`399400Аналогично `close()`, но корректно обрабатывает ожидаемые объекты.401402Продолжая пример для [`asynccontextmanager()`](https://python-all.ru/3.9/library/contextlib.html#contextlib.asynccontextmanager):403404```python405async with AsyncExitStack() as stack:406    connections = [await stack.enter_async_context(get_connection())407        for i in range(5)]408    # Все открытые соединения будут автоматически освобождены в конце409    # оператора async with, даже если попытки открыть соединение410    # далее в списке вызывают исключение.411```412413Добавлено в версии 3.7.414415## Примеры и рецепты416417В этом разделе описаны некоторые примеры и рецепты для эффективного использования инструментов, предоставляемых [`contextlib`](https://python-all.ru/3.9/library/contextlib.html#module-contextlib).418419### Поддержка переменного числа менеджеров контекста420421Основной вариант использования [`ExitStack`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ExitStack) – это тот, что описан в документации класса: поддержка переменного числа менеджеров контекста и других операций очистки в одном операторе [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with). Переменность может быть обусловлена тем, что количество необходимых менеджеров контекста определяется пользовательским вводом (например, открытие указанной пользователем коллекции файлов), или тем, что некоторые менеджеры контекста являются необязательными:422423```python424with ExitStack() as stack:425    for resource in resources:426        stack.enter_context(resource)427    if need_special_resource():428        special = acquire_special_resource()429        stack.callback(release_special_resource, special)430    # Выполните операции, использующие полученные ресурсы431```432433Как показано, [`ExitStack`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ExitStack) также значительно упрощает использование операторов [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with) для управления произвольными ресурсами, которые изначально не поддерживают протокол управления контекстом.434435### Перехват исключений из методов `__enter__`436437Иногда бывает желательно перехватывать исключения из реализации метода `__enter__`, *не* перехватывая случайно исключения из тела оператора [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with) или метода `__exit__` менеджера контекста. Используя [`ExitStack`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ExitStack), можно немного разделить шаги протокола управления контекстом, чтобы это стало возможным:438439```python440stack = ExitStack()441try:442    x = stack.enter_context(cm)443except Exception:444    # обработать исключение __enter__445else:446    with stack:447        # Обработка нормального случая448```449450Необходимость в этом, скорее всего, указывает на то, что базовый API должен предоставлять прямой интерфейс управления ресурсами для использования с операторами [`try`](https://python-all.ru/3.9/reference/compound_stmts.html#try)/[`except`](https://python-all.ru/3.9/reference/compound_stmts.html#except)/[`finally`](https://python-all.ru/3.9/reference/compound_stmts.html#finally), но не все API хорошо спроектированы в этом отношении. Когда менеджер контекста является единственным предоставляемым API управления ресурсами, тогда [`ExitStack`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ExitStack) может упростить обработку различных ситуаций, которые невозможно обработать напрямую в операторе [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with).451452### Очистка в реализации `__enter__`453454Как отмечено в документации [`ExitStack.push()`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ExitStack.push), этот метод может быть полезен для очистки уже выделенного ресурса, если последующие шаги в реализации [`__enter__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__enter__) завершатся неудачей.455456Вот пример реализации этого для менеджера контекста, который принимает функции захвата и освобождения ресурса, а также опциональную функцию проверки, и отображает их на протокол управления контекстом:457458```python459from contextlib import contextmanager, AbstractContextManager, ExitStack460461class ResourceManager(AbstractContextManager):462463    def __init__(self, acquire_resource, release_resource, check_resource_ok=None):464        self.acquire_resource = acquire_resource465        self.release_resource = release_resource466        if check_resource_ok is None:467            def check_resource_ok(resource):468                return True469        self.check_resource_ok = check_resource_ok470471    @contextmanager472    def _cleanup_on_error(self):473        with ExitStack() as stack:474            stack.push(self)475            yield476            # Проверка прошла успешно и не вызвала исключение477            # Соответственно, мы хотим сохранить ресурс и передать его478            # обратно вызывающему коду479            stack.pop_all()480481    def __enter__(self):482        resource = self.acquire_resource()483        with self._cleanup_on_error():484            if not self.check_resource_ok(resource):485                msg = "Failed validation for {!r}"486                raise RuntimeError(msg.format(resource))487        return resource488489    def __exit__(self, *exc_details):490        # Нам не нужно дублировать логику освобождения ресурсов491        self.release_resource()492```493494### Замена любого использования `try-finally` и флаговых переменных495496Иногда встречается шаблон, в котором используется инструкция `try-finally` с переменной-флагом, указывающей, должно ли выполняться тело предложения `finally`. В простейшей форме (если это нельзя обработать простым использованием предложения `except`) это выглядит примерно так:497498```python499cleanup_needed = True500try:501    result = perform_operation()502    if result:503        cleanup_needed = False504finally:505    if cleanup_needed:506        cleanup_resources()507```508509Как и в любом коде, основанном на инструкции `try`, это может вызвать проблемы при разработке и рецензировании, поскольку код настройки и код очистки могут оказаться разделенными произвольно длинными участками кода.510511[`ExitStack`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ExitStack) позволяет вместо этого зарегистрировать колбэк для выполнения в конце инструкции `with`, а затем позже решить пропустить выполнение этого колбэка:512513```python514from contextlib import ExitStack515516with ExitStack() as stack:517    stack.callback(cleanup_resources)518    result = perform_operation()519    if result:520        stack.pop_all()521```522523Это позволяет заранее явно указать предполагаемое поведение очистки, вместо того чтобы требовать отдельную переменную-флаг.524525Если конкретное приложение часто использует этот шаблон, его можно упростить еще больше с помощью небольшого вспомогательного класса:526527```python528from contextlib import ExitStack529530class Callback(ExitStack):531    def __init__(self, callback, /, *args, **kwds):532        super().__init__()533        self.callback(callback, *args, **kwds)534535    def cancel(self):536        self.pop_all()537538with Callback(cleanup_resources) as cb:539    result = perform_operation()540    if result:541        cb.cancel()542```543544Если очистка ресурсов уже не аккуратно оформлена в виде отдельной функции, то все равно можно использовать форму декоратора [`ExitStack.callback()`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ExitStack.callback), чтобы объявить очистку ресурсов заранее:545546```python547from contextlib import ExitStack548549with ExitStack() as stack:550    @stack.callback551    def cleanup_resources():552        ...553    result = perform_operation()554    if result:555        stack.pop_all()556```557558Из-за того, как работает протокол декоратора, функция обратного вызова, объявленная таким образом, не может принимать никаких параметров. Вместо этого любые ресурсы, которые необходимо освободить, должны быть доступны как переменные замыкания.559560### Использование менеджера контекста в качестве декоратора функции561562[`ContextDecorator`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ContextDecorator) позволяет использовать менеджер контекста как в обычной инструкции `with`, так и в качестве декоратора функции.563564Например, иногда полезно оборачивать функции или группы инструкций в логгер, который может отслеживать время входа и время выхода. Вместо написания как декоратора функции, так и менеджера контекста для этой задачи, наследование от [`ContextDecorator`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ContextDecorator) предоставляет обе возможности в одном определении:565566```python567from contextlib import ContextDecorator568import logging569570logging.basicConfig(level=logging.INFO)571572class track_entry_and_exit(ContextDecorator):573    def __init__(self, name):574        self.name = name575576    def __enter__(self):577        logging.info('Entering: %s', self.name)578579    def __exit__(self, exc_type, exc, exc_tb):580        logging.info('Exiting: %s', self.name)581```582583Экземпляры этого класса можно использовать как менеджер контекста:584585```python586with track_entry_and_exit('widget loader'):587    print('Some time consuming activity goes here')588    load_widget()589```590591А также как декоратор функции:592593```python594@track_entry_and_exit('widget loader')595def activity():596    print('Some time consuming activity goes here')597    load_widget()598```599600Обратите внимание, что есть одно дополнительное ограничение при использовании менеджеров контекста в качестве декораторов функций: невозможно получить доступ к возвращаемому значению [`__enter__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__enter__). Если это значение необходимо, то все равно нужно использовать явную инструкцию `with`.601602> **См. также**603>604> **[**PEP 343**](https://python-all.ru/3.9/library/contextlib.html) – Оператор «with»**605>606> Спецификация, предыстория и примеры для инструкции [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with) в Python.607608## Одноразовые, многократно используемые и реентерабельные менеджеры контекста609610Большинство менеджеров контекста написаны таким образом, что их можно эффективно использовать только один раз в инструкции [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with). Эти одноразовые менеджеры контекста должны создаваться заново каждый раз при использовании – попытка использовать их второй раз вызовет исключение или иным образом приведет к некорректной работе.611612Это распространенное ограничение означает, что обычно рекомендуется создавать менеджеры контекста непосредственно в заголовке инструкции [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with), где они используются (как показано во всех примерах использования выше).613614Файлы являются примером эффективно одноразовых менеджеров контекста, поскольку первая инструкция [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with) закроет файл, предотвращая любые дальнейшие операции ввода-вывода с использованием этого объекта файла.615616Менеджеры контекста, созданные с помощью [`contextmanager()`](https://python-all.ru/3.9/library/contextlib.html#contextlib.contextmanager), также являются одноразовыми менеджерами контекста и будут сообщать об ошибке, если базовый генератор не сможет выполнить yield при попытке использовать их второй раз:617618```python619>>> from contextlib import contextmanager620>>> @contextmanager621... def singleuse():622...     print("Before")623...     yield624...     print("After")625...626>>> cm = singleuse()627>>> with cm:628...     pass629...630Before631After632>>> with cm:633...     pass634...635Traceback (most recent call last):636    ...637RuntimeError: generator didn't yield638```639640### Реентерабельные менеджеры контекста641642Более сложные менеджеры контекста могут быть «реентерабельными». Такие менеджеры контекста можно использовать не только в нескольких инструкциях [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with), но также *внутри* инструкции `with`, которая уже использует тот же менеджер контекста.643644[`threading.RLock`](https://python-all.ru/3.9/library/threading.html#threading.RLock) – это пример реентерабельного контекстного менеджера, как и [`suppress()`](https://python-all.ru/3.9/library/contextlib.html#contextlib.suppress) и [`redirect_stdout()`](https://python-all.ru/3.9/library/contextlib.html#contextlib.redirect_stdout). Вот очень простой пример реентерабельного использования:645646```python647>>> from contextlib import redirect_stdout648>>> from io import StringIO649>>> stream = StringIO()650>>> write_to_stream = redirect_stdout(stream)651>>> with write_to_stream:652...     print("This is written to the stream rather than stdout")653...     with write_to_stream:654...         print("This is also written to the stream")655...656>>> print("This is written directly to stdout")657This is written directly to stdout658>>> print(stream.getvalue())659This is written to the stream rather than stdout660This is also written to the stream661```662663Реальные примеры реентерабельности, скорее всего, будут включать несколько функций, вызывающих друг друга, и, следовательно, будут гораздо сложнее этого примера.664665Также обратите внимание, что быть реентерабельным – это *не* то же самое, что быть потокобезопасным. [`redirect_stdout()`](https://python-all.ru/3.9/library/contextlib.html#contextlib.redirect_stdout), например, определенно не является потокобезопасным, так как он вносит глобальное изменение в состояние системы, привязывая [`sys.stdout`](https://python-all.ru/3.9/library/sys.html#sys.stdout) к другому потоку данных.666667### Многократно используемые менеджеры контекста668669Отличающиеся от одноразовых и реентерабельных менеджеров контекста – «многократно используемые» менеджеры контекста (или, если быть совсем точным, «многократно используемые, но не реентерабельные» менеджеры контекста, поскольку реентерабельные менеджеры контекста также являются многократно используемыми). Эти менеджеры контекста поддерживают многократное использование, но завершатся ошибкой (или иным образом будут работать некорректно), если конкретный экземпляр менеджера контекста уже был использован во внешней инструкции with.670671[`threading.Lock`](https://python-all.ru/3.9/library/threading.html#threading.Lock) является примером многократно используемого, но не реентерабельного менеджера контекста (для реентерабельной блокировки необходимо использовать [`threading.RLock`](https://python-all.ru/3.9/library/threading.html#threading.RLock) вместо этого).672673Другим примером многократно используемого, но не реентерабельного менеджера контекста является [`ExitStack`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ExitStack), так как он вызывает *все* зарегистрированные в данный момент колбэки при выходе из любой инструкции with, независимо от того, где эти колбэки были добавлены:674675```python676>>> from contextlib import ExitStack677>>> stack = ExitStack()678>>> with stack:679...     stack.callback(print, "Callback: from first context")680...     print("Leaving first context")681...682Leaving first context683Callback: from first context684>>> with stack:685...     stack.callback(print, "Callback: from second context")686...     print("Leaving second context")687...688Leaving second context689Callback: from second context690>>> with stack:691...     stack.callback(print, "Callback: from outer context")692...     with stack:693...         stack.callback(print, "Callback: from inner context")694...         print("Leaving inner context")695...     print("Leaving outer context")696...697Leaving inner context698Callback: from inner context699Callback: from outer context700Leaving outer context701```702703Как показывает вывод примера, повторное использование одного объекта стека в нескольких инструкциях with работает корректно, но попытка вложить их приведет к очистке стека в конце самой внутренней инструкции with, что вряд ли является желательным поведением.704705Использование отдельных экземпляров [`ExitStack`](https://python-all.ru/3.9/library/contextlib.html#contextlib.ExitStack) вместо повторного использования одного экземпляра позволяет избежать этой проблемы:706707```python708>>> from contextlib import ExitStack709>>> with ExitStack() as outer_stack:710...     outer_stack.callback(print, "Callback: from outer context")711...     with ExitStack() as inner_stack:712...         inner_stack.callback(print, "Callback: from inner context")713...         print("Leaving inner context")714...     print("Leaving outer context")715...716Leaving inner context717Callback: from inner context718Leaving outer context719Callback: from outer context720```721