Add the ability for @async_generator to produce a native async generator

[oremanj]

This improves performance and offers cleaner tracebacks, although native generators continue to have the failure mode of https://bugs.python.org/issue32526 and to provide not-very-clear exception messages when they're misused.

Since the semantics of native async generators are slightly different, this change has @async_generator continue to produce an old-style pure-Python AsyncGenerator by default, with warnings if it looks like bpo-32526 would change the behavior of code that's using the async generator. Users can say @async_generator_legacy to continue to get the old behavior without the warnings, or @async_generator_native to use a native generator where available; my thought is that the next release of async_generator can make @async_generator_native be the default.

Also add an ag_await attribute to legacy async generators, to match the behavior of native ones.

[codecov[bot]]

Codecov Report

Merging #17 into pr15-pr16-combined will not change coverage. The diff coverage is 100%.

@@                Coverage Diff                 @@
##           pr15-pr16-combined    #17    +/-   ##
==================================================
  Coverage                 100%   100%            
==================================================
  Files                       7      7            
  Lines                     991   1108   +117     
  Branches                   78    100    +22     
==================================================
+ Hits                      991   1108   +117

Impacted Files	Coverage Δ
async_generator/_tests/test_async_generator.py	100% <100%> (ø)	:arrow_up:
async_generator/_tests/conftest.py	100% <100%> (ø)	:arrow_up:
async_generator/_tests/test_util.py	100% <100%> (ø)	:arrow_up:
async_generator/_impl.py	100% <100%> (ø)	:arrow_up:
async_generator/__init__.py	100% <100%> (ø)	:arrow_up:

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update df24add...e520187. Read the comment docs.

[oremanj]

I originally made this maximally paranoid about the minor behavioral differences, but on reflection I'm not sure that level of paranoia is necessary -- I think it would reasonable to make @async_generator produce native generators on CPython 3.6+ without a deprecation period, and continue to permit @async_generator(allow_native=False) to use the old pure-Python version always. That reduces the API footprint (exposing @async_generator_legacy and @async_generator_native feels like a wart to me). Thoughts?

[njsmith]

See https://github.com/python-trio/async_generator/pull/16#issuecomment-409523135 for high-level review comments.