`contextlib.md`

865 строк · 60.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3/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.14/Lib/contextlib.py)1011---1213Этот модуль предоставляет утилиты для типовых задач, связанных с оператором [`with`](https://python-all.ru/3/reference/compound_stmts.html#with). Для получения дополнительной информации см. также [Типы менеджеров контекста](https://python-all.ru/3/library/stdtypes.html#typecontextmanager) и [Менеджеры контекста оператора with](https://python-all.ru/3/reference/datamodel.html#context-managers).1415## Утилиты1617Предоставляемые функции и классы:1819#### `class contextlib.AbstractContextManager`2021[абстрактный базовый класс](https://python-all.ru/3/glossary.html#term-abstract-base-class) для классов, реализующих [`__enter__()`](https://python-all.ru/3/reference/datamodel.html#object.__enter__) и [`__exit__()`](https://python-all.ru/3/reference/datamodel.html#object.__exit__). Предоставляется реализация по умолчанию для `__enter__()`, которая возвращает `self`, а `__exit__()` – это абстрактный метод, который по умолчанию возвращает `None`. См. также определение [Типов менеджеров контекста](https://python-all.ru/3/library/stdtypes.html#typecontextmanager).2223Добавлено в версии 3.6.2425#### `class contextlib.AbstractAsyncContextManager`2627[абстрактный базовый класс](https://python-all.ru/3/glossary.html#term-abstract-base-class) для классов, реализующих [`__aenter__()`](https://python-all.ru/3/reference/datamodel.html#object.__aenter__) и [`__aexit__()`](https://python-all.ru/3/reference/datamodel.html#object.__aexit__). Предоставляется реализация по умолчанию для `__aenter__()`, которая возвращает `self`, а `__aexit__()` – это абстрактный метод, который по умолчанию возвращает `None`. См. также определение [Асинхронных менеджеров контекста](https://python-all.ru/3/reference/datamodel.html#async-context-managers).2829Добавлено в версии 3.7.3031#### `@contextlib.contextmanager`3233Эта функция – [декоратор](https://python-all.ru/3/glossary.html#term-decorator), который можно использовать для определения фабричной функции для контекстных менеджеров оператора [`with`](https://python-all.ru/3/reference/compound_stmts.html#with), без необходимости создавать класс или отдельные методы [`__enter__()`](https://python-all.ru/3/reference/datamodel.html#object.__enter__) и [`__exit__()`](https://python-all.ru/3/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/glossary.html#term-generator)-итератор. Этот итератор должен возвращать ровно одно значение, которое будет связано с целями в предложении `as` оператора [`with`](https://python-all.ru/3/reference/compound_stmts.html#with), если таковые имеются.6263В момент, где генератор делает yield, выполняется блок, вложенный в оператор [`with`](https://python-all.ru/3/reference/compound_stmts.html#with). Затем генератор возобновляется после выхода из блока. Если в блоке возникает необработанное исключение, оно повторно возбуждается внутри генератора в точке, где произошел yield. Таким образом, можно использовать оператор [`try`](https://python-all.ru/3/reference/compound_stmts.html#try)…[`except`](https://python-all.ru/3/reference/compound_stmts.html#except)…[`finally`](https://python-all.ru/3/reference/compound_stmts.html#finally) для перехвата ошибки (если есть) или для выполнения очистки. Если исключение перехватывается только для того, чтобы зарегистрировать его или выполнить какое-либо действие (а не подавить полностью), генератор должен повторно возбудить это исключение. В противном случае контекстный менеджер генератора сообщит оператору `with`, что исключение обработано, и выполнение продолжится с оператора, следующего сразу за оператором `with`.6465`contextmanager()` использует [`ContextDecorator`](https://python-all.ru/3/library/contextlib.html#contextlib.ContextDecorator), поэтому создаваемые им контекстные менеджеры могут использоваться как в качестве декораторов, так и в операторах [`with`](https://python-all.ru/3/reference/compound_stmts.html#with). При использовании в качестве декоратора для каждого вызова функции неявно создается новый экземпляр генератора (это позволяет в противном случае «одноразовым» контекстным менеджерам, созданным с помощью `contextmanager()`, соответствовать требованию, согласно которому контекстные менеджеры должны поддерживать многократные вызовы, чтобы их можно было использовать в качестве декораторов).6667Изменено в версии 3.2: Использование [`ContextDecorator`](https://python-all.ru/3/library/contextlib.html#contextlib.ContextDecorator).6869#### `@contextlib.asynccontextmanager`7071Аналог [`contextmanager()`](https://python-all.ru/3/library/contextlib.html#contextlib.contextmanager), но создает [асинхронный контекстный менеджер](https://python-all.ru/3/reference/datamodel.html#async-context-managers).7273Эта функция – [декоратор](https://python-all.ru/3/glossary.html#term-decorator), который можно использовать для определения фабричной функции для асинхронных контекстных менеджеров оператора [`async with`](https://python-all.ru/3/reference/compound_stmts.html#async-with), без необходимости создавать класс или отдельные методы [`__aenter__()`](https://python-all.ru/3/reference/datamodel.html#object.__aenter__) и [`__aexit__()`](https://python-all.ru/3/reference/datamodel.html#object.__aexit__). Она должна применяться к функции [асинхронного генератора](https://python-all.ru/3/glossary.html#term-asynchronous-generator).7475Простой пример:7677```python78from contextlib import asynccontextmanager7980@asynccontextmanager81async def get_connection():82    conn = await acquire_db_connection()83    try:84        yield conn85    finally:86        await release_db_connection(conn)8788async def get_all_users():89    async with get_connection() as conn:90        return conn.query('SELECT ...')91```9293Добавлено в версии 3.7.9495Контекстные менеджеры, определенные с помощью `asynccontextmanager()`, могут использоваться как в качестве декораторов, так и с операторами [`async with`](https://python-all.ru/3/reference/compound_stmts.html#async-with):9697```python98import time99from contextlib import asynccontextmanager100101@asynccontextmanager102async def timeit():103    now = time.monotonic()104    try:105        yield106    finally:107        print(f'it took {time.monotonic() - now}s to run')108109@timeit()110async def main():111    # ... асинхронный код ...112```113114При использовании в качестве декоратора для каждого вызова функции неявно создается новый экземпляр генератора. Это позволяет в противном случае «одноразовым» контекстным менеджерам, созданным с помощью `asynccontextmanager()`, соответствовать требованию, согласно которому контекстные менеджеры должны поддерживать многократные вызовы, чтобы их можно было использовать в качестве декораторов.115116Изменено в версии 3.10: Асинхронные контекстные менеджеры, созданные с помощью `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/reference/compound_stmts.html#with).145146> **Примечание**147>148> Большинство типов, управляющих ресурсами, поддерживают протокол [контекстного менеджера](https://python-all.ru/3/glossary.html#term-context-manager), который закрывает *thing* при выходе из оператора [`with`](https://python-all.ru/3/reference/compound_stmts.html#with). Поэтому `closing()` наиболее полезен для сторонних типов, не поддерживающих контекстные менеджеры. Этот пример приведен только для иллюстрации, поскольку [`urlopen()`](https://python-all.ru/3/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/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__()`](https://python-all.ru/3/reference/datamodel.html#object.__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/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/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/library/contextlib.html#reentrant-cms).263264Если код внутри блока `with` вызывает [`BaseExceptionGroup`](https://python-all.ru/3/library/exceptions.html#BaseExceptionGroup), подавленные исключения удаляются из группы. Любые исключения группы, которые не были подавлены, возбуждаются повторно в новой группе, созданной с помощью метода [`derive()`](https://python-all.ru/3/library/exceptions.html#BaseExceptionGroup.derive) исходной группы.265266Добавлено в версии 3.4.267268Изменено в версии 3.12: `suppress` теперь поддерживает подавление исключений, возбужденных в составе [`BaseExceptionGroup`](https://python-all.ru/3/library/exceptions.html#BaseExceptionGroup).269270#### `contextlib.redirect_stdout(new_target)`271272Менеджер контекста для временного перенаправления [`sys.stdout`](https://python-all.ru/3/library/sys.html#sys.stdout) в другой файл или файлоподобный объект.273274Этот инструмент добавляет гибкость существующим функциям или классам, чей вывод жестко привязан к stdout.275276Например, вывод [`help()`](https://python-all.ru/3/library/functions.html#help) обычно отправляется в *sys.stdout*. Этот вывод можно захватить в строку, перенаправив его на объект [`io.StringIO`](https://python-all.ru/3/library/io.html#io.StringIO). Заменяющий поток данных возвращается из метода [`__enter__()`](https://python-all.ru/3/reference/datamodel.html#object.__enter__) и поэтому доступен как цель оператора [`with`](https://python-all.ru/3/reference/compound_stmts.html#with):277278```python279with redirect_stdout(io.StringIO()) as f:280    help(pow)281s = f.getvalue()282```283284Чтобы отправить вывод [`help()`](https://python-all.ru/3/library/functions.html#help) в файл на диске, перенаправьте вывод в обычный файл:285286```python287with open('help.txt', 'w') as f:288    with redirect_stdout(f):289        help(pow)290```291292Чтобы отправить вывод [`help()`](https://python-all.ru/3/library/functions.html#help) в *sys.stderr*:293294```python295with redirect_stdout(sys.stderr):296    help(pow)297```298299Обратите внимание, что глобальный побочный эффект на [`sys.stdout`](https://python-all.ru/3/library/sys.html#sys.stdout) означает, что этот менеджер контекста не подходит для использования в библиотечном коде и большинстве многопоточных приложений. Он также не влияет на вывод подпроцессов. Тем не менее, это всё ещё полезный подход для многих вспомогательных скриптов.300301Этот менеджер контекста является [реентерабельным](https://python-all.ru/3/library/contextlib.html#reentrant-cms).302303Добавлено в версии 3.4.304305#### `contextlib.redirect_stderr(new_target)`306307Аналогично [`redirect_stdout()`](https://python-all.ru/3/library/contextlib.html#contextlib.redirect_stdout), но перенаправляет [`sys.stderr`](https://python-all.ru/3/library/sys.html#sys.stderr) в другой файл или файлоподобный объект.308309Этот менеджер контекста является [реентерабельным](https://python-all.ru/3/library/contextlib.html#reentrant-cms).310311Добавлено в версии 3.5.312313#### `contextlib.chdir(path)`314315Менеджер контекста, небезопасный для параллельного использования, для смены текущей рабочей директории. Поскольку это меняет глобальное состояние – рабочую директорию, он не подходит для использования в большинстве многопоточных или асинхронных контекстов. Также он не подходит для нелинейного выполнения кода, например, генераторов, где выполнение программы временно приостанавливается – если только это не требуется явно, не следует выполнять yield, пока этот менеджер контекста активен.316317Это простая обёртка вокруг [`chdir()`](https://python-all.ru/3/library/os.html#os.chdir): она меняет текущую рабочую директорию при входе и восстанавливает предыдущую при выходе.318319Этот менеджер контекста является [реентерабельным](https://python-all.ru/3/library/contextlib.html#reentrant-cms).320321Добавлено в версии 3.12.322323#### `class contextlib.ContextDecorator`324325Базовый класс, который позволяет менеджеру контекста также использоваться в качестве декоратора.326327Менеджеры контекста, наследующие от `ContextDecorator`, должны реализовывать [`__enter__()`](https://python-all.ru/3/reference/datamodel.html#object.__enter__) и [`__exit__()`](https://python-all.ru/3/reference/datamodel.html#object.__exit__) как обычно. `__exit__` сохраняет свою опциональную обработку исключений даже при использовании в качестве декоратора.328329`ContextDecorator` используется [`contextmanager()`](https://python-all.ru/3/library/contextlib.html#contextlib.contextmanager), поэтому эта функциональность доступна автоматически.330331Пример `ContextDecorator`:332333```python334from contextlib import ContextDecorator335336class mycontext(ContextDecorator):337    def __enter__(self):338        print('Starting')339        return self340341    def __exit__(self, *exc):342        print('Finishing')343        return False344```345346Затем класс можно использовать следующим образом:347348```python349>>> @mycontext()350... def function():351...     print('The bit in the middle')352...353>>> function()354Starting355The bit in the middle356Finishing357358>>> with mycontext():359...     print('The bit in the middle')360...361Starting362The bit in the middle363Finishing364```365366Это изменение – всего лишь синтаксический сахар для любой конструкции следующего вида:367368```python369def f():370    with cm():371        # Выполнить действия372```373374`ContextDecorator` позволяет вместо этого писать:375376```python377@cm()378def f():379    # Выполнить действия380```381382Становится ясно, что `cm` применяется ко всей функции, а не только к её части (и экономия уровня отступа тоже приятна).383384Существующие менеджеры контекста, уже имеющие базовый класс, можно расширить, используя `ContextDecorator` в качестве примеси (mixin):385386```python387from contextlib import ContextDecorator388389class mycontext(ContextBaseClass, ContextDecorator):390    def __enter__(self):391        return self392393    def __exit__(self, *exc):394        return False395```396397> **Примечание**398>399> Поскольку декорированная функция должна допускать многократный вызов, нижележащий менеджер контекста должен поддерживать использование в нескольких операторах [`with`](https://python-all.ru/3/reference/compound_stmts.html#with). Если это не так, следует использовать исходную конструкцию с явным оператором `with` внутри функции.400401Добавлено в версии 3.2.402403#### `class contextlib.AsyncContextDecorator`404405Аналогично [`ContextDecorator`](https://python-all.ru/3/library/contextlib.html#contextlib.ContextDecorator), но только для асинхронных функций.406407Пример `AsyncContextDecorator`:408409```python410from asyncio import run411from contextlib import AsyncContextDecorator412413class mycontext(AsyncContextDecorator):414    async def __aenter__(self):415        print('Starting')416        return self417418    async def __aexit__(self, *exc):419        print('Finishing')420        return False421```422423Затем класс можно использовать следующим образом:424425```python426>>> @mycontext()427... async def function():428...     print('The bit in the middle')429...430>>> run(function())431Starting432The bit in the middle433Finishing434435>>> async def function():436...    async with mycontext():437...         print('The bit in the middle')438...439>>> run(function())440Starting441The bit in the middle442Finishing443```444445Добавлено в версии 3.10.446447#### `class contextlib.ExitStack`448449Менеджер контекста, предназначенный для упрощения программного комбинирования других менеджеров контекста и функций очистки, особенно тех, которые являются необязательными или определяются входными данными.450451Например, набор файлов можно легко обработать в одном операторе with следующим образом:452453```python454with ExitStack() as stack:455    files = [stack.enter_context(open(fname)) for fname in filenames]456    # Все открытые файлы будут автоматически закрыты в конце457    # оператор with, даже если попытки открыть файлы, идущие далее458    # в списке, вызывают исключение459```460461Метод [`__enter__()`](https://python-all.ru/3/reference/datamodel.html#object.__enter__) возвращает экземпляр `ExitStack` и не выполняет никаких дополнительных операций.462463Каждый экземпляр поддерживает стек зарегистрированных колбэков, которые вызываются в обратном порядке при закрытии экземпляра (явно или неявно в конце оператора [`with`](https://python-all.ru/3/reference/compound_stmts.html#with)). Обратите внимание, что колбэки *не* вызываются неявно при сборке мусора экземпляра стека контекста.464465Такая стековая модель используется, чтобы менеджеры контекста, получающие свои ресурсы в методе `__init__` (например, файловые объекты), могли обрабатываться корректно.466467Поскольку зарегистрированные колбэки вызываются в порядке, обратном регистрации, в итоге это ведёт себя так, как если бы с зарегистрированным набором колбэков использовалось несколько вложенных операторов [`with`](https://python-all.ru/3/reference/compound_stmts.html#with). Это распространяется даже на обработку исключений: если внутренний колбэк подавляет или заменяет исключение, то внешним колбэкам будут переданы аргументы, основанные на этом обновлённом состоянии.468469Это относительно низкоуровневый API, который заботится о деталях корректной размотки стека колбэков выхода. Он предоставляет подходящую основу для менеджеров контекста более высокого уровня, которые манипулируют стеком выхода специфичным для приложения образом.470471Добавлено в версии 3.3.472473#### `enter_context(cm)`474475Входит в новый менеджер контекста и добавляет его метод [`__exit__()`](https://python-all.ru/3/reference/datamodel.html#object.__exit__) в стек колбэков. Возвращаемое значение – результат собственного метода [`__enter__()`](https://python-all.ru/3/reference/datamodel.html#object.__enter__) менеджера контекста.476477Эти менеджеры контекста могут подавлять исключения точно так же, как они это делали бы при непосредственном использовании в операторе [`with`](https://python-all.ru/3/reference/compound_stmts.html#with).478479Изменено в версии 3.11: Возбуждает [`TypeError`](https://python-all.ru/3/library/exceptions.html#TypeError) вместо [`AttributeError`](https://python-all.ru/3/library/exceptions.html#AttributeError), если *cm* не является менеджером контекста.480481#### `push(exit)`482483Добавляет метод [`__exit__()`](https://python-all.ru/3/reference/datamodel.html#object.__exit__) менеджера контекста в стек колбэков.484485Поскольку `__enter__` *не* вызывается, этот метод можно использовать для покрытия части реализации [`__enter__()`](https://python-all.ru/3/reference/datamodel.html#object.__enter__) собственным методом [`__exit__()`](https://python-all.ru/3/reference/datamodel.html#object.__exit__) менеджера контекста.486487Если передан объект, не являющийся менеджером контекста, этот метод считает его колбэком с той же сигнатурой, что и метод [`__exit__()`](https://python-all.ru/3/reference/datamodel.html#object.__exit__) менеджера контекста, и добавляет его напрямую в стек колбэков.488489Возвращая истинные значения, эти колбэки могут подавлять исключения так же, как это делают методы [`__exit__()`](https://python-all.ru/3/reference/datamodel.html#object.__exit__) менеджеров контекста.490491Переданный объект возвращается из функции, что позволяет использовать этот метод в качестве декоратора функции.492493#### `callback(callback, /, *args, **kwds)`494495Принимает произвольную функцию-колбэк и аргументы и добавляет её в стек колбэков.496497В отличие от других методов, колбэки, добавленные таким образом, не могут подавлять исключения (поскольку им никогда не передаются сведения об исключении).498499Переданный колбэк возвращается из функции, что позволяет использовать этот метод в качестве декоратора функции.500501#### `pop_all()`502503Перемещает стек колбэков в новый экземпляр `ExitStack` и возвращает его. При этой операции колбэки не вызываются – вместо этого они будут вызваны при закрытии нового стека (явно или неявно в конце оператора [`with`](https://python-all.ru/3/reference/compound_stmts.html#with)).504505Например, группу файлов можно открыть как операцию «всё или ничего» следующим образом:506507```python508with ExitStack() as stack:509    files = [stack.enter_context(open(fname)) for fname in filenames]510    # Сохраните метод close, но пока не вызывайте его.511    close_files = stack.pop_all().close512    # Если открытие любого файла завершается неудачей, все ранее открытые файлы будут513    # закрыты автоматически. Если все файлы открыты успешно,514    # они останутся открытыми даже после завершения оператора with.515    # close_files() затем можно вызвать явно, чтобы закрыть их все.516```517518#### `close()`519520Немедленно разворачивает стек колбэков, вызывая колбэки в порядке, обратном регистрации. Для любых зарегистрированных менеджеров контекста и колбэков выхода переданные аргументы будут указывать, что исключения не произошло.521522#### `class contextlib.AsyncExitStack`523524[Асинхронный менеджер контекста](https://python-all.ru/3/reference/datamodel.html#async-context-managers), аналогичный [`ExitStack`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack), который поддерживает объединение как синхронных, так и асинхронных менеджеров контекста, а также имеет корутины для логики очистки.525526Метод [`close()`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack.close) не реализован; вместо него следует использовать [`aclose()`](https://python-all.ru/3/library/contextlib.html#contextlib.AsyncExitStack.aclose).527528#### `async enter_async_context(cm)`529530Аналогично [`ExitStack.enter_context()`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack.enter_context), но ожидает асинхронный менеджер контекста.531532Изменено в версии 3.11: Вызывает [`TypeError`](https://python-all.ru/3/library/exceptions.html#TypeError) вместо [`AttributeError`](https://python-all.ru/3/library/exceptions.html#AttributeError), если *cm* не является асинхронным менеджером контекста.533534#### `push_async_exit(exit)`535536Аналогично [`ExitStack.push()`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack.push), но ожидает либо асинхронный менеджер контекста, либо корутинную функцию.537538#### `push_async_callback(callback, /, *args, **kwds)`539540Аналогично [`ExitStack.callback()`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack.callback), но ожидает корутинную функцию.541542#### `async aclose()`543544Аналогично [`ExitStack.close()`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack.close), но корректно обрабатывает ожидаемые объекты.545546Продолжая пример для [`asynccontextmanager()`](https://python-all.ru/3/library/contextlib.html#contextlib.asynccontextmanager):547548```python549async with AsyncExitStack() as stack:550    connections = [await stack.enter_async_context(get_connection())551        for i in range(5)]552    # Все открытые соединения будут автоматически освобождены в конце553    # оператора async with, даже если попытки открыть соединение554    # далее в списке вызывают исключение.555```556557Добавлено в версии 3.7.558559## Примеры и рецепты560561В этом разделе описаны некоторые примеры и рецепты для эффективного использования инструментов, предоставляемых `contextlib`.562563### Поддержка переменного числа менеджеров контекста564565Основной вариант использования [`ExitStack`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack) – это тот, что описан в документации класса: поддержка переменного числа менеджеров контекста и других операций очистки в одном операторе [`with`](https://python-all.ru/3/reference/compound_stmts.html#with). Переменность может быть обусловлена тем, что количество необходимых менеджеров контекста определяется пользовательским вводом (например, открытие указанной пользователем коллекции файлов), или тем, что некоторые менеджеры контекста являются необязательными:566567```python568with ExitStack() as stack:569    for resource in resources:570        stack.enter_context(resource)571    if need_special_resource():572        special = acquire_special_resource()573        stack.callback(release_special_resource, special)574    # Выполните операции, использующие полученные ресурсы575```576577Как показано, [`ExitStack`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack) также значительно упрощает использование операторов [`with`](https://python-all.ru/3/reference/compound_stmts.html#with) для управления произвольными ресурсами, которые изначально не поддерживают протокол управления контекстом.578579### Перехват исключений из методов `__enter__`580581Иногда бывает желательно перехватывать исключения из реализации метода [`__enter__()`](https://python-all.ru/3/reference/datamodel.html#object.__enter__), *не* перехватывая случайно исключения из тела оператора [`with`](https://python-all.ru/3/reference/compound_stmts.html#with) или метода [`__exit__()`](https://python-all.ru/3/reference/datamodel.html#object.__exit__) менеджера контекста. Используя [`ExitStack`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack), можно немного разделить шаги протокола управления контекстом, чтобы это стало возможным:582583```python584stack = ExitStack()585try:586    x = stack.enter_context(cm)587except Exception:588    # обработать исключение __enter__589else:590    with stack:591        # Обработка нормального случая592```593594Необходимость в этом, скорее всего, указывает на то, что базовый API должен предоставлять прямой интерфейс управления ресурсами для использования с операторами [`try`](https://python-all.ru/3/reference/compound_stmts.html#try)/[`except`](https://python-all.ru/3/reference/compound_stmts.html#except)/[`finally`](https://python-all.ru/3/reference/compound_stmts.html#finally), но не все API хорошо спроектированы в этом отношении. Когда менеджер контекста является единственным предоставляемым API управления ресурсами, тогда [`ExitStack`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack) может упростить обработку различных ситуаций, которые невозможно обработать напрямую в операторе [`with`](https://python-all.ru/3/reference/compound_stmts.html#with).595596### Очистка в реализации `__enter__`597598Как отмечено в документации [`ExitStack.push()`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack.push), этот метод может быть полезен для очистки уже выделенного ресурса, если последующие шаги в реализации [`__enter__()`](https://python-all.ru/3/reference/datamodel.html#object.__enter__) завершатся неудачей.599600Вот пример реализации этого для менеджера контекста, который принимает функции захвата и освобождения ресурса, а также опциональную функцию проверки, и отображает их на протокол управления контекстом:601602```python603from contextlib import contextmanager, AbstractContextManager, ExitStack604605class ResourceManager(AbstractContextManager):606607    def __init__(self, acquire_resource, release_resource, check_resource_ok=None):608        self.acquire_resource = acquire_resource609        self.release_resource = release_resource610        if check_resource_ok is None:611            def check_resource_ok(resource):612                return True613        self.check_resource_ok = check_resource_ok614615    @contextmanager616    def _cleanup_on_error(self):617        with ExitStack() as stack:618            stack.push(self)619            yield620            # Проверка прошла успешно и не вызвала исключение621            # Соответственно, мы хотим сохранить ресурс и передать его622            # обратно вызывающему коду623            stack.pop_all()624625    def __enter__(self):626        resource = self.acquire_resource()627        with self._cleanup_on_error():628            if not self.check_resource_ok(resource):629                msg = "Failed validation for {!r}"630                raise RuntimeError(msg.format(resource))631        return resource632633    def __exit__(self, *exc_details):634        # Нам не нужно дублировать логику освобождения ресурсов635        self.release_resource()636```637638### Замена любого использования `try-finally` и флаговых переменных639640Иногда встречается шаблон, в котором используется инструкция `try-finally` с переменной-флагом, указывающей, должно ли выполняться тело предложения `finally`. В простейшей форме (если это нельзя обработать простым использованием предложения `except`) это выглядит примерно так:641642```python643cleanup_needed = True644try:645    result = perform_operation()646    if result:647        cleanup_needed = False648finally:649    if cleanup_needed:650        cleanup_resources()651```652653Как и в любом коде, основанном на инструкции `try`, это может вызвать проблемы при разработке и рецензировании, поскольку код настройки и код очистки могут оказаться разделенными произвольно длинными участками кода.654655[`ExitStack`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack) позволяет вместо этого зарегистрировать колбэк для выполнения в конце инструкции `with`, а затем позже решить пропустить выполнение этого колбэка:656657```python658from contextlib import ExitStack659660with ExitStack() as stack:661    stack.callback(cleanup_resources)662    result = perform_operation()663    if result:664        stack.pop_all()665```666667Это позволяет заранее сделать предполагаемое поведение очистки явным, вместо того чтобы требовать отдельной переменной-флага.668669Если конкретное приложение часто использует этот шаблон, его можно упростить еще больше с помощью небольшого вспомогательного класса:670671```python672from contextlib import ExitStack673674class Callback(ExitStack):675    def __init__(self, callback, /, *args, **kwds):676        super().__init__()677        self.callback(callback, *args, **kwds)678679    def cancel(self):680        self.pop_all()681682with Callback(cleanup_resources) as cb:683    result = perform_operation()684    if result:685        cb.cancel()686```687688Если очистка ресурсов уже не аккуратно оформлена в виде отдельной функции, то все равно можно использовать форму декоратора [`ExitStack.callback()`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack.callback), чтобы объявить очистку ресурсов заранее:689690```python691from contextlib import ExitStack692693with ExitStack() as stack:694    @stack.callback695    def cleanup_resources():696        ...697    result = perform_operation()698    if result:699        stack.pop_all()700```701702Из-за того, как работает протокол декоратора, функция обратного вызова, объявленная таким образом, не может принимать никаких параметров. Вместо этого любые ресурсы, которые необходимо освободить, должны быть доступны как переменные замыкания.703704### Использование менеджера контекста в качестве декоратора функции705706[`ContextDecorator`](https://python-all.ru/3/library/contextlib.html#contextlib.ContextDecorator) позволяет использовать менеджер контекста как в обычной инструкции `with`, так и в качестве декоратора функции.707708Например, иногда полезно оборачивать функции или группы инструкций в логгер, который может отслеживать время входа и время выхода. Вместо написания как декоратора функции, так и менеджера контекста для этой задачи, наследование от [`ContextDecorator`](https://python-all.ru/3/library/contextlib.html#contextlib.ContextDecorator) предоставляет обе возможности в одном определении:709710```python711from contextlib import ContextDecorator712import logging713714logging.basicConfig(level=logging.INFO)715716class track_entry_and_exit(ContextDecorator):717    def __init__(self, name):718        self.name = name719720    def __enter__(self):721        logging.info('Entering: %s', self.name)722723    def __exit__(self, exc_type, exc, exc_tb):724        logging.info('Exiting: %s', self.name)725```726727Экземпляры этого класса можно использовать как менеджер контекста:728729```python730with track_entry_and_exit('widget loader'):731    print('Some time consuming activity goes here')732    load_widget()733```734735А также как декоратор функции:736737```python738@track_entry_and_exit('widget loader')739def activity():740    print('Some time consuming activity goes here')741    load_widget()742```743744Обратите внимание, что есть одно дополнительное ограничение при использовании менеджеров контекста в качестве декораторов функций: невозможно получить доступ к возвращаемому значению [`__enter__()`](https://python-all.ru/3/reference/datamodel.html#object.__enter__). Если это значение необходимо, то все равно нужно использовать явную инструкцию `with`.745746> **См. также**747>748> **[**PEP 343**](https://python-all.ru/3/library/contextlib.html) – Оператор «with»**749>750> Спецификация, предыстория и примеры для инструкции [`with`](https://python-all.ru/3/reference/compound_stmts.html#with) в Python.751752## Одноразовые, многократно используемые и реентерабельные менеджеры контекста753754Большинство менеджеров контекста написаны таким образом, что их можно эффективно использовать только один раз в инструкции [`with`](https://python-all.ru/3/reference/compound_stmts.html#with). Эти одноразовые менеджеры контекста должны создаваться заново каждый раз при использовании – попытка использовать их второй раз вызовет исключение или иным образом приведет к некорректной работе.755756Это распространенное ограничение означает, что обычно рекомендуется создавать менеджеры контекста непосредственно в заголовке инструкции [`with`](https://python-all.ru/3/reference/compound_stmts.html#with), где они используются (как показано во всех примерах использования выше).757758Файлы являются примером эффективно одноразовых менеджеров контекста, поскольку первая инструкция [`with`](https://python-all.ru/3/reference/compound_stmts.html#with) закроет файл, предотвращая любые дальнейшие операции ввода-вывода с использованием этого объекта файла.759760Менеджеры контекста, созданные с помощью [`contextmanager()`](https://python-all.ru/3/library/contextlib.html#contextlib.contextmanager), также являются одноразовыми менеджерами контекста и будут сообщать об ошибке, если базовый генератор не сможет выполнить yield при попытке использовать их второй раз:761762```python763>>> from contextlib import contextmanager764>>> @contextmanager765... def singleuse():766...     print("Before")767...     yield768...     print("After")769...770>>> cm = singleuse()771>>> with cm:772...     pass773...774Before775After776>>> with cm:777...     pass778...779Traceback (most recent call last):780    ...781RuntimeError: generator didn't yield782```783784### Реентерабельные менеджеры контекста785786Более сложные менеджеры контекста могут быть «реентерабельными». Такие менеджеры контекста можно использовать не только в нескольких инструкциях [`with`](https://python-all.ru/3/reference/compound_stmts.html#with), но также *внутри* инструкции `with`, которая уже использует тот же менеджер контекста.787788[`threading.RLock`](https://python-all.ru/3/library/threading.html#threading.RLock) является примером реентерабельного менеджера контекста, как и [`suppress()`](https://python-all.ru/3/library/contextlib.html#contextlib.suppress), [`redirect_stdout()`](https://python-all.ru/3/library/contextlib.html#contextlib.redirect_stdout) и [`chdir()`](https://python-all.ru/3/library/contextlib.html#contextlib.chdir). Вот очень простой пример реентерабельного использования:789790```python791>>> from contextlib import redirect_stdout792>>> from io import StringIO793>>> stream = StringIO()794>>> write_to_stream = redirect_stdout(stream)795>>> with write_to_stream:796...     print("This is written to the stream rather than stdout")797...     with write_to_stream:798...         print("This is also written to the stream")799...800>>> print("This is written directly to stdout")801This is written directly to stdout802>>> print(stream.getvalue())803This is written to the stream rather than stdout804This is also written to the stream805```806807Реальные примеры реентерабельности, скорее всего, будут включать несколько функций, вызывающих друг друга, и, следовательно, будут гораздо сложнее этого примера.808809Также обратите внимание, что быть реентерабельным – это *не* то же самое, что быть потокобезопасным. [`redirect_stdout()`](https://python-all.ru/3/library/contextlib.html#contextlib.redirect_stdout), например, определенно не является потокобезопасным, так как он вносит глобальное изменение в состояние системы, привязывая [`sys.stdout`](https://python-all.ru/3/library/sys.html#sys.stdout) к другому потоку данных.810811### Многократно используемые менеджеры контекста812813Отличающиеся от одноразовых и реентерабельных менеджеров контекста – «многократно используемые» менеджеры контекста (или, если быть совсем точным, «многократно используемые, но не реентерабельные» менеджеры контекста, поскольку реентерабельные менеджеры контекста также являются многократно используемыми). Эти менеджеры контекста поддерживают многократное использование, но завершатся ошибкой (или иным образом будут работать некорректно), если конкретный экземпляр менеджера контекста уже был использован во внешней инструкции with.814815[`threading.Lock`](https://python-all.ru/3/library/threading.html#threading.Lock) является примером многократно используемого, но не реентерабельного менеджера контекста (для реентерабельной блокировки необходимо использовать [`threading.RLock`](https://python-all.ru/3/library/threading.html#threading.RLock) вместо этого).816817Другим примером многократно используемого, но не реентерабельного менеджера контекста является [`ExitStack`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack), так как он вызывает *все* зарегистрированные в данный момент колбэки при выходе из любой инструкции with, независимо от того, где эти колбэки были добавлены:818819```python820>>> from contextlib import ExitStack821>>> stack = ExitStack()822>>> with stack:823...     stack.callback(print, "Callback: from first context")824...     print("Leaving first context")825...826Leaving first context827Callback: from first context828>>> with stack:829...     stack.callback(print, "Callback: from second context")830...     print("Leaving second context")831...832Leaving second context833Callback: from second context834>>> with stack:835...     stack.callback(print, "Callback: from outer context")836...     with stack:837...         stack.callback(print, "Callback: from inner context")838...         print("Leaving inner context")839...     print("Leaving outer context")840...841Leaving inner context842Callback: from inner context843Callback: from outer context844Leaving outer context845```846847Как показывает вывод примера, повторное использование одного объекта стека в нескольких инструкциях with работает корректно, но попытка вложить их приведет к очистке стека в конце самой внутренней инструкции with, что вряд ли является желательным поведением.848849Использование отдельных экземпляров [`ExitStack`](https://python-all.ru/3/library/contextlib.html#contextlib.ExitStack) вместо повторного использования одного экземпляра позволяет избежать этой проблемы:850851```python852>>> from contextlib import ExitStack853>>> with ExitStack() as outer_stack:854...     outer_stack.callback(print, "Callback: from outer context")855...     with ExitStack() as inner_stack:856...         inner_stack.callback(print, "Callback: from inner context")857...         print("Leaving inner context")858...     print("Leaving outer context")859...860Leaving inner context861Callback: from inner context862Leaving outer context863Callback: from outer context864```865