add stub for contextvars.pyi

[JelleZijlstra]

See PEP 567 and https://docs.python.org/dev/library/contextvars.html#module-contextvars.

Part of #1965.

[gvanrossum]

@1st1 Can you have a quick look here?

[1st1]

default is not a required parameter. It's not typing.Optional either, as it is either of type _T or not passed at all (None is not a valid value).

A couple of examples:

# valid:
int_var: ContextVar[int] = ContextVar(default=1)
int_var: ContextVar[int] = ContextVar()

# invalid:
int_var: ContextVar[int] = ContextVar(default=None)

and

# valid:
int_var: ContextVar[Optional[int]] = ContextVar(default=1)
int_var: ContextVar[Optional[int]] = ContextVar(default=None)
int_var: ContextVar[Optional[int]] = ContextVar()

Here's a pure Python implementaion of PEP 567 / ContextVar: https://github.com/MagicStack/contextvars/blob/master/contextvars/__init__.py#L111

I'm not sure how to express this in terms of typing. Maybe

class ContextVar(Generic[_T]):
    def __init__(self, name: str, *, default: _T=...) -> None: ...

?

[JelleZijlstra]

We can write *, default: _T = .... Sorry for missing this.

[gvanrossum]

Jelle: If = ... doesn't work, you can use an overload (once without, once with default).

[1st1]

NP!

[1st1]

LGTM.

I wish there was a way to express Token.old_value more clearly, but since Token.MISSING is not a type we can't use a union type there, right?

[JelleZijlstra]

Yes, I couldn't think of a clean way. An approach I thought of was to define a fake type like class _Missing: ... and then define MISSING as being of type _Missing, and have old_value return Union[_T, _Missing]. However, I assume the idiomatic way of using old_value would be something like:

val = token.old_value()
if val is token.MISSING:
     # do something
else:
     # do something else

and with the proposed type annotations I don't think mypy would be able to infer that val is not MISSING in the else branch.

So unless Guido can think of something better, we should probably go with Any.

[1st1]

However, I assume the idiomatic way of using old_value would be something like:

FWIW I think that the primary use-case for Token.old_value will be debugging.

[gvanrossum]

Go ahead and merge!