`contextlib.md`

861 строк · 60.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.11/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.11/Lib/contextlib.py)1011---1213Этот модуль предоставляет утилиты для типовых задач, связанных с оператором [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with). Для получения дополнительной информации см. также [Типы менеджеров контекста](https://python-all.ru/3.11/library/stdtypes.html#typecontextmanager) и [Менеджеры контекста оператора with](https://python-all.ru/3.11/reference/datamodel.html#context-managers).1415## Утилиты1617Предоставляемые функции и классы:1819#### `class contextlib.AbstractContextManager`2021[абстрактный базовый класс](https://python-all.ru/3.11/glossary.html#term-abstract-base-class) для классов, реализующих [`object.__enter__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__enter__) и [`object.__exit__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__exit__). Предоставляется реализация по умолчанию для [`object.__enter__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__enter__), которая возвращает `self`, а [`object.__exit__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__exit__) – это абстрактный метод, который по умолчанию возвращает `None`. См. также определение [Типов менеджеров контекста](https://python-all.ru/3.11/library/stdtypes.html#typecontextmanager).2223Новое в версии 3.6.2425#### `class contextlib.AbstractAsyncContextManager`2627[абстрактный базовый класс](https://python-all.ru/3.11/glossary.html#term-abstract-base-class) для классов, реализующих [`object.__aenter__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__aenter__) и [`object.__aexit__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__aexit__). Предоставляется реализация по умолчанию для [`object.__aenter__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__aenter__), которая возвращает `self`, а [`object.__aexit__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__aexit__) – это абстрактный метод, который по умолчанию возвращает `None`. См. также определение [Асинхронных менеджеров контекста](https://python-all.ru/3.11/reference/datamodel.html#async-context-managers).2829Добавлено в версии 3.7.3031#### `@contextlib.contextmanager`3233Эта функция – [декоратор](https://python-all.ru/3.11/glossary.html#term-decorator), который можно использовать для определения фабричной функции для контекстных менеджеров оператора [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with), без необходимости создавать класс или отдельные методы [`__enter__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__enter__) и [`__exit__()`](https://python-all.ru/3.11/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)51```5253Затем функцию можно использовать следующим образом:5455```python56>>> with managed_resource(timeout=3600) as resource:57...     # Ресурс освобождается в конце этого блока,58...     # даже если код в блоке вызывает исключение59```6061Декорируемая функция при вызове должна возвращать [генератор](https://python-all.ru/3.11/glossary.html#term-generator)-итератор. Этот итератор должен возвращать ровно одно значение, которое будет связано с целями в предложении `as` оператора [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with), если таковые имеются.6263В момент, где генератор делает yield, выполняется блок, вложенный в оператор [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with). Затем генератор возобновляется после выхода из блока. Если в блоке возникает необработанное исключение, оно повторно возбуждается внутри генератора в точке, где произошел yield. Таким образом, можно использовать оператор [`try`](https://python-all.ru/3.11/reference/compound_stmts.html#try)…[`except`](https://python-all.ru/3.11/reference/compound_stmts.html#except)…[`finally`](https://python-all.ru/3.11/reference/compound_stmts.html#finally) для перехвата ошибки (если есть) или для выполнения очистки. Если исключение перехватывается только для того, чтобы зарегистрировать его или выполнить какое-либо действие (а не подавить полностью), генератор должен повторно возбудить это исключение. В противном случае контекстный менеджер генератора сообщит оператору `with`, что исключение обработано, и выполнение продолжится с оператора, следующего сразу за оператором `with`.6465[`contextmanager()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.contextmanager) использует [`ContextDecorator`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ContextDecorator), поэтому создаваемые им контекстные менеджеры могут использоваться как в качестве декораторов, так и в операторах [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with). При использовании в качестве декоратора для каждого вызова функции неявно создается новый экземпляр генератора (это позволяет в противном случае «одноразовым» контекстным менеджерам, созданным с помощью [`contextmanager()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.contextmanager), соответствовать требованию, согласно которому контекстные менеджеры должны поддерживать многократные вызовы, чтобы их можно было использовать в качестве декораторов).6667Изменено в версии 3.2: Использование [`ContextDecorator`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ContextDecorator).6869#### `@contextlib.asynccontextmanager`7071> Аналог [`contextmanager()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.contextmanager), но создает [асинхронный контекстный менеджер](https://python-all.ru/3.11/reference/datamodel.html#async-context-managers).72>73> Эта функция – [декоратор](https://python-all.ru/3.11/glossary.html#term-decorator), который можно использовать для определения фабричной функции для асинхронных контекстных менеджеров оператора [`async with`](https://python-all.ru/3.11/reference/compound_stmts.html#async-with), без необходимости создавать класс или отдельные методы [`__aenter__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__aenter__) и [`__aexit__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__aexit__). Она должна применяться к функции [асинхронного генератора](https://python-all.ru/3.11/glossary.html#term-asynchronous-generator).74>75> Простой пример:76>77> ```python78> from contextlib import asynccontextmanager79>80> @asynccontextmanager81> async def get_connection():82>     conn = await acquire_db_connection()83>     try:84>         yield conn85>     finally:86>         await release_db_connection(conn)87>88> async def get_all_users():89>     async with get_connection() as conn:90>         return conn.query('SELECT ...')91> ```92>93> Добавлено в версии 3.7.94>95> Контекстные менеджеры, определенные с помощью [`asynccontextmanager()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.asynccontextmanager), могут использоваться как в качестве декораторов, так и с операторами [`async with`](https://python-all.ru/3.11/reference/compound_stmts.html#async-with):96>97> ```python98> import time99> from contextlib import asynccontextmanager100>101> @asynccontextmanager102> async def timeit():103>     now = time.monotonic()104>     try:105>         yield106>     finally:107>         print(f'it took {time.monotonic() - now}s to run')108>109> @timeit()110> async def main():111>     # ... асинхронный код ...112> ```113>114> При использовании в качестве декоратора для каждого вызова функции неявно создается новый экземпляр генератора. Это позволяет в противном случае «одноразовым» контекстным менеджерам, созданным с помощью [`asynccontextmanager()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.asynccontextmanager), соответствовать требованию, согласно которому контекстные менеджеры должны поддерживать многократные вызовы, чтобы их можно было использовать в качестве декораторов.115116Изменено в версии 3.10: Асинхронные контекстные менеджеры, созданные с помощью [`asynccontextmanager()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.asynccontextmanager), могут использоваться в качестве декораторов.117118#### `contextlib.closing(thing)`119120Возвращает контекстный менеджер, который закрывает *thing* после завершения блока. По сути эквивалентно следующему:121122```python123from contextlib import contextmanager124125@contextmanager126def closing(thing):127    try:128        yield thing129    finally:130        thing.close()131```132133И позволяет писать код следующим образом:134135```python136from contextlib import closing137from urllib.request import urlopen138139with closing(urlopen('https://www.python.org')) as page:140    for line in page:141        print(line)142```143144без необходимости явно закрывать `page`. Даже если произойдет ошибка, `page.close()` будет вызван при выходе из блока [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with).145146> **Примечание**147>148> Большинство типов, управляющих ресурсами, поддерживают протокол [контекстного менеджера](https://python-all.ru/3.11/glossary.html#term-context-manager), который закрывает *thing* при выходе из оператора [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with). Поэтому `closing()` наиболее полезен для сторонних типов, не поддерживающих контекстные менеджеры. Этот пример приведен только для иллюстрации, поскольку [`urlopen()`](https://python-all.ru/3.11/library/urllib.request.html#urllib.request.urlopen) обычно используется в контекстном менеджере.149150#### `contextlib.aclosing(thing)`151152Возвращает асинхронный контекстный менеджер, который вызывает метод `aclose()` объекта *thing* после завершения блока. По сути эквивалентно следующему:153154```python155from contextlib import asynccontextmanager156157@asynccontextmanager158async def aclosing(thing):159    try:160        yield thing161    finally:162        await thing.aclose()163```164165Примечательно, что `aclosing()` поддерживает детерминированную очистку асинхронных генераторов, когда они завершаются досрочно из-за [`break`](https://python-all.ru/3.11/reference/simple_stmts.html#break) или исключения. Например:166167```python168from contextlib import aclosing169170async with aclosing(my_generator()) as values:171    async for value in values:172        if value == 42:173            break174```175176Этот шаблон гарантирует, что асинхронный код выхода генератора выполняется в том же контексте, что и его итерации (чтобы исключения и контекстные переменные работали как ожидается, а код выхода не выполнялся после завершения времени жизни задачи, от которой он зависит).177178Новое в версии 3.10.179180#### `contextlib.nullcontext(enter_result=None)`181182Возвращает менеджер контекста, который возвращает *enter\_result* из `__enter__`, но в остальном ничего не делает. Предназначен для использования в качестве замены опционального менеджера контекста, например:183184```python185def myfunction(arg, ignore_exceptions=False):186    if ignore_exceptions:187        # Используйте suppress, чтобы игнорировать все исключения.188        cm = contextlib.suppress(Exception)189    else:190        # Не игнорируйте никакие исключения, cm не оказывает эффекта.191        cm = contextlib.nullcontext()192    with cm:193        # Выполнить действие194```195196Пример использования *enter\_result*:197198```python199def process_file(file_or_path):200    if isinstance(file_or_path, str):201        # Если строка, открыть файл202        cm = open(file_or_path)203    else:204        # Вызывающий отвечает за закрытие файла205        cm = nullcontext(file_or_path)206207    with cm as file:208        # Выполнить обработку файла209```210211Его также можно использовать в качестве замены [асинхронных менеджеров контекста](https://python-all.ru/3.11/reference/datamodel.html#async-context-managers):212213```python214async def send_http(session=None):215    if not session:216        # Если нет http-сессии, создать её с помощью aiohttp217        cm = aiohttp.ClientSession()218    else:219        # Вызывающий отвечает за закрытие сессии220        cm = nullcontext(session)221222    async with cm as session:223        # Отправить http-запросы с помощью сессии224```225226Добавлено в версии 3.7.227228Изменено в версии 3.10: добавлена поддержка [асинхронного менеджера контекста](https://python-all.ru/3.11/glossary.html#term-asynchronous-context-manager).229230#### `contextlib.suppress(*exceptions)`231232Возвращает менеджер контекста, который подавляет любые из указанных исключений, если они возникают в теле оператора `with`, а затем возобновляет выполнение с первого оператора после завершения оператора `with`.233234Как и любой другой механизм, полностью подавляющий исключения, этот менеджер контекста следует использовать только для обработки очень специфических ошибок, когда молчаливое продолжение выполнения программы является правильным решением.235236Например:237238```python239from contextlib import suppress240241with suppress(FileNotFoundError):242    os.remove('somefile.tmp')243244with suppress(FileNotFoundError):245    os.remove('someotherfile.tmp')246```247248Этот код эквивалентен:249250```python251try:252    os.remove('somefile.tmp')253except FileNotFoundError:254    pass255256try:257    os.remove('someotherfile.tmp')258except FileNotFoundError:259    pass260```261262Этот менеджер контекста является [реентерабельным](https://python-all.ru/3.11/library/contextlib.html#reentrant-cms).263264Новое в версии 3.4.265266#### `contextlib.redirect_stdout(new_target)`267268Менеджер контекста для временного перенаправления [`sys.stdout`](https://python-all.ru/3.11/library/sys.html#sys.stdout) в другой файл или файлоподобный объект.269270Этот инструмент добавляет гибкость существующим функциям или классам, чей вывод жестко привязан к stdout.271272Например, вывод [`help()`](https://python-all.ru/3.11/library/functions.html#help) обычно отправляется в *sys.stdout*. Этот вывод можно захватить в строку, перенаправив его на объект [`io.StringIO`](https://python-all.ru/3.11/library/io.html#io.StringIO). Заменяющий поток данных возвращается из метода `__enter__` и поэтому доступен как цель оператора [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with):273274```python275with redirect_stdout(io.StringIO()) as f:276    help(pow)277s = f.getvalue()278```279280Чтобы отправить вывод [`help()`](https://python-all.ru/3.11/library/functions.html#help) в файл на диске, перенаправьте вывод в обычный файл:281282```python283with open('help.txt', 'w') as f:284    with redirect_stdout(f):285        help(pow)286```287288Чтобы отправить вывод [`help()`](https://python-all.ru/3.11/library/functions.html#help) в *sys.stderr*:289290```python291with redirect_stdout(sys.stderr):292    help(pow)293```294295Обратите внимание, что глобальный побочный эффект на [`sys.stdout`](https://python-all.ru/3.11/library/sys.html#sys.stdout) означает, что этот менеджер контекста не подходит для использования в библиотечном коде и большинстве многопоточных приложений. Он также не влияет на вывод подпроцессов. Тем не менее, это всё ещё полезный подход для многих вспомогательных скриптов.296297Этот менеджер контекста является [реентерабельным](https://python-all.ru/3.11/library/contextlib.html#reentrant-cms).298299Новое в версии 3.4.300301#### `contextlib.redirect_stderr(new_target)`302303Аналогично [`redirect_stdout()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.redirect_stdout), но перенаправляет [`sys.stderr`](https://python-all.ru/3.11/library/sys.html#sys.stderr) в другой файл или файлоподобный объект.304305Этот менеджер контекста является [реентерабельным](https://python-all.ru/3.11/library/contextlib.html#reentrant-cms).306307Новое в версии 3.5.308309#### `contextlib.chdir(path)`310311Менеджер контекста, небезопасный для параллельного использования, для смены текущей рабочей директории. Поскольку это меняет глобальное состояние – рабочую директорию, он не подходит для использования в большинстве многопоточных или асинхронных контекстов. Также он не подходит для нелинейного выполнения кода, например, генераторов, где выполнение программы временно приостанавливается – если только это не требуется явно, не следует выполнять yield, пока этот менеджер контекста активен.312313Это простая обёртка вокруг [`chdir()`](https://python-all.ru/3.11/library/os.html#os.chdir): она меняет текущую рабочую директорию при входе и восстанавливает предыдущую при выходе.314315Этот менеджер контекста является [реентерабельным](https://python-all.ru/3.11/library/contextlib.html#reentrant-cms).316317Новое в версии 3.11.318319#### `class contextlib.ContextDecorator`320321Базовый класс, который позволяет менеджеру контекста также использоваться в качестве декоратора.322323Менеджеры контекста, наследующие от `ContextDecorator`, должны обычным образом реализовывать `__enter__` и `__exit__`. `__exit__` сохраняет необязательную обработку исключений даже при использовании в качестве декоратора.324325`ContextDecorator` используется [`contextmanager()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.contextmanager), поэтому эта функциональность доступна автоматически.326327Пример `ContextDecorator`:328329```python330from contextlib import ContextDecorator331332class mycontext(ContextDecorator):333    def __enter__(self):334        print('Starting')335        return self336337    def __exit__(self, *exc):338        print('Finishing')339        return False340```341342Затем класс можно использовать следующим образом:343344```python345>>> @mycontext()346... def function():347...     print('The bit in the middle')348...349>>> function()350Starting351The bit in the middle352Finishing353354>>> with mycontext():355...     print('The bit in the middle')356...357Starting358The bit in the middle359Finishing360```361362Это изменение – всего лишь синтаксический сахар для любой конструкции следующего вида:363364```python365def f():366    with cm():367        # Выполнить действия368```369370`ContextDecorator` позволяет вместо этого писать:371372```python373@cm()374def f():375    # Выполнить действия376```377378Становится ясно, что `cm` применяется ко всей функции, а не только к её части (и экономия уровня отступа тоже приятна).379380Существующие менеджеры контекста, уже имеющие базовый класс, можно расширить, используя `ContextDecorator` в качестве примеси (mixin):381382```python383from contextlib import ContextDecorator384385class mycontext(ContextBaseClass, ContextDecorator):386    def __enter__(self):387        return self388389    def __exit__(self, *exc):390        return False391```392393> **Примечание**394>395> Поскольку декорированная функция должна допускать многократный вызов, нижележащий менеджер контекста должен поддерживать использование в нескольких операторах [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with). Если это не так, следует использовать исходную конструкцию с явным оператором `with` внутри функции.396397Новое в версии 3.2.398399#### `class contextlib.AsyncContextDecorator`400401Аналогично [`ContextDecorator`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ContextDecorator), но только для асинхронных функций.402403Пример `AsyncContextDecorator`:404405```python406from asyncio import run407from contextlib import AsyncContextDecorator408409class mycontext(AsyncContextDecorator):410    async def __aenter__(self):411        print('Starting')412        return self413414    async def __aexit__(self, *exc):415        print('Finishing')416        return False417```418419Затем класс можно использовать следующим образом:420421```python422>>> @mycontext()423... async def function():424...     print('The bit in the middle')425...426>>> run(function())427Starting428The bit in the middle429Finishing430431>>> async def function():432...    async with mycontext():433...         print('The bit in the middle')434...435>>> run(function())436Starting437The bit in the middle438Finishing439```440441Новое в версии 3.10.442443#### `class contextlib.ExitStack`444445Менеджер контекста, предназначенный для упрощения программного комбинирования других менеджеров контекста и функций очистки, особенно тех, которые являются необязательными или определяются входными данными.446447Например, набор файлов можно легко обработать в одном операторе with следующим образом:448449```python450with ExitStack() as stack:451    files = [stack.enter_context(open(fname)) for fname in filenames]452    # Все открытые файлы будут автоматически закрыты в конце453    # оператор with, даже если попытки открыть файлы, идущие далее454    # в списке, вызывают исключение455```456457Метод [`__enter__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__enter__) возвращает экземпляр [`ExitStack`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack) и не выполняет никаких дополнительных операций.458459Каждый экземпляр поддерживает стек зарегистрированных колбэков, которые вызываются в обратном порядке при закрытии экземпляра (явно или неявно в конце оператора [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with)). Обратите внимание, что колбэки *не* вызываются неявно при сборке мусора экземпляра стека контекста.460461Такая стековая модель используется, чтобы менеджеры контекста, получающие свои ресурсы в методе `__init__` (например, файловые объекты), могли обрабатываться корректно.462463Поскольку зарегистрированные колбэки вызываются в порядке, обратном регистрации, в итоге это ведёт себя так, как если бы с зарегистрированным набором колбэков использовалось несколько вложенных операторов [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with). Это распространяется даже на обработку исключений: если внутренний колбэк подавляет или заменяет исключение, то внешним колбэкам будут переданы аргументы, основанные на этом обновлённом состоянии.464465Это относительно низкоуровневый API, который заботится о деталях корректной размотки стека колбэков выхода. Он предоставляет подходящую основу для менеджеров контекста более высокого уровня, которые манипулируют стеком выхода специфичным для приложения образом.466467Новое в версии 3.3.468469#### `enter_context(cm)`470471Входит в новый менеджер контекста и добавляет его метод [`__exit__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__exit__) в стек колбэков. Возвращаемое значение – результат собственного метода [`__enter__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__enter__) менеджера контекста.472473Эти менеджеры контекста могут подавлять исключения точно так же, как они это делали бы при непосредственном использовании в операторе [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with).474475Изменено в версии 3.11: Возбуждает [`TypeError`](https://python-all.ru/3.11/library/exceptions.html#TypeError) вместо [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError), если *cm* не является менеджером контекста.476477#### `push(exit)`478479Добавляет метод [`__exit__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__exit__) менеджера контекста в стек колбэков.480481Поскольку `__enter__` *не* вызывается, этот метод можно использовать для покрытия части реализации [`__enter__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__enter__) собственным методом [`__exit__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__exit__) менеджера контекста.482483Если передан объект, не являющийся менеджером контекста, этот метод считает его колбэком с той же сигнатурой, что и метод [`__exit__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__exit__) менеджера контекста, и добавляет его напрямую в стек колбэков.484485Возвращая истинные значения, эти колбэки могут подавлять исключения так же, как это делают методы [`__exit__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__exit__) менеджеров контекста.486487Переданный объект возвращается из функции, что позволяет использовать этот метод в качестве декоратора функции.488489#### `callback(callback, /, *args, **kwds)`490491Принимает произвольную функцию-колбэк и аргументы и добавляет её в стек колбэков.492493В отличие от других методов, колбэки, добавленные таким образом, не могут подавлять исключения (поскольку им никогда не передаются сведения об исключении).494495Переданный колбэк возвращается из функции, что позволяет использовать этот метод в качестве декоратора функции.496497#### `pop_all()`498499Перемещает стек колбэков в новый экземпляр [`ExitStack`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack) и возвращает его. При этой операции колбэки не вызываются – вместо этого они будут вызваны при закрытии нового стека (явно или неявно в конце оператора [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with)).500501Например, группу файлов можно открыть как операцию «всё или ничего» следующим образом:502503```python504with ExitStack() as stack:505    files = [stack.enter_context(open(fname)) for fname in filenames]506    # Сохраните метод close, но пока не вызывайте его.507    close_files = stack.pop_all().close508    # Если открытие любого файла завершается неудачей, все ранее открытые файлы будут509    # закрыты автоматически. Если все файлы открыты успешно,510    # они останутся открытыми даже после завершения оператора with.511    # close_files() затем можно вызвать явно, чтобы закрыть их все.512```513514#### `close()`515516Немедленно разворачивает стек колбэков, вызывая колбэки в порядке, обратном регистрации. Для любых зарегистрированных менеджеров контекста и колбэков выхода переданные аргументы будут указывать, что исключения не произошло.517518#### `class contextlib.AsyncExitStack`519520[Асинхронный менеджер контекста](https://python-all.ru/3.11/reference/datamodel.html#async-context-managers), аналогичный [`ExitStack`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack), который поддерживает объединение как синхронных, так и асинхронных менеджеров контекста, а также имеет корутины для логики очистки.521522Метод [`close()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack.close) не реализован; вместо него следует использовать [`aclose()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.AsyncExitStack.aclose).523524#### `coroutine enter_async_context(cm)`525526Аналогично [`ExitStack.enter_context()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack.enter_context), но ожидает асинхронный менеджер контекста.527528Изменено в версии 3.11: Вызывает [`TypeError`](https://python-all.ru/3.11/library/exceptions.html#TypeError) вместо [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError), если *cm* не является асинхронным менеджером контекста.529530#### `push_async_exit(exit)`531532Аналогично [`ExitStack.push()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack.push), но ожидает либо асинхронный менеджер контекста, либо корутинную функцию.533534#### `push_async_callback(callback, /, *args, **kwds)`535536Аналогично [`ExitStack.callback()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack.callback), но ожидает корутинную функцию.537538#### `coroutine aclose()`539540Аналогично [`ExitStack.close()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack.close), но корректно обрабатывает ожидаемые объекты.541542Продолжая пример для [`asynccontextmanager()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.asynccontextmanager):543544```python545async with AsyncExitStack() as stack:546    connections = [await stack.enter_async_context(get_connection())547        for i in range(5)]548    # Все открытые соединения будут автоматически освобождены в конце549    # оператора async with, даже если попытки открыть соединение550    # далее в списке вызывают исключение.551```552553Добавлено в версии 3.7.554555## Примеры и рецепты556557В этом разделе описаны некоторые примеры и рецепты для эффективного использования инструментов, предоставляемых [`contextlib`](https://python-all.ru/3.11/library/contextlib.html#module-contextlib).558559### Поддержка переменного числа менеджеров контекста560561Основной вариант использования [`ExitStack`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack) – это тот, что описан в документации класса: поддержка переменного числа менеджеров контекста и других операций очистки в одном операторе [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with). Переменность может быть обусловлена тем, что количество необходимых менеджеров контекста определяется пользовательским вводом (например, открытие указанной пользователем коллекции файлов), или тем, что некоторые менеджеры контекста являются необязательными:562563```python564with ExitStack() as stack:565    for resource in resources:566        stack.enter_context(resource)567    if need_special_resource():568        special = acquire_special_resource()569        stack.callback(release_special_resource, special)570    # Выполните операции, использующие полученные ресурсы571```572573Как показано, [`ExitStack`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack) также значительно упрощает использование операторов [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with) для управления произвольными ресурсами, которые изначально не поддерживают протокол управления контекстом.574575### Перехват исключений из методов `__enter__`576577Иногда бывает желательно перехватывать исключения из реализации метода `__enter__`, *не* перехватывая случайно исключения из тела оператора [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with) или метода `__exit__` менеджера контекста. Используя [`ExitStack`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack), можно немного разделить шаги протокола управления контекстом, чтобы это стало возможным:578579```python580stack = ExitStack()581try:582    x = stack.enter_context(cm)583except Exception:584    # обработать исключение __enter__585else:586    with stack:587        # Обработка нормального случая588```589590Необходимость в этом, скорее всего, указывает на то, что базовый API должен предоставлять прямой интерфейс управления ресурсами для использования с операторами [`try`](https://python-all.ru/3.11/reference/compound_stmts.html#try)/[`except`](https://python-all.ru/3.11/reference/compound_stmts.html#except)/[`finally`](https://python-all.ru/3.11/reference/compound_stmts.html#finally), но не все API хорошо спроектированы в этом отношении. Когда менеджер контекста является единственным предоставляемым API управления ресурсами, тогда [`ExitStack`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack) может упростить обработку различных ситуаций, которые невозможно обработать напрямую в операторе [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with).591592### Очистка в реализации `__enter__`593594Как отмечено в документации [`ExitStack.push()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack.push), этот метод может быть полезен для очистки уже выделенного ресурса, если последующие шаги в реализации [`__enter__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__enter__) завершатся неудачей.595596Вот пример реализации этого для менеджера контекста, который принимает функции захвата и освобождения ресурса, а также опциональную функцию проверки, и отображает их на протокол управления контекстом:597598```python599from contextlib import contextmanager, AbstractContextManager, ExitStack600601class ResourceManager(AbstractContextManager):602603    def __init__(self, acquire_resource, release_resource, check_resource_ok=None):604        self.acquire_resource = acquire_resource605        self.release_resource = release_resource606        if check_resource_ok is None:607            def check_resource_ok(resource):608                return True609        self.check_resource_ok = check_resource_ok610611    @contextmanager612    def _cleanup_on_error(self):613        with ExitStack() as stack:614            stack.push(self)615            yield616            # Проверка прошла успешно и не вызвала исключение617            # Соответственно, мы хотим сохранить ресурс и передать его618            # обратно вызывающему коду619            stack.pop_all()620621    def __enter__(self):622        resource = self.acquire_resource()623        with self._cleanup_on_error():624            if not self.check_resource_ok(resource):625                msg = "Failed validation for {!r}"626                raise RuntimeError(msg.format(resource))627        return resource628629    def __exit__(self, *exc_details):630        # Нам не нужно дублировать логику освобождения ресурсов631        self.release_resource()632```633634### Замена любого использования `try-finally` и флаговых переменных635636Иногда встречается шаблон, в котором используется инструкция `try-finally` с переменной-флагом, указывающей, должно ли выполняться тело предложения `finally`. В простейшей форме (если это нельзя обработать простым использованием предложения `except`) это выглядит примерно так:637638```python639cleanup_needed = True640try:641    result = perform_operation()642    if result:643        cleanup_needed = False644finally:645    if cleanup_needed:646        cleanup_resources()647```648649Как и в любом коде, основанном на инструкции `try`, это может вызвать проблемы при разработке и рецензировании, поскольку код настройки и код очистки могут оказаться разделенными произвольно длинными участками кода.650651[`ExitStack`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack) позволяет вместо этого зарегистрировать колбэк для выполнения в конце инструкции `with`, а затем позже решить пропустить выполнение этого колбэка:652653```python654from contextlib import ExitStack655656with ExitStack() as stack:657    stack.callback(cleanup_resources)658    result = perform_operation()659    if result:660        stack.pop_all()661```662663Это позволяет заранее явно указать предполагаемое поведение очистки, вместо того чтобы требовать отдельную переменную-флаг.664665Если конкретное приложение часто использует этот шаблон, его можно упростить еще больше с помощью небольшого вспомогательного класса:666667```python668from contextlib import ExitStack669670class Callback(ExitStack):671    def __init__(self, callback, /, *args, **kwds):672        super().__init__()673        self.callback(callback, *args, **kwds)674675    def cancel(self):676        self.pop_all()677678with Callback(cleanup_resources) as cb:679    result = perform_operation()680    if result:681        cb.cancel()682```683684Если очистка ресурсов уже не аккуратно оформлена в виде отдельной функции, то все равно можно использовать форму декоратора [`ExitStack.callback()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack.callback), чтобы объявить очистку ресурсов заранее:685686```python687from contextlib import ExitStack688689with ExitStack() as stack:690    @stack.callback691    def cleanup_resources():692        ...693    result = perform_operation()694    if result:695        stack.pop_all()696```697698Из-за того, как работает протокол декоратора, функция обратного вызова, объявленная таким образом, не может принимать никаких параметров. Вместо этого любые ресурсы, которые необходимо освободить, должны быть доступны как переменные замыкания.699700### Использование менеджера контекста в качестве декоратора функции701702[`ContextDecorator`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ContextDecorator) позволяет использовать менеджер контекста как в обычной инструкции `with`, так и в качестве декоратора функции.703704Например, иногда полезно оборачивать функции или группы инструкций в логгер, который может отслеживать время входа и время выхода. Вместо написания как декоратора функции, так и менеджера контекста для этой задачи, наследование от [`ContextDecorator`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ContextDecorator) предоставляет обе возможности в одном определении:705706```python707from contextlib import ContextDecorator708import logging709710logging.basicConfig(level=logging.INFO)711712class track_entry_and_exit(ContextDecorator):713    def __init__(self, name):714        self.name = name715716    def __enter__(self):717        logging.info('Entering: %s', self.name)718719    def __exit__(self, exc_type, exc, exc_tb):720        logging.info('Exiting: %s', self.name)721```722723Экземпляры этого класса можно использовать как менеджер контекста:724725```python726with track_entry_and_exit('widget loader'):727    print('Some time consuming activity goes here')728    load_widget()729```730731А также как декоратор функции:732733```python734@track_entry_and_exit('widget loader')735def activity():736    print('Some time consuming activity goes here')737    load_widget()738```739740Обратите внимание, что есть одно дополнительное ограничение при использовании менеджеров контекста в качестве декораторов функций: невозможно получить доступ к возвращаемому значению [`__enter__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__enter__). Если это значение необходимо, то все равно нужно использовать явную инструкцию `with`.741742> **См. также**743>744> **[**PEP 343**](https://python-all.ru/3.11/library/contextlib.html) – Оператор «with»**745>746> Спецификация, предыстория и примеры для инструкции [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with) в Python.747748## Одноразовые, многократно используемые и реентерабельные менеджеры контекста749750Большинство менеджеров контекста написаны таким образом, что их можно эффективно использовать только один раз в инструкции [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with). Эти одноразовые менеджеры контекста должны создаваться заново каждый раз при использовании – попытка использовать их второй раз вызовет исключение или иным образом приведет к некорректной работе.751752Это распространенное ограничение означает, что обычно рекомендуется создавать менеджеры контекста непосредственно в заголовке инструкции [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with), где они используются (как показано во всех примерах использования выше).753754Файлы являются примером эффективно одноразовых менеджеров контекста, поскольку первая инструкция [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with) закроет файл, предотвращая любые дальнейшие операции ввода-вывода с использованием этого объекта файла.755756Менеджеры контекста, созданные с помощью [`contextmanager()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.contextmanager), также являются одноразовыми менеджерами контекста и будут сообщать об ошибке, если базовый генератор не сможет выполнить yield при попытке использовать их второй раз:757758```python759>>> from contextlib import contextmanager760>>> @contextmanager761... def singleuse():762...     print("Before")763...     yield764...     print("After")765...766>>> cm = singleuse()767>>> with cm:768...     pass769...770Before771After772>>> with cm:773...     pass774...775Traceback (most recent call last):776    ...777RuntimeError: generator didn't yield778```779780### Реентерабельные менеджеры контекста781782Более сложные менеджеры контекста могут быть «реентерабельными». Такие менеджеры контекста можно использовать не только в нескольких инструкциях [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with), но также *внутри* инструкции `with`, которая уже использует тот же менеджер контекста.783784[`threading.RLock`](https://python-all.ru/3.11/library/threading.html#threading.RLock) является примером реентерабельного менеджера контекста, как и [`suppress()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.suppress), [`redirect_stdout()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.redirect_stdout) и [`chdir()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.chdir). Вот очень простой пример реентерабельного использования:785786```python787>>> from contextlib import redirect_stdout788>>> from io import StringIO789>>> stream = StringIO()790>>> write_to_stream = redirect_stdout(stream)791>>> with write_to_stream:792...     print("This is written to the stream rather than stdout")793...     with write_to_stream:794...         print("This is also written to the stream")795...796>>> print("This is written directly to stdout")797This is written directly to stdout798>>> print(stream.getvalue())799This is written to the stream rather than stdout800This is also written to the stream801```802803Реальные примеры реентерабельности, скорее всего, будут включать несколько функций, вызывающих друг друга, и, следовательно, будут гораздо сложнее этого примера.804805Также обратите внимание, что быть реентерабельным – это *не* то же самое, что быть потокобезопасным. [`redirect_stdout()`](https://python-all.ru/3.11/library/contextlib.html#contextlib.redirect_stdout), например, определенно не является потокобезопасным, так как он вносит глобальное изменение в состояние системы, привязывая [`sys.stdout`](https://python-all.ru/3.11/library/sys.html#sys.stdout) к другому потоку данных.806807### Многократно используемые менеджеры контекста808809Отличающиеся от одноразовых и реентерабельных менеджеров контекста – «многократно используемые» менеджеры контекста (или, если быть совсем точным, «многократно используемые, но не реентерабельные» менеджеры контекста, поскольку реентерабельные менеджеры контекста также являются многократно используемыми). Эти менеджеры контекста поддерживают многократное использование, но завершатся ошибкой (или иным образом будут работать некорректно), если конкретный экземпляр менеджера контекста уже был использован во внешней инструкции with.810811[`threading.Lock`](https://python-all.ru/3.11/library/threading.html#threading.Lock) является примером многократно используемого, но не реентерабельного менеджера контекста (для реентерабельной блокировки необходимо использовать [`threading.RLock`](https://python-all.ru/3.11/library/threading.html#threading.RLock) вместо этого).812813Другим примером многократно используемого, но не реентерабельного менеджера контекста является [`ExitStack`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack), так как он вызывает *все* зарегистрированные в данный момент колбэки при выходе из любой инструкции with, независимо от того, где эти колбэки были добавлены:814815```python816>>> from contextlib import ExitStack817>>> stack = ExitStack()818>>> with stack:819...     stack.callback(print, "Callback: from first context")820...     print("Leaving first context")821...822Leaving first context823Callback: from first context824>>> with stack:825...     stack.callback(print, "Callback: from second context")826...     print("Leaving second context")827...828Leaving second context829Callback: from second context830>>> with stack:831...     stack.callback(print, "Callback: from outer context")832...     with stack:833...         stack.callback(print, "Callback: from inner context")834...         print("Leaving inner context")835...     print("Leaving outer context")836...837Leaving inner context838Callback: from inner context839Callback: from outer context840Leaving outer context841```842843Как показывает вывод примера, повторное использование одного объекта стека в нескольких инструкциях with работает корректно, но попытка вложить их приведет к очистке стека в конце самой внутренней инструкции with, что вряд ли является желательным поведением.844845Использование отдельных экземпляров [`ExitStack`](https://python-all.ru/3.11/library/contextlib.html#contextlib.ExitStack) вместо повторного использования одного экземпляра позволяет избежать этой проблемы:846847```python848>>> from contextlib import ExitStack849>>> with ExitStack() as outer_stack:850...     outer_stack.callback(print, "Callback: from outer context")851...     with ExitStack() as inner_stack:852...         inner_stack.callback(print, "Callback: from inner context")853...         print("Leaving inner context")854...     print("Leaving outer context")855...856Leaving inner context857Callback: from inner context858Leaving outer context859Callback: from outer context860```861