contextvars
— Контекстные переменные¶
Этот модуль предоставляет API для управления, хранения и доступа к контекстно-локальному состоянию. Класс ContextVar
используется для объявления и работы с контекстными переменными. Функция copy_context()
и класс Context
должны использоваться для управления текущим контекстом в асинхронных фреймворках.
Менеджеры контекста, имеющие состояние, должны использовать переменные контекста вместо threading.local()
, чтобы предотвратить неожиданную утечку их состояния в другой код, когда они используются в параллельном коде.
Дополнительные сведения см. также в разделе 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])¶
Возвращает значение контекстной переменной для текущего контекста.
Если в текущем контексте нет значения для переменной, метод выполнится:
возвращает значение аргумента по умолчанию метода, если он был предоставлен; или
возвращает значение по умолчанию для контекстной переменной, если она была создана с таким значением; или
поднять
LookupError
.
- set(value)¶
Вызов для установки нового значения для контекстной переменной в текущем контексте.
Обязательный аргумент value - это новое значение для контекстной переменной.
Возвращает объект
Token
, который может быть использован для восстановления предыдущего значения переменной с помощью методаContextVar.reset()
.
- 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.
- class contextvars.Token¶
Объекты Token возвращаются методом
ContextVar.set()
. Их можно передать методуContextVar.reset()
, чтобы вернуть значение переменной к тому, которое было до соответствующего set.- var¶
Свойство, доступное только для чтения. Указывает на объект
ContextVar
, который создал токен.
- old_value¶
Свойство, доступное только для чтения. Устанавливается в значение, которое переменная имела до вызова метода
ContextVar.set()
, создавшего маркер. Указывает наToken.MISSING
, если переменная не была установлена до вызова.
- MISSING¶
Объект-маркер, используемый
Token.old_value
.
Ручное управление контекстом¶
- contextvars.copy_context()¶
Возвращает копию текущего объекта
Context
.Следующий фрагмент получает копию текущего контекста и выводит все переменные и их значения, которые в нем заданы:
ctx: Context = copy_context() print(list(ctx.items()))
Функция имеет сложность O(1), то есть работает одинаково быстро как для контекстов с небольшим количеством контекстных переменных, так и для контекстов с большим их количеством.
- class contextvars.Context¶
Отображение
ContextVars
на их значения.Context()
создает пустой контекст, в котором нет значений. Чтобы получить копию текущего контекста, используйте функциюcopy_context()
.Каждый поток будет иметь свой объект верхнего уровня
Context
. Это означает, что объектContextVar
ведет себя аналогичноthreading.local()
, когда значения присваиваются в разных потоках.Контекст реализует интерфейс
collections.abc.Mapping
.- run(callable, *args, **kwargs)¶
Выполните код
callable(*args, **kwargs)
в объекте контекста, для которого вызван метод run. Верните результат выполнения или передайте исключение, если оно возникло.Любые изменения переменных контекста, которые производит callable, будут содержаться в объекте контекста:
var = ContextVar('var') var.set('spam') def main(): # 'var' was set to 'spam' before # calling 'copy_context()' and 'ctx.run(main)', so: # var.get() == ctx[var] == 'spam' var.set('ham') # Now, after setting 'var' to 'ham': # var.get() == ctx[var] == 'ham' ctx = copy_context() # 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: # ctx[var] == 'ham' # However, outside of 'ctx', 'var' is still set to 'spam': # var.get() == 'spam'
Метод вызывает ошибку
RuntimeError
при вызове одного и того же контекстного объекта из более чем одного потока ОС или при рекурсивном вызове.
- copy()¶
Возвращает неглубокую копию объекта контекста.
- var in context
Возвращает
True
, если в контексте задано значение для var; возвращаетFalse
в противном случае.
- context[var]
Возвращает значение переменной var
ContextVar
. Если переменная не задана в объекте контекста, возникает ошибкаKeyError
.
- get(var[, default])¶
Возвращает значение для var, если var имеет значение в объекте контекста. В противном случае возвращается значение default. Если значение 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}\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 is now possible to get
# client's address by calling 'client_addr_var.get()'.
while True:
line = await reader.readline()
print(line)
if not line.strip():
break
writer.write(line)
writer.write(render_goodbye())
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:
# telnet 127.0.0.1 8081