> While I agree this needs to be fixed, one key piece of documentation needed will be to cover how to write an __aiter__ method that does the right thing on both 3.5.1 and 3.5.2+ (and also avoids the deprecation warning in the latter case).

Oh, this is tough.

How about we do this:

1. In 3.5.2 we start to support new behaviour. We raise PendingDeprecationWarning.  We update documentation and PEP 492.  The recommended way to write 3.5 code is to keep returning awaitables from __aiter__.  We can add a snippet of code for a compatibility decorator to the docs.

2. In 3.6 we start to raise DeprecationWarning.  The recommended way to write code for 3.6 & 3.7 is to return async iterators from __aiter__.

3. In 3.7 we remove support of the old behaviour.

It's a rather long & conservative process, but it will be