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

[guido at python.org]

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

http://bugs.python.org/review/28644/diff/19105/Doc/library/typing.rst#newcode444
Doc/library/typing.rst:444: .. class:: Tuple
On 2016/11/10 14:59:14, levkivskyi wrote:
> On 2016/11/09 17:39:42, gvanrossum wrote:
> > I'm not sure I'm comfortable advertising Tuple as a class. While
`class
> > C(Tuple): pass` works, using `class C(Tuple[int, int]): pass`
elicits the
> error
> > (from mypy) "error: Tuple[...] not supported as a base class outside
a stub
> > file".
> 
> Everything else in docs is systematized by the actual implementation.
I am
> marking this simply as :data: (under your responsibility :-) if
someone will
> complain).
> 
> Actually, I think subclassing is also a way of annotating types.
Subclassing
> Tuple[int, str] means that the class supports a certain "API". mypy
already
> supports ``class C(Tuple[int, str]): ...`` this way in stub files.
> 
> It looks like mypy rejects this for normal files only because of
previous
> limitations of typing.py. If I just remove the check, it also works in
normal
> files as well. Also, it looks like Jukka likes allowing this, so that
I will
> make a PR for mypy soon.

Well, inheriting from Tuple doesn't just inherit the type -- it inherits
the implementation as well. This seems to work (although mypy doesn't
understand enough about `__new__` to make it very useful) but I think
it's still mostly a party trick. So for now classifying Tuple under data
seems right.

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#newcode614
Doc/library/typing.rst:614: async def foo() -> str:
Should be -> int

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]
I tested this and it doesn't work, because Coroutine is a subclass of
Awaitable (not the other way around).

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]
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...

http://bugs.python.org/review/28644/diff/19123/Doc/library/typing.rst#newcode874
Doc/library/typing.rst:874: must be a list of types or ellipsis; the
return type must be
or -> or an

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