# `contextlib` — Утиліти для контекстів операторів `with`

Вихідний код: Lib/contextlib.py

Цей модуль надає утиліти для типових завдань, пов’язаних із оператором `with`. Для отримання додаткової інформації див. також Типи менеджера контексту і З менеджерами контексту операторів.

## Комунальні послуги

Надані функції та класи:

class contextlib.AbstractContextManager

  abstract base class для класів, які реалізують `object.__enter__()` і `object.__exit__()`. Надається реалізація за замовчуванням для `object.__enter__()`, яка повертає `self`, тоді як `object.__exit__()` є абстрактним методом, який за замовчуванням повертає `None`. Дивіться також визначення Типи менеджера контексту.

  Added in version 3.6.

class contextlib.AbstractAsyncContextManager

  abstract base class для класів, які реалізують `object.__aenter__()` і `object.__aexit__()`. Надається реалізація за замовчуванням для `object.__aenter__()`, яка повертає `self`, тоді як `object.__aexit__()` є абстрактним методом, який за замовчуванням повертає `None`. Дивіться також визначення Менеджери асинхронного контексту.

  Added in version 3.7.

@contextlib.contextmanager

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

  While many objects natively support use in with statements, sometimes a resource needs to be managed that isn’t a context manager in its own right, and doesn’t implement a `close()` method for use with `contextlib.closing`.

  Абстрактним прикладом може бути наступне, щоб забезпечити правильне керування ресурсами:

      from contextlib import contextmanager

      @contextmanager
      def managed_resource(*args, **kwds):
          # Code to acquire resource, e.g.:
          resource = acquire_resource(*args, **kwds)
          try:
              yield resource
          finally:
              # Code to release resource, e.g.:
              release_resource(resource)

  The function can then be used like this:

      >>> with managed_resource(timeout=3600) as resource:
      ...     # Resource is released at the end of this block,
      ...     # even if code in the block raises an exception

  Функція, яка декорується, має повертати generator-ітератор під час виклику. Цей ітератор має давати рівно одне значення, яке буде прив’язано до цілей у пропозиції `as` інструкції `with`, якщо така є.

  У точці, де генератор поступається, виконується блок, вкладений у оператор `with`. Потім генератор відновлюється після виходу з блоку. Якщо в блоці виникає необроблена виняткова ситуація, вона повторно створюється всередині генератора в точці, де відбувся вихід. Таким чином, ви можете використовувати оператор `try`…`except`…`finally`, щоб перехопити помилку (якщо така є) або забезпечити виконання певного очищення. Якщо виняток перехоплюється лише для того, щоб зареєструвати його або виконати певну дію (а не повністю його придушити), генератор повинен повторно викликати цей виняток. В іншому випадку менеджер контексту генератора вкаже оператору `with`, що виняток було оброблено, і виконання буде відновлено оператором, що слідує безпосередньо за оператором `with`.

  `contextmanager()` використовує `ContextDecorator`, тому створені ним менеджери контексту можна використовувати як декоратори, а також у операторах `with`. Коли використовується як декоратор, новий екземпляр генератора неявно створюється під час кожного виклику функції (це дозволяє «одноразовим» контекстним менеджерам, створеним `contextmanager()`, відповідати вимогам, щоб контекстні менеджери підтримували кілька викликів, щоб використовувати як декоратори).

  Змінено в версії 3.2: Використання `ContextDecorator`.

@contextlib.asynccontextmanager

  Подібно до `contextmanager()`, але створює асинхронний менеджер контексту.

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

  Простий приклад:

      from contextlib import asynccontextmanager

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

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

  Added in version 3.7.

  Менеджери контексту, визначені за допомогою `asynccontextmanager()`, можна використовувати як декоратори або за допомогою операторів `async with`:

      import time
      from contextlib import asynccontextmanager

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

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

  При використанні як декоратора новий екземпляр генератора неявно створюється під час кожного виклику функції. Це дозволяє «одноразовим» контекстним менеджерам, створеним `asynccontextmanager()`, відповідати вимогам, щоб контекстні менеджери підтримували кілька викликів, щоб використовувати їх як декоратори.

  Змінено в версії 3.10: Менеджери асинхронного контексту, створені за допомогою `asynccontextmanager()`, можна використовувати як декоратори.

contextlib.closing(thing)

  Повертає контекстний менеджер, який закриває річ після завершення блоку. Це в основному еквівалентно:

      from contextlib import contextmanager

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

  І дозволяє писати такий код:

      from contextlib import closing
      from urllib.request import urlopen

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

  без необхідності явного закриття `сторінки`. Навіть якщо станеться помилка, `page.close()` буде викликано під час виходу з блоку `with`.

  Примітка

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

contextlib.aclosing(thing)

  Повертає менеджер асинхронного контексту, який викликає метод `aclose()` thing після завершення блоку. Це в основному еквівалентно:

      from contextlib import asynccontextmanager

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

  Важливо, що `aclosing()` підтримує детерміноване очищення асинхронних генераторів, коли вони виходять раніше через `break` або виняток. Наприклад:

      from contextlib import aclosing

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

  Цей шаблон гарантує, що асинхронний код виходу генератора виконується в тому самому контексті, що й його ітерації (щоб винятки та контекстні змінні працювали належним чином, а код виходу не запускався після закінчення часу існування певного завдання, від якого він залежить).

  Added in version 3.10.

contextlib.nullcontext(enter_result=None)

  Повертає контекстний менеджер, який повертає enter_result із `__enter__`, але в іншому випадку нічого не робить. Він призначений для використання як резервний для додаткового контекстного менеджера, наприклад:

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

  Приклад використання enter_result:

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

          with cm as file:
              # Perform processing on the file

  Його також можна використовувати як заміну для асинхронних контекстних менеджерів:

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

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

  Added in version 3.7.

  Змінено в версії 3.10: Додано підтримку asynchronous context manager.

contextlib.suppress(*exceptions)

  Повертає диспетчер контексту, який пригнічує будь-які з указаних винятків, якщо вони трапляються в тілі оператора `with`, а потім відновлює виконання з першим оператором, що йде після кінця оператора `with`.

  Як і будь-який інший механізм, який повністю пригнічує винятки, цей менеджер контексту слід використовувати лише для покриття дуже конкретних помилок, коли, як відомо, правильно продовжувати виконання програми.

  Наприклад:

      from contextlib import suppress

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

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

  Цей код еквівалентний:

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

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

  Цей контекстний менеджер є reentrant.

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

  Added in version 3.4.

  Змінено в версії 3.12: `suppress` now supports suppressing exceptions raised as part of a `BaseExceptionGroup`.

contextlib.redirect_stdout(new_target)

  Context manager for temporarily redirecting `sys.stdout` to another file object.

  This tool adds flexibility to existing functions or classes whose output is hardwired to `sys.stdout`.

  Наприклад, вихід `help()` зазвичай надсилається до sys.stdout. Ви можете записати цей вивід у рядок, перенаправивши вивід на об’єкт `io.StringIO`. Потік заміни повертається з методу `__enter__` і тому доступний як ціль оператора `with`:

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

  Щоб надіслати вивід `help()` у файл на диску, перенаправте вивід у звичайний файл:

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

  Щоб надіслати результат `help()` до sys.stderr:

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

  Зауважте, що глобальний побічний ефект `sys.stdout` означає, що цей контекстний менеджер не підходить для використання в бібліотечному коді та більшості потокових програм. Це також не впливає на вихідні дані підпроцесів. Однак це все ще корисний підхід для багатьох службових сценаріїв.

  Цей контекстний менеджер є reentrant.

  Added in version 3.4.

contextlib.redirect_stderr(new_target)

  Similar to `redirect_stdout()` but redirecting the global `sys.stderr` to another file object.

  Цей контекстний менеджер є reentrant.

  Added in version 3.5.

contextlib.chdir(path)

  Non parallel-safe context manager to change the current working directory. As this changes a global state, the working directory, it is not suitable for use in most threaded or async contexts. It is also not suitable for most non-linear code execution, like generators, where the program execution is temporarily relinquished – unless explicitly desired, you should not yield when this context manager is active.

  This is a simple wrapper around `chdir()`, it changes the current working directory upon entering and restores the old one on exit.

  Цей контекстний менеджер є reentrant.

  Added in version 3.11.

class contextlib.ContextDecorator

  Базовий клас, який дозволяє менеджеру контексту також використовуватися як декоратор.

  Менеджери контексту, успадковані від `ContextDecorator`, мають реалізувати `__enter__` і `__exit__` як зазвичай. `__exit__` зберігає необов’язкову обробку винятків, навіть якщо використовується як декоратор.

  `ContextDecorator` використовується `contextmanager()`, тому ви отримуєте цю функціональність автоматично.

  Приклад `ContextDecorator`:

      from contextlib import ContextDecorator

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

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

  The class can then be used like this:

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

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

  Ця зміна є просто синтаксичним цукром для будь-якої конструкції наступної форми:

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

  `ContextDecorator` дозволяє замість цього писати:

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

  Це дає зрозуміти, що `cm` застосовується до всієї функції, а не лише до її частини (і зберегти рівень відступу теж добре).

  Існуючі контекстні менеджери, які вже мають базовий клас, можна розширити за допомогою `ContextDecorator` як класу mixin:

      from contextlib import ContextDecorator

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

          def __exit__(self, *exc):
              return False

  Примітка

  Оскільки декорована функція повинна мати можливість викликатися кілька разів, базовий менеджер контексту повинен підтримувати використання в кількох операторах `with`. Якщо це не так, тоді слід використовувати оригінальну конструкцію з явним оператором `with` усередині функції.

  Added in version 3.2.

class contextlib.AsyncContextDecorator

  Подібно до `ContextDecorator`, але лише для асинхронних функцій.

  Приклад `AsyncContextDecorator`:

      from asyncio import run
      from contextlib import AsyncContextDecorator

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

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

  The class can then be used like this:

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

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

  Added in version 3.10.

class contextlib.ExitStack

  Менеджер контексту, розроблений для полегшення програмного поєднання інших менеджерів контексту та функцій очищення, особливо тих, які є необов’язковими або іншим чином керуються вхідними даними.

  Наприклад, набір файлів можна легко обробити в одному операторі with наступним чином:

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

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

  Кожен екземпляр підтримує стек зареєстрованих зворотних викликів, які викликаються у зворотному порядку, коли екземпляр закривається (явно чи неявно в кінці оператора `with`). Зауважте, що зворотні виклики не викликаються неявно, коли примірник стеку контексту збирається сміттям.

  Ця модель стеку використовується для того, щоб контекстні менеджери, які отримують свої ресурси у своєму методі `__init__` (наприклад, файлові об’єкти), могли оброблятися правильно.

  Оскільки зареєстровані зворотні виклики викликаються в порядку, зворотному реєстрації, це в кінцевому підсумку поводиться так, ніби декілька вкладених операторів `with` використовувалися із зареєстрованим набором зворотних викликів. Це навіть поширюється на обробку винятків - якщо внутрішній зворотний виклик пригнічує або замінює виняток, то зовнішнім зворотним викликам будуть передані аргументи на основі цього оновленого стану.

  Це API відносно низького рівня, який піклується про деталі правильного розгортання стека зворотних викликів виходу. Він забезпечує відповідну основу для контекстних менеджерів вищого рівня, які маніпулюють стеком виходу у специфічних для програми способах.

  Added in version 3.3.

  enter_context(cm)

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

    Ці контекстні менеджери можуть придушувати винятки так само, як вони зазвичай робили б, якщо використовувати безпосередньо як частину оператора `with`.

    Змінено в версії 3.11: Raises `TypeError` instead of `AttributeError` if cm is not a context manager.

    Змінено в версії 3.15.0a5 (unreleased): Added support for arbitrary descriptors `__enter__()` and `__exit__()`.

  push(exit)

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

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

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

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

    Переданий об’єкт повертається функцією, що дозволяє використовувати цей метод як декоратор функції.

    Змінено в версії 3.15.0a5 (unreleased): Added support for arbitrary descriptors `__exit__()`.

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

    Приймає довільну функцію зворотного виклику та аргументи та додає їх до стеку зворотного виклику.

    На відміну від інших методів, зворотні виклики, додані таким чином, не можуть придушувати винятки (оскільки їм ніколи не передаються деталі винятку).

    Переданий зворотний виклик повертається функцією, що дозволяє використовувати цей метод як декоратор функції.

  pop_all()

    Передає стек зворотних викликів до нового екземпляра `ExitStack` і повертає його. Жодні зворотні виклики не викликаються цією операцією - замість цього вони тепер будуть викликані, коли новий стек закривається (явно чи неявно в кінці оператора `with`).

    Наприклад, групу файлів можна відкрити за допомогою операції «все або нічого» наступним чином:

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

  close()

    Негайно розгортає стек зворотних викликів, викликаючи зворотні виклики в порядку, зворотному реєстрації. Для будь-яких менеджерів контексту та зареєстрованих зворотних викликів виходу передані аргументи вказуватимуть, що винятків не сталося.

class contextlib.AsyncExitStack

  асинхронний контекстний менеджер, подібний до `ExitStack`, який підтримує поєднання синхронних і асинхронних контекстних менеджерів, а також має співпрограми для логіки очищення.

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

  async enter_async_context(cm)

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

    Змінено в версії 3.11: Raises `TypeError` instead of `AttributeError` if cm is not an asynchronous context manager.

    Змінено в версії 3.15.0a5 (unreleased): Added support for arbitrary descriptors `__aenter__()` and `__aexit__()`.

  push_async_exit(exit)

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

    Змінено в версії 3.15.0a5 (unreleased): Added support for arbitrary descriptors `__aexit__()`.

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

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

  async aclose()

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

  Продовжуємо приклад для `asynccontextmanager()`:

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

  Added in version 3.7.

## Приклади та рецепти

This section describes some examples and recipes for making effective use of the tools provided by `contextlib`.

### Підтримка змінної кількості контекстних менеджерів

Основний варіант використання `ExitStack` — це той, який наведено в документації класу: підтримка змінної кількості контекстних менеджерів та інших операцій очищення в одному операторі `with`. Варіативність може виникати через кількість необхідних менеджерів контексту, які керуються введенням користувача (наприклад, відкриття вказаної користувачем колекції файлів), або через те, що деякі менеджери контексту є необов’язковими:

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

Як показано, `ExitStack` також дозволяє досить легко використовувати оператори `with` для керування довільними ресурсами, які спочатку не підтримують протокол керування контекстом.

### Перехоплення винятків із методів `__enter__`

Час від часу бажано перехоплювати винятки з реалізації методу `__enter__`, без випадкового перехоплення винятків з тіла оператора `with` або методу `__exit__` контекстного менеджера. За допомогою `ExitStack` кроки в протоколі керування контекстом можна трохи розділити, щоб дозволити це:

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

Насправді необхідність зробити це означає, що основний API має надавати інтерфейс прямого керування ресурсами для використання з операторами `try`/`except`/`finally`, але не з усіма API добре розроблені в цьому плані. Коли контекстний менеджер є єдиним наданим API керування ресурсами, тоді `ExitStack` може полегшити обробку різноманітних ситуацій, які не можна обробити безпосередньо в операторі `with`.

### Очищення в реалізації `__enter__`

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

Ось приклад виконання цього для контекстного менеджера, який приймає функції отримання та звільнення ресурсів разом із додатковою функцією перевірки та відображає їх у протоколі керування контекстом:

    from contextlib import contextmanager, AbstractContextManager, ExitStack

    class ResourceManager(AbstractContextManager):

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

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

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

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

### Заміна будь-якого використання змінних `try-finally` і прапорців

Зразок, який ви іноді побачите, — це інструкція `try-finally` зі змінною-прапором, яка вказує, чи має бути виконано тіло пропозиції `finally`. У своїй найпростішій формі (з якою вже не можна впоратися лише за допомогою пропозиції `except`), це виглядає приблизно так:

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

Як і у випадку з будь-яким кодом, заснованим на інструкціях `try`, це може спричинити проблеми з розробкою та переглядом, оскільки код налаштування та код очищення можуть бути розділені довільно довгими частинами коду.

`ExitStack` дає змогу замість цього зареєструвати зворотний виклик для виконання в кінці оператора `with`, а потім вирішити пропустити виконання цього зворотного виклику:

    from contextlib import ExitStack

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

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

Якщо певна програма часто використовує цей шаблон, його можна ще більше спростити за допомогою невеликого допоміжного класу:

    from contextlib import ExitStack

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

        def cancel(self):
            self.pop_all()

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

Якщо очищення ресурсу ще не акуратно об’єднано в окрему функцію, то все ще можна використовувати форму декоратора `ExitStack.callback()`, щоб оголосити очищення ресурсу заздалегідь:

    from contextlib import ExitStack

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

Через те, як працює протокол декоратора, функція зворотного виклику, оголошена таким чином, не може приймати жодних параметрів. Натомість доступ до будь-яких ресурсів, які потрібно звільнити, має здійснюватися як змінні закриття.

### Використання контекстного менеджера як декоратора функції

`ContextDecorator` дає змогу використовувати менеджер контексту як у звичайному операторі `with`, так і як декоратор функції.

Наприклад, іноді корисно обернути функції або групи операторів за допомогою реєстратора, який може відстежувати час входу та час виходу. Замість написання як декоратора функції, так і менеджера контексту для завдання, успадкування від `ContextDecorator` надає обидві можливості в одному визначенні:

    from contextlib import ContextDecorator
    import logging

    logging.basicConfig(level=logging.INFO)

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

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

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

Екземпляри цього класу можна використовувати і як менеджер контексту:

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

А також як декоратор функцій:

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

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

Дивись також

PEP 343 - оператор «з».

  Специфікація, передумови та приклади оператора Python `with`.

## Менеджери контексту для одноразового, багаторазового та повторного входу

Більшість контекстних менеджерів написані таким чином, що вони можуть бути ефективно використані в операторі `with` лише один раз. Ці одноразові контекстні менеджери потрібно створювати заново кожного разу, коли вони використовуються — спроба використати їх вдруге призведе до виключення або іншим чином не працюватиме належним чином.

Це загальне обмеження означає, що загалом доцільно створювати менеджери контексту безпосередньо в заголовку оператора `with`, де вони використовуються (як показано в усіх наведених вище прикладах використання).

Файли є прикладом ефективних одноразових контекстних менеджерів, оскільки перший оператор `with` закриває файл, запобігаючи будь-яким подальшим операціям вводу-виводу з використанням цього файлового об’єкта.

Менеджери контексту, створені за допомогою `contextmanager()`, також є одноразовими менеджерами контексту, і вони скаржаться на те, що базовий генератор не працює, якщо буде зроблена спроба використати їх вдруге:

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

### Реентерабельні контекстні менеджери

Більш складні контекстні менеджери можуть бути «реентерабельними». Ці менеджери контексту можна використовувати не лише в кількох операторах `with`, але також всередині оператора `with`, який уже використовує той самий менеджер контексту.

`threading.RLock` is an example of a reentrant context manager, as are `suppress()`, `redirect_stdout()`, and `chdir()`. Here’s a very simple example of reentrant use:

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

Приклади повторного входу в реальному світі, швидше за все, включають кілька функцій, які викликають одна одну, і, отже, вони набагато складніші, ніж цей приклад.

Зауважте також, що реентерабельність — це не те саме, що бути потокобезпечною. `redirect_stdout()`, наприклад, точно небезпечний для потоків, оскільки він робить глобальну модифікацію стану системи шляхом прив’язки `sys.stdout` до іншого потоку.

### Багаторазові контекстні менеджери

Від одноразових і повторних контекстних менеджерів відрізняються «повторно використовувані» контекстні менеджери (або, якщо бути повністю явними, «повторно використовувані, але не повторні» контекстні менеджери, оскільки повторні контекстні менеджери також багаторазові). Ці контекстні менеджери підтримують багаторазове використання, але не працюватимуть (або не працюватимуть належним чином), якщо конкретний екземпляр контекстного менеджера вже використовувався в операторі containing with.

`threading.Lock` є прикладом повторно використовуваного, але не реентрантного, контекстного менеджера (для повторного вхідного блокування замість цього необхідно використовувати `threading.RLock`).

Іншим прикладом повторно використовуваного, але не реентрантного контекстного менеджера є `ExitStack`, оскільки він викликає всі зареєстровані наразі зворотні виклики, коли залишає будь-який оператор with, незалежно від того, де ці зворотні виклики було додано:

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

Як показує вихід із прикладу, повторне використання одного об’єкта стека в кількох інструкціях with працює правильно, але спроба їх вкладення спричинить очищення стека в кінці внутрішнього оператора with, що навряд чи буде бажаною поведінкою.

Використання окремих екземплярів `ExitStack` замість повторного використання одного екземпляра дозволяє уникнути цієї проблеми:

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