[docs] Document recen changes in typing.py (issue 28644)

[levkivskyi at gmail.com]

http://bugs.python.org/review/28644/diff/19123/Doc/library/typing.rst
File Doc/library/typing.rst (right):

http://bugs.python.org/review/28644/diff/19123/Doc/library/typing.rst#newcode616
Doc/library/typing.rst:616: coro = foo() # type: Coroutine[None, None,
int]
On 2016/11/10 20:47:36, gvanrossum wrote:
> I tested this and it doesn't work, because Coroutine is a subclass of
Awaitable
> (not the other way around).

It looks like this is a bug in mypy. Awaitable[int] is to wide type for
the result of calling async def.

Future, for example, is Awaitable but is not a Coroutine since Future
doesn't have .send(), while async def always results in Coroutine, it
always has .send().

I think in this example inferred type of foo() should be Coroutine[None,
None, int] (the first argument is questionable, since the coroutine in
example never yields, but we don't have a notation for this).

Anyway, I removed this example.

http://bugs.python.org/review/28644/diff/19123/Doc/library/typing.rst#newcode623
Doc/library/typing.rst:623: chat = bar() # type: Coroutine[str, Any,
int]
On 2016/11/10 20:47:36, gvanrossum wrote:
> Sadly this doesn't work either. I get
> 
> __tmp__.py:12: error: Incompatible types in assignment (expression has
type
> AwaitableGenerator[str, Any, int, Generator[str, Any, int]], variable
has type
> Coroutine[str, Any, int])
> 
> Now that seems to be due to a bug in typing.pyi (AwaitableGenerator
should
> inherit from Awaitable[_V_co], not _T_co, I think), but after fixing
that I
> still get an error:
> 
> __tmp__.py:12: error: Incompatible types in assignment (expression has
type
> AwaitableGenerator[str, Any, int, Generator[str, Any, int]], variable
has type
> Coroutine[str, Any, int])
> 
> I could make that go away by replacing Generator with Coroutine in the
> definition of AwaitableGenerator, but that feels fishy (and I'd have
to swap in
> what I was thinking when I implemented async/await in mypy).
> 
> I propose that we leave these examples out for now and get back to
them once
> we've figured out how this actually works...

It also looks like a bug in mypy. As I understand, now we have three
things:

* Normal generator (Generator): could not be used with await, could be
used with yield from.
* Result of @types.coroutine: could be used with both await and yield
from (this is probably the thing called AwaitableGenerator)
* A coroutine (result of calling async def, Coroutine): could be used
with await, but not with yield from.

This somehow reminds me bytes/str/unicode :-) But I think here the
solution is simple. The second type is just an intersection of two
others:

class AwaitableGenerator(Coroutine[T_co, T_contra, V_co],
Generator[T_co, T_contra, V_co]): ...

Actually, the current definition in typing.pyi could also work if mypy
would treat all these types as ABCs (by structural subtyping). So this
is another +1 for Protocol.

Again, I removed this example.

http://bugs.python.org/review/28644/