Please find attached a docs patch for PEP 492 changes.

I'd really appreciate if someone can review it / help me with it.  I think it's important to have at least some documentation shipped with beta-1, so that people start testing the feature.

Patch looks worth merging to me. Some minor questions/quibbles:

Asynchronous iterator question: should the typical pattern for those be:

    def __aiter__(self):
        return self
    def __await__(self):
        return self

"Did we put the ABC's in the right place?" question: reviewing the draft docs meant I just noticed that collections.abc is quite an odd home for some of these. Probably not worth worrying about, given that AsyncIterator and AsyncIterable do belong, and the others are building blocks for those.

The What's New entry can be tweaked to replace "proposes" with "added".

New changeset 548d5704fcb3 by Yury Selivanov in branch 'default':
Issue 24180: Documentation for PEP 492 changes.
https://hg.python.org/cpython/rev/548d5704fcb3

Thanks for the review Nick.  I committed the patch with some additional minor fixes, including your suggestion.

> Asynchronous iterator question: should the typical pattern for those be:

    def __aiter__(self):
        return self
    def __await__(self):
        return self


Well, adding __await__ to asynchronous iterators is the same as adding __call__ to regular iterators.  It would be like:

    i = iter(iterable)               # __iter__
    i = iterable()                   # __call__
   
    ai = await iterable.__aiter__()  # __aiter__
       # or "ai = await aiter(iterable)", but we don't have it yet

    ai = await iterable              # __await__


> "Did we put the ABC's in the right place?" question: reviewing the draft docs meant I just noticed that collections.abc is quite an odd home for some of these. Probably not worth worrying about, given that AsyncIterator and AsyncIterable do belong, and the others are building blocks for those.

I had this question too.  My impression is that Guido doesn't want to fix this in 3.5.  FWIW, my initial suggestion was to have "Coroutine", "Awaitable" and "Hashable" in the top-level "abc" module (not ideal by any means).

Hi Yury,

Here is a post commit review. I've mostly removed some additional PEP 492 mentions and made a couple of trivial changes.

New changeset 5691d2d2d0a4 by Yury Selivanov in branch 'default':
Issue 24180: Fixes by Berker Peksag.
https://hg.python.org/cpython/rev/5691d2d2d0a4

Hi Berker, thanks for the review. I think all your edits are reasonable, so I've just committed your patch as is.

Closing this issue.

New changeset 3eb817e19090 by Yury Selivanov in branch '3.5':
Issue 24180: Document sys.(set|get)_coroutine_wrapper
https://hg.python.org/cpython/rev/3eb817e19090

New changeset ca489c50fbd1 by Yury Selivanov in branch 'default':
Issue 24180: Document sys.(set|get)_coroutine_wrapper
https://hg.python.org/cpython/rev/ca489c50fbd1

New changeset 8a185bb62a25 by Yury Selivanov in branch '3.5':
Issue 24180: Mention sys.(get|set)_coroutine_wrapper in whatsnew
https://hg.python.org/cpython/rev/8a185bb62a25

New changeset 10f92b4d55ed by Yury Selivanov in branch 'default':
Issue 24180: Mention sys.(get|set)_coroutine_wrapper in whatsnew
https://hg.python.org/cpython/rev/10f92b4d55ed

stage: patch review -> resolved

assignee: yselivanov
components: + Documentation
keywords: + patch
stage: needs patch -> patch review