classification
Title: dis module: coroutine opcode documentation clarity
Type: Stage: needs patch
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: yselivanov Nosy List: Jim.Jewett, serhiy.storchaka, yselivanov
Priority: normal Keywords:

Created on 2016-02-04 21:08 by Jim.Jewett, last changed 2018-03-22 09:34 by serhiy.storchaka.

Messages (2)
msg259595 - (view) Author: Jim Jewett (Jim.Jewett) * (Python triager) Date: 2016-02-04 21:07
https://docs.python.org/3/library/dis.html includes a section describing the various opcodes.

Current documentation: """
Coroutine opcodes

GET_AWAITABLE
Implements TOS = get_awaitable(TOS), where get_awaitable(o) returns o if o is a coroutine object or a generator object with the CO_ITERABLE_COROUTINE flag, or resolves o.__await__.

GET_AITER
Implements TOS = get_awaitable(TOS.__aiter__()). See GET_AWAITABLE for details about get_awaitable

GET_ANEXT
Implements PUSH(get_awaitable(TOS.__anext__())). See GET_AWAITABLE for details about get_awaitable

BEFORE_ASYNC_WITH
Resolves __aenter__ and __aexit__ from the object on top of the stack. Pushes __aexit__ and result of __aenter__() to the stack.

SETUP_ASYNC_WITH
Creates a new frame object.
"""

(1)  There is a PUSH macro in ceval.c, but no PUSH bytecode.  I spent a few minutes trying to figure out what a PUSH command was, and how the GET_ANEXT differed from 
    TOS = get_awaitable(TOS.__anext__())
which would match the bytecodes right above it.

After looking at ceval.c, I think GET_ANEXT is the only such bytecode to leave the original TOS in place, but I'm not certain about that.  Please be explicit.  (Unless they are the same, in which case, please use the same wording.)
 
(2)  The coroutine bytecode instructions should have a "New in 3.5" marker, as the GET_YIELD_FROM_ITER does.  It might make sense to just place the mark under Coroutine opcodes section header and say it applies to all of them, instead of marking each individual opcode.  

(3)  The GET_AITER and GET_ANEXT descriptions do not show the final period.  Opcodes such as INPLACE_LSHIFT also end with a code quote, but still include a (not-marked-as-code) final period.

(4)  Why does SETUP_ASYNC_WITH talk about frames?  Is there actually a python frame involved, or is this another bytecode "block", similar to that used for except and finally?
msg314240 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-03-22 09:34
(2) is already fixed.

SETUP_ASYNC_WITH talks about the same frame blocks as pushed by SETUP_FINALLY, SETUP_EXCEPT, SETUP_LOOP and popped by POP_BLOCK. But unlike to SETUP_FINALLY it pushes a frame block pointing below TOS. This detail needs to be documented.

Do you mind to create a pull request Jim?
History
Date User Action Args
2018-03-22 09:34:33serhiy.storchakasetnosy: + serhiy.storchaka

messages: + msg314240
versions: + Python 3.6, Python 3.7, Python 3.8, - Python 3.5
2016-02-04 21:08:00Jim.Jewettcreate