Typing Stubs for contextvars

2.4.7.3 · active · verified Fri Apr 17

This package provides static type checking definitions (typing stubs) for the built-in Python `contextvars` standard library module. It enables type checkers like MyPy to correctly analyze code that uses `contextvars`, ensuring type safety without altering runtime behavior. The current version is 2.4.7.3, and releases are tied to updates in the Python standard library and the broader typeshed project.

Common errors

```
Module 'types_contextvars' has no attribute 'ContextVar'
```
cause The user is attempting to import symbols directly from the `types_contextvars` package, which is incorrect. `types_contextvars` is a stub package for static type checking, not a runtime module.

fix Import symbols like `ContextVar` from the standard library `contextvars` module: `from contextvars import ContextVar`.
```
Missing type annotations for 'contextvars' (reportMissingTypeStubs)
```
cause A type checker (like MyPy or Pylance) is reporting that it cannot find type stubs for the `contextvars` module, meaning it cannot properly type-check code using `contextvars`.

fix Install the `types-contextvars` package: `pip install types-contextvars`. Ensure your type checker is configured to use installed stub packages.
```
mypy: error: Incompatible default for argument "default" (item is "None", expected "str")
```
cause This specific MyPy error (or similar) occurs when a `ContextVar` is defined with a type hint that doesn't match the default value, and `types-contextvars` is correctly enforcing the type.

fix Ensure the default value provided to `ContextVar` matches the type annotation, or make the type annotation optional (e.g., `ContextVar[Optional[str]]`) if `None` is an expected default and `from typing import Optional` is used.

Warnings

gotcha Do not attempt to import symbols directly from `types_contextvars` (e.g., `from types_contextvars import ContextVar`). This package only provides type stubs for static analysis, not runtime objects.
Fix: Install `types-contextvars` via pip, but always import symbols (like `ContextVar`, `copy_context`, `Token`) directly from the standard library `contextvars` module: `from contextvars import ContextVar`.
gotcha While typeshed strives for accuracy, stubs might occasionally lag behind the absolute bleeding edge of Python's standard library, especially when using pre-release Python versions or new, undocumented features.
Fix: Ensure your `types-contextvars` package is up-to-date. If encountering type errors for very new features, consider using `typing.Any` for specific annotations as a temporary workaround until updated stubs are released.

Install

pip install types-contextvars Install stubs

Imports

ContextVar
wrong:
```
from types_contextvars import ContextVar
```
correct:
```
from contextvars import ContextVar
```
This package provides type stubs for the built-in `contextvars` module. You install `types-contextvars` but import symbols directly from the standard library `contextvars` module for runtime use, and type checkers will use these installed stubs for analysis.
copy_context
wrong:
```
from types_contextvars import copy_context
```
correct:
```
from contextvars import copy_context
```
As with other symbols, `copy_context` is imported from the standard library `contextvars` module.
Token
wrong:
```
from types_contextvars import Token
```
correct:
```
from contextvars import Token
```
As with other symbols, `Token` is imported from the standard library `contextvars` module.

Quickstart

This example demonstrates basic usage of `contextvars` with type annotations. Installing `types-contextvars` allows static type checkers (like MyPy) to validate the types of `my_var`, `ContextVar` methods, and related functions, ensuring your code adheres to type definitions without affecting runtime execution.

import contextvars

# Define a ContextVar with a type hint
my_var: contextvars.ContextVar[str] = contextvars.ContextVar('my_var', default='default_value')

def worker_task():
    print(f"Worker: my_var is {my_var.get()}")

def main():
    print(f"Main: my_var is {my_var.get()}")
    
    # Set a new value for my_var in the current context
    token = my_var.set('new_value_in_main')
    print(f"Main (after set): my_var is {my_var.get()}")
    
    worker_task()
    
    # Restore the previous value
    my_var.reset(token)
    print(f"Main (after reset): my_var is {my_var.get()}")

if __name__ == '__main__':
    # Installing `types-contextvars` (e.g., `pip install types-contextvars`)
    # allows static type checkers (like MyPy) to validate these type annotations.
    # Example: run `mypy your_script.py` after installation.
    main()

view raw JSON →