Implement AsyncGenerator type annotation

[em92]

typing.AsyncGenerator was added in 3.5.4 https://github.com/python/cpython/commit/e9ed560fcec8d2d1f9705e93049cdb3790d40838

debian stretch python3 has version 3.5.3. https://packages.debian.org/stretch/python3

Implementation itself is based on original cpython commit above

[codecov[bot]]

Codecov Report

Merging #25 into master will decrease coverage by 1.06%. The diff coverage is 100%.

@@            Coverage Diff             @@
##           master      #25      +/-   ##
==========================================
- Coverage     100%   98.93%   -1.07%     
==========================================
  Files           7        8       +1     
  Lines         972     1037      +65     
  Branches       77       79       +2     
==========================================
+ Hits          972     1026      +54     
- Misses          0        7       +7     
- Partials        0        4       +4

Impacted Files	Coverage Δ
async_generator/__init__.py	100% <100%> (ø)	:arrow_up:
async_generator/typing.py	100% <100%> (ø)
async_generator/_util.py	96.36% <0%> (-3.64%)	:arrow_down:
async_generator/_impl.py	98.53% <0%> (-1.47%)	:arrow_down:
async_generator/_tests/test_async_generator.py	98.98% <0%> (-1.02%)	:arrow_down:
async_generator/_tests/conftest.py	100% <0%> (ø)	:arrow_up:
async_generator/_tests/test_util.py	100% <0%> (ø)	:arrow_up:

[codecov[bot]]

Codecov Report

Merging #25 into master will decrease coverage by 1.06%. The diff coverage is 100%.

@@            Coverage Diff             @@
##           master      #25      +/-   ##
==========================================
- Coverage     100%   98.93%   -1.07%     
==========================================
  Files           7        8       +1     
  Lines         972     1037      +65     
  Branches       77       79       +2     
==========================================
+ Hits          972     1026      +54     
- Misses          0        7       +7     
- Partials        0        4       +4

Impacted Files	Coverage Δ
async_generator/__init__.py	100% <100%> (ø)	:arrow_up:
async_generator/typing.py	100% <100%> (ø)
async_generator/_util.py	96.36% <0%> (-3.64%)	:arrow_down:
async_generator/_impl.py	98.53% <0%> (-1.47%)	:arrow_down:
async_generator/_tests/test_async_generator.py	98.98% <0%> (-1.02%)	:arrow_down:
async_generator/_tests/conftest.py	100% <0%> (ø)	:arrow_up:
async_generator/_tests/test_util.py	100% <0%> (ø)	:arrow_up:

[oremanj]

This looks reasonable once you fix CI (there's a formatting nit, plus 3.5.0's typing doesn't even have AsyncIterator).

If your goal is to be able to write stubs for @async_generator, you should anticipate some challenges:

• I looked for a while and couldn't find a way to get mypy to validate the send/yield types of the generator -- effectively the type of yield_ depends on the type of the generator it's in, and mypy doesn't have a good way to support that (it supports native yield but in a way that's hardcoded)
• There's not a great place to write the yield/send types because the decorated function's return type doesn't depend on them.

The best solution I can think of is to modify the async_generator decorator to permit @async_generator(yield_type=Foo [, send_type=Bar]) and just take it on faith that the user in fact interacts with yield_ in the way they've promised to. That's not great but it's better than nothing... It might also be possible to do something clever with a mypy plugin in a way that escaped me.

[oremanj]

I just released the trio-typing package which includes an AsyncGenerator type (as trio_typing.AsyncGenerator). Maybe it's sufficient for your needs? It also includes a mypy plugin that lets you (somewhat hackishly) specify the yield and send types of an @async_generator function and get await yield_() calls type-checked accordingly.

I'm not against merging this PR too, if you make it work on 3.5.0 and add a test that exercises the new code.

[em92]

That will be enough. Thanks!