[Python-Dev] PEP 567 v3 (original) (raw)

Tue Jan 16 17:44:14 EST 2018

# Declare a context variable 'var' with the default value 42.
var = ContextVar('var', default=42)
# Get the value of `var`.
var.get()
# Set the variable 'var' to 1 in the current context.
var.set(1)
assert var.get(None) is None

token = var.set(1)
try:
    ...
finally:
    var.reset(token)

assert var.get(None) is None
ctx = contextvars.copy_context()
ctx.run(function)
var = ContextVar('var')
var.set('spam')

def function():
    assert var.get() == 'spam'
    assert ctx[var] == 'spam'

    var.set('ham')
    assert var.get() == 'ham'
    assert ctx[var] == 'ham'

ctx = copy_context()

# Any changes that 'function' makes to 'var' will stay
# isolated in the 'ctx'.
ctx.run(function)

assert var.get() == 'spam'
assert ctx[var] == 'ham'
ctx = contextvars.copy_context()

# Print all context variables and their values in 'ctx':
print(ctx.items())

# Print the value of 'some_variable' in context 'ctx':
print(ctx[some_variable])
def call_soon(self, callback, *args, context=None):
    if context is None:
        context = contextvars.copy_context()

    # ... some time later
    context.run(callback, *args)
class Task:
    def __init__(self, coro):
        ...
        # Get the current context snapshot.
        self._context = contextvars.copy_context()
        self._loop.call_soon(self._step, context=self._context)

    def _step(self, exc=None):
        ...
        # Every advance of the wrapped coroutine is done in
        # the task's context.
        self._loop.call_soon(self._step, context=self._context)
        ...
class _ContextData:

    def __init__(self):
        self._mapping = dict()

    def get(self, key):
        return self._mapping[key]

    def set(self, key, value):
        copy = _ContextData()
        copy._mapping = self._mapping.copy()
        copy._mapping[key] = value
        return copy

    def delete(self, key):
        copy = _ContextData()
        copy._mapping = self._mapping.copy()
        del copy._mapping[key]
        return copy
class PyThreadState:
    context: Context
class Context(collections.abc.Mapping):

    _data: _ContextData
    _prev_context: Optional[Context]

    def __init__(self):
        self._data = _ContextData()
        self._prev_context = None

    def run(self, callable, *args, **kwargs):
        if self._prev_context is not None:
            raise RuntimeError(
                f'cannot enter context: {self} is already entered')

        ts: PyThreadState = PyThreadState_Get()
        if ts.context is None:
            ts.context = Context()

        self._prev_context = ts.context
        try:
            ts.context = self
            return callable(*args, **kwargs)
        finally:
            ts.context = self._prev_context
            self._prev_context = None

    def copy(self):
        new = Context()
        new._data = self._data
        return new

    # Mapping API methods are implemented by delegating
    # `get()` and other Mapping methods to `self._data`.
def copy_context():
    ts: PyThreadState = PyThreadState_Get()

    if ts.context is None:
        ts.context = Context()

    return ts.context.copy()
class ContextVar:

    def __init__(self, name, *, default=_NO_DEFAULT):
        self._name = name
        self._default = default

    @property
    def name(self):
        return self._name

    def get(self, default=_NO_DEFAULT):
        ts: PyThreadState = PyThreadState_Get()
        if ts.context is not None:
            try:
                return ts.context[self]
            except KeyError:
                pass

        if default is not _NO_DEFAULT:
            return default

        if self._default is not _NO_DEFAULT:
            return self._default

        raise LookupError

    def set(self, value):
        ts: PyThreadState = PyThreadState_Get()
        if ts.context is None:
            ts.context = Context()

        data: _ContextData = ts.context._data
        try:
            old_value = data.get(self)
        except KeyError:
            old_value = Token.MISSING

        updated_data = data.set(self, value)
        ts.context._data = updated_data
        return Token(ts.context, self, old_value)

    def reset(self, token):
        if token._var is not self:
            raise ValueError(
                "Token was created by a different ContextVar")

        ts: PyThreadState = PyThreadState_Get()
        if token._ctx is not ts.context:
            raise ValueError(
                "Token was created in a different Context")

        if token._used:
            return

        if token._old_value is Token.MISSING:
            ts.context._data = data.delete(token._var)
        else:
            ts.context._data = data.set(token._var,
                                        token._old_value)

        token._used = True
class Token:

    MISSING = object()

    def __init__(self, ctx, var, old_value):
        self._ctx = ctx
        self._var = var
        self._old_value = old_value
        self._used = False

    @property
    def var(self):
        return self._var

    @property
    def old_value(self):
        return self._old_value
token = cv.get()
try:
    cv.set(blah)
    # code
finally:
    cv.reset(token)
_deleted = object()
old = cv.get(default=_deleted)
try:
    cv.set(blah)
    # code
finally:
    if old is _deleted:
        cv.unset()
    else:
        cv.set(old)
class mylocal(threading.local):
    # Subclass threading.local to specify a default value.
    value = 'spam'

mylocal = mylocal()

# To set a new value:
mylocal.value = 'new value'

# To read the current value:
mylocal.value
mylocal = contextvars.ContextVar('mylocal', 'spam')

# To set a new value:
mylocal.set('new value')

# To read the current value:
mylocal.get()
executor = ThreadPoolExecutor()
current_context = contextvars.copy_context()

executor.submit(
    lambda: current_context.run(some_function))

[Python-Dev] PEP 567 v3 (original) (raw)

Abstract

Rationale

Introduction

Specification

contextvars.ContextVar

contextvars.Token

contextvars.Context

asyncio

Implementation

Summary of the New APIs

Python API

C API

Design Considerations

Why contextvars.Token and not ContextVar.unset()?

Rejected Ideas

Replication of threading.local() interface

Backwards Compatibility

Examples

Converting code that uses threading.local()

Offloading execution to other threads

Reference Implementation

References

Copyright