# `contextvars` — Context Variables

Цей модуль надає API для керування, зберігання та доступу до контекстно-локального стану. Клас `ContextVar` використовується для оголошення контекстних змінних і роботи з ними. Функцію `copy_context()` і клас `Context` слід використовувати для керування поточним контекстом в асинхронних структурах.

Context managers that have state should use Context Variables instead of `threading.local()` to prevent their state from bleeding to other code unexpectedly, when used in concurrent code.

Дивіться також PEP 567 для отримання додаткової інформації.

Added in version 3.7.

## Контекстні змінні

class contextvars.ContextVar(name[, *, default])

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

      var: ContextVar[int] = ContextVar('var', default=42)

  Необхідний параметр name використовується для самоаналізу та налагодження.

  Необов’язковий параметр default, що містить лише ключове слово, повертається `ContextVar.get()`, якщо значення для змінної не знайдено в поточному контексті.

  Важливо: Змінні контексту слід створювати на верхньому рівні модуля, а не в закриттях. Об’єкти `Context` містять сильні посилання на змінні контексту, що перешкоджає правильному збиранню сміття змінним контексту.

  name

    Ім’я змінної. Це властивість лише для читання.

    Added in version 3.7.1.

  get([default])

    Повертає значення контекстної змінної для поточного контексту.

    Якщо для змінної немає значення в поточному контексті, метод:

    - повертає значення аргументу default методу, якщо він надається; або

    - повертає значення за замовчуванням для контекстної змінної, якщо вона була створена за допомогою такої; або

    - викликає `LookupError`.

  set(value)

    Виклик, щоб встановити нове значення для контекстної змінної в поточному контексті.

    Обов’язковий аргумент значення — це нове значення для контекстної змінної.

    Повертає об’єкт `Token`, який можна використовувати для відновлення попереднього значення змінної за допомогою методу `ContextVar.reset()`.

    For convenience, the token object can be used as a context manager to avoid calling `ContextVar.reset()` manually:

        var = ContextVar('var', default='default value')

        with var.set('new value'):
            assert var.get() == 'new value'

        assert var.get() == 'default value'

    It is a shorthand for:

        var = ContextVar('var', default='default value')

        token = var.set('new value')
        try:
            assert var.get() == 'new value'
        finally:
            var.reset(token)

        assert var.get() == 'default value'

    Added in version 3.14: Added support for using tokens as context managers.

  reset(token)

    Скиньте контекстну змінну до значення, яке воно мало до використання `ContextVar.set()`, який створив токен.

    Наприклад:

        var = ContextVar('var')

        token = var.set('new value')
        # code that uses 'var'; var.get() returns 'new value'.
        var.reset(token)

        # After the reset call the var has no value again, so
        # var.get() would raise a LookupError.

    The same token cannot be used twice.

class contextvars.Token

  Token objects are returned by the `ContextVar.set()` method. They can be passed to the `ContextVar.reset()` method to revert the value of the variable to what it was before the corresponding set. A single token cannot reset a context variable more than once.

  Tokens support the context manager protocol to automatically reset context variables. See `ContextVar.set()`.

  Added in version 3.14: Added support for usage as a context manager.

  var

    Властивість лише для читання. Вказує на об’єкт `ContextVar`, який створив маркер.

  old_value

    A read-only property. Set to the value the variable had before the `ContextVar.set()` method call that created the token. It points to `Token.MISSING` if the variable was not set before the call.

  MISSING

    Об’єкт-маркер, який використовується `Token.old_value`.

## Ручне керування контекстом

contextvars.copy_context()

  Повертає копію поточного об’єкта `Context`.

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

      ctx: Context = copy_context()
      print(list(ctx.items()))

  The function has an O(1) complexity, i.e. works equally fast for contexts with a few context variables and for contexts that have a lot of them.

class contextvars.Context

  Відображення `ContextVars` на їхні значення.

  `Context()` створює порожній контекст без значень у ньому. Щоб отримати копію поточного контексту, використовуйте функцію `copy_context()`.

  Each thread has its own effective stack of `Context` objects. The current context is the `Context` object at the top of the current thread’s stack. All `Context` objects in the stacks are considered to be entered.

  Entering a context, which can be done by calling its `run()` method, makes the context the current context by pushing it onto the top of the current thread’s context stack.

  Exiting from the current context, which can be done by returning from the callback passed to the `run()` method, restores the current context to what it was before the context was entered by popping the context off the top of the context stack.

  Since each thread has its own context stack, `ContextVar` objects behave in a similar fashion to `threading.local()` when values are assigned in different threads.

  Attempting to enter an already entered context, including contexts entered in other threads, raises a `RuntimeError`.

  After exiting a context, it can later be re-entered (from any thread).

  Any changes to `ContextVar` values via the `ContextVar.set()` method are recorded in the current context. The `ContextVar.get()` method returns the value associated with the current context. Exiting a context effectively reverts any changes made to context variables while the context was entered (if needed, the values can be restored by re-entering the context).

  Context реалізує інтерфейс `collections.abc.Mapping`.

  run(callable, *args, **kwargs)

    Enters the Context, executes `callable(*args, **kwargs)`, then exits the Context. Returns callable’s return value, or propagates an exception if one occurred.

    приклад:

        import contextvars

        var = contextvars.ContextVar('var')
        var.set('spam')
        print(var.get())  # 'spam'

        ctx = contextvars.copy_context()

        def main():
            # 'var' was set to 'spam' before
            # calling 'copy_context()' and 'ctx.run(main)', so:
            print(var.get())  # 'spam'
            print(ctx[var])  # 'spam'

            var.set('ham')

            # Now, after setting 'var' to 'ham':
            print(var.get())  # 'ham'
            print(ctx[var])  # 'ham'

        # Any changes that the 'main' function makes to 'var'
        # will be contained in 'ctx'.
        ctx.run(main)

        # The 'main()' function was run in the 'ctx' context,
        # so changes to 'var' are contained in it:
        print(ctx[var])  # 'ham'

        # However, outside of 'ctx', 'var' is still set to 'spam':
        print(var.get())  # 'spam'

  copy()

    Повертає поверхневу копію об’єкта контексту.

  var in context

    Повертає `True`, якщо контекст має встановлене значення var; інакше поверніть `False`.

  context[var]

    Повертає значення змінної var `ContextVar`. Якщо змінна не встановлена в об’єкті контексту, виникає `KeyError`.

  get(var[, default])

    Повертає значення для var, якщо var має значення в об’єкті контексту. Повернути за замовчуванням інакше. Якщо default не вказано, поверніть `None`.

  iter(context)

    Повертає ітератор над змінними, що зберігаються в об’єкті контексту.

  len(proxy)

    Повертає кількість змінних, встановлених в об’єкті контексту.

  keys()

    Повертає список усіх змінних в об’єкті контексту.

  values()

    Повертає список усіх значень змінних в об’єкті контексту.

  items()

    Повертає список 2-кортежів, що містить усі змінні та їхні значення в контекстному об’єкті.

## підтримка asyncio

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

    import asyncio
    import contextvars

    client_addr_var = contextvars.ContextVar('client_addr')

    def render_goodbye():
        # The address of the currently handled client can be accessed
        # without passing it explicitly to this function.

        client_addr = client_addr_var.get()
        return f'Good bye, client @ {client_addr}\r\n'.encode()

    async def handle_request(reader, writer):
        addr = writer.transport.get_extra_info('socket').getpeername()
        client_addr_var.set(addr)

        # In any code that we call, it is now possible to get the
        # client's address by calling 'client_addr_var.get()'.

        while True:
            line = await reader.readline()
            print(line)
            if not line.strip():
                break

        writer.write(b'HTTP/1.1 200 OK\r\n')  # status line
        writer.write(b'\r\n')  # headers
        writer.write(render_goodbye())  # body
        writer.close()

    async def main():
        srv = await asyncio.start_server(
            handle_request, '127.0.0.1', 8081)

        async with srv:
            await srv.serve_forever()

    asyncio.run(main())

    # To test it you can use telnet or curl:
    #     telnet 127.0.0.1 8081
    #     curl 127.0.0.1:8081