PEP 492: Documentation

[1st1]

BPO	24180
Nosy	@gvanrossum, @ncoghlan, @vstinner, @asvetlov, @berkerpeksag, @1st1
Files	async_docs_v1.patch issue24180.diff

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/1st1'
closed_at = <Date 2015-05-22.15:32:41.277>
created_at = <Date 2015-05-13.19:47:26.860>
labels = ['deferred-blocker', 'type-feature', 'docs']
title = 'PEP 492: Documentation'
updated_at = <Date 2015-05-31.21:21:56.701>
user = 'https://github.com/1st1'

bugs.python.org fields:

activity = <Date 2015-05-31.21:21:56.701>
actor = 'python-dev'
assignee = 'yselivanov'
closed = True
closed_date = <Date 2015-05-22.15:32:41.277>
closer = 'yselivanov'
components = ['Documentation']
creation = <Date 2015-05-13.19:47:26.860>
creator = 'yselivanov'
dependencies = []
files = ['39449', '39462']
hgrepos = []
issue_num = 24180
keywords = ['patch']
message_count = 10.0
messages = ['243732', '243742', '243757', '243758', '243789', '243790', '243791', '243833', '244559', '244560']
nosy_count = 7.0
nosy_names = ['gvanrossum', 'ncoghlan', 'vstinner', 'asvetlov', 'python-dev', 'berker.peksag', 'yselivanov']
pr_nums = []
priority = 'deferred blocker'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue24180'
versions = ['Python 3.5']

[1st1]

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.

[ncoghlan]

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

[python-dev]

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

[1st1]

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

[berkerpeksag]

Hi Yury,

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

[python-dev]

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

[1st1]

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

[1st1]

Closing this issue.

[python-dev]

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

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

[python-dev]

New changeset 8a185bb62a25 by Yury Selivanov in branch '3.5':
bpo-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':
bpo-24180: Mention sys.(get|set)_coroutine_wrapper in whatsnew
https://hg.python.org/cpython/rev/10f92b4d55ed