Registry / serialization / aiocontextvars

aiocontextvars

library0.2.2pypypi✓ verified 85d ago

aiocontextvars provides asyncio support for the PEP-567 contextvars backport, effectively offering 'task local' storage similar to 'threading.local' but scoped to asyncio tasks. It is primarily relevant for Python versions 3.5 and 3.6, as Python 3.7 and later include native `contextvars` support. The project is currently at version 0.2.2 and is explicitly marked for deprecation once native asyncio contextvars support is fully stable in older backports.

serialization

pip install aiocontextvars

github ↗package ↗

INSTALL

IMPORT

SIG · AIOCONTEXTVARS

aiocontextvars

serializationpythonv0.2.2

Install

1.5s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.2.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ContextVar

✓ from aiocontextvars import ContextVar

copy_context

✓ from aiocontextvars import copy_context

This quickstart demonstrates defining and using a `ContextVar` within an asyncio application. It shows how values set in a parent task are inherited by child tasks upon creation, and how to set and retrieve values using `ContextVar.set()` and `ContextVar.get()`. `ContextVar.reset()` is used with the token returned by `set()` to restore previous context.

import asyncio from aiocontextvars import ContextVar # Define a ContextVar my_variable = ContextVar('my_variable', default='default_value') async def child_task(task_id): current_val = my_variable.get() print(f"Task {task_id}: Initial value in child: {current_val}") my_variable.set(f"value_from_task_{task_id}") print(f"Task {task_id}: New value set in child: {my_variable.get()}") await asyncio.sleep(0.1) async def main(): print(f"Main: Initial value: {my_variable.get()}") token = my_variable.set("main_context_value") print(f"Main: Value after set: {my_variable.get()}") # Spawning child tasks - they inherit the context at creation tasks = [ asyncio.create_task(child_task(1)), asyncio.create_task(child_task(2)) ] await asyncio.gather(*tasks) print(f"Main: Value after children complete: {my_variable.get()}") my_variable.reset(token) print(f"Main: Value after reset: {my_variable.get()}") if __name__ == '__main__': # IMPORTANT: aiocontextvars must be imported BEFORE creating event loops. # For Python 3.5/3.6, ensure aiocontextvars is imported early in your application. asyncio.run(main())

Debug

Known issues

deprecatedThis package is explicitly marked for deprecation. For Python 3.7+ environments, `contextvars` is built into the standard library and should be used directly. This library's primary purpose is a backport for Python 3.5/3.6.

fix

Upgrade to Python 3.7+ and use `import contextvars` directly. For Python 3.5/3.6, continue using `aiocontextvars` but be aware of its maintenance status.

affects: All versions

breakingVersion 0.2.0 introduced significant breaking changes. `ContextVar.delete()` was removed, `enable_inherit()` and `disable_inherit()` functions were removed (inheritance is always enabled), and `ContextVar.set()` now returns a `Token` object which must be used with the newly added `ContextVar.reset(token)` to restore the previous value.

fix

Update code to use `ContextVar.set()` with `token = var.set(value)` and later `var.reset(token)`. Remove calls to deprecated `delete()`, `enable_inherit()`, and `disable_inherit()`.

affects: <0.2.0

gotchaFor correct behavior (especially patching `asyncio.get_event_loop` and `loop.create_task`), `aiocontextvars` MUST be imported at the very beginning of your application, before any asyncio event loops are created. Loops created before the import will not be patched.

fix

Ensure `import aiocontextvars` is one of the first lines of code executed in your application's entry point.

affects: All versions on Python 3.5/3.6

gotchaContexts are copied when a new task is created (e.g., via `asyncio.create_task` or `asyncio.gather`). Changes made to `ContextVar` values in a parent task *after* a child task has been spawned will NOT be visible to that already-running child task, as it operates on a snapshot of the context at its creation time.

fix

Design your application with this snapshot behavior in mind. If you need dynamic updates across tasks, consider passing data explicitly or using other synchronization primitives.

affects: All versions

gotchaWhen using `loop.call_soon()` (or similar low-level scheduling functions) in Python 3.5/3.6 and expecting context inheritance, you must explicitly pass the context. The standard `call_soon` in these versions does not automatically copy the context.

fix

Wrap your callable with `copy_context().run`. Example: `loop.call_soon(copy_context().run, my_method)`.

affects: All versions on Python 3.5/3.6

Errors

Common errors & fixes

LookupError: 'ContextVar' has no value in this context

Attempting to retrieve the value of a `ContextVar` using `var.get()` before a value has been set in the current execution context.

fix

Ensure `var.set(value)` is called at least once in the current context (or a parent context if inherited) before calling `var.get()`. You can also provide a default value when initializing the `ContextVar`: `my_variable = ContextVar('my_variable', default='initial_value')`.

AttributeError: 'ContextVar' object has no attribute 'delete'

Attempting to use the `delete()` method on a `ContextVar` object, which was removed in version 0.2.0.

fix

Replace `var.delete()` with `var.reset(token)` where `token` was the result of the `var.set()` call you wish to revert. If no token is available, you cannot 'delete' a value, only reset to a prior state.

Context not propagating correctly with uvloop or custom task factories.

`aiocontextvars` patches `asyncio.get_event_loop` and `loop.create_task`. Custom event loop implementations (like `uvloop`) or directly creating `asyncio.Task` instances via private APIs might bypass these patches, leading to incorrect context propagation.

fix

Always use public `asyncio` APIs (e.g., `asyncio.run()`, `asyncio.create_task()`, `asyncio.get_event_loop()`) and ensure `aiocontextvars` is imported at startup. If using `uvloop`, consider if `aiocontextvars` is the right solution, as `uvloop` might need specific integration not provided by this library.

Upgrade

Version history

0.2.2latest on PyPI · released Apr 8, 2019

Audit

Dependencies

contextvarsrequiredRequired for Python 3.5/3.6 as a PEP-567 backport dependency. Not needed for Python 3.7+ as contextvars is built-in.

Agent activity

44 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/fantix/aiocontextvars ↗

packagehttps://pypi.org/project/aiocontextvars/ ↗