Sitelet https://github.com/python/cpython/issues/70474
Skip to content

dis module: coroutine opcode documentation clarity #70474

Closed
#94048
Closed
dis module: coroutine opcode documentation clarity#70474
#94048
Assignees
1st1
Labels
3.7 (EOL)end of life3.8 (EOL)end of lifedocsDocumentation in the Doc dir

Description

@jimjjewett
jimjjewett
mannequin
opened on Feb 4, 2016
BPO 26286
Nosy @JimJJewett, @serhiy-storchaka, @1st1

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 = None
created_at = <Date 2016-02-04.21:08:00.017>
labels = ['3.7', '3.8', 'docs']
title = 'dis module: coroutine opcode documentation clarity'
updated_at = <Date 2018-03-22.09:34:33.404>
user = 'https://github.com/JimJJewett'

bugs.python.org fields:

activity = <Date 2018-03-22.09:34:33.404>
actor = 'serhiy.storchaka'
assignee = 'yselivanov'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2016-02-04.21:08:00.017>
creator = 'Jim.Jewett'
dependencies = []
files = []
hgrepos = []
issue_num = 26286
keywords = []
message_count = 2.0
messages = ['259595', '314240']
nosy_count = 3.0
nosy_names = ['Jim.Jewett', 'serhiy.storchaka', 'yselivanov']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue26286'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']

Activity

  1. jimjjewett commented on Feb 4, 2016

    @jimjjewett
    jimjjewettmannequin
    on Feb 4, 2016
    MannequinAuthor

    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?

  2. jimjjewett
    assigned
    1st1
    on Feb 4, 2016
  3. jimjjewett
    added
    docsDocumentation in the Doc dir
    on Feb 4, 2016

  4. serhiy-storchaka commented on Mar 22, 2018

    @serhiy-storchaka
    serhiy-storchaka
    on Mar 22, 2018
    Member

    (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?

  5. serhiy-storchaka
    added
    3.7 (EOL)end of life
    3.8 (EOL)end of life
    on Mar 22, 2018
  6. ezio-melotti
    transferred this issue fromon Apr 10, 2022
  7. iritkatriel
    added a commit that references this issue on Jun 21, 2022

    pythongh-70474: [doc] fix wording of GET_ANEXT doc

    f1fb8e8

  8. iritkatriel commented on Jun 21, 2022

    @iritkatriel
    iritkatriel
    on Jun 21, 2022
    Member

    I've created a PR for (1) and part of (3), the rest are no longer relevant.

  9. iritkatriel
    closed this as completedin #94048on Jun 25, 2022
  10. iritkatriel
    added a commit that references this issue on Jun 25, 2022

    gh-70474: [doc] fix wording of GET_ANEXT doc (GH-94048)

    9af6b75
  11. miss-islington
    added 4 commits that reference this issue on Jun 25, 2022

    pythongh-70474: [doc] fix wording of GET_ANEXT doc (pythonGH-94048)

    67fc830

    pythongh-70474: [doc] fix wording of GET_ANEXT doc (pythonGH-94048)

    1bb6a17

    gh-70474: [doc] fix wording of GET_ANEXT doc (GH-94048)

    4ec1f8d

    gh-70474: [doc] fix wording of GET_ANEXT doc (GH-94048)

    5f3b45a
  12. serhiy-storchaka
    added a commit that references this issue on Jun 26, 2022

    Revert 30935 defer bpo45162 to 312 (#94285)

    1ffde3e
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

3.7 (EOL)end of life3.8 (EOL)end of lifedocsDocumentation in the Doc dir

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions