Skip to content

Bytecode changes in 3.14 are not documented in dis module docs #135447

Open
Open
Bytecode changes in 3.14 are not documented in dis module docs#135447
Labels
3.14bugs and security fixesdocsDocumentation in the Doc dirtype-bugAn unexpected behavior, bug, or error

Description

@Techcable
Techcable
opened on Jun 12, 2025

Documentation

The module documentation for dis normally contains documentation for all non-specialized bytecode instructions.

However, many of the new bytecode instructions added in 3.14 (BUILD_INTERPOLATION, NOT_TAKEN, etc) are missing from the 3.14 module docs. Some changes to existing instructions like CALL_FUNCTION_EX are also undocumented.

  • BUILD_TEMPLATE
  • BUILD_INTERPOLATION
  • NOT_TAKEN
  • POP_ITER
  • CALL_FUNCTION_EX (changed)
  • Remove BINARY_SUBSCR

Based on pycore_magic_number.h, it appears all changes after Python 3.14a2 with magic number 3609 are undocumented. Changes before this, like the addition of LOAD_SMALL_INT are correctly documented.

Linked PRs

Activity

  1. Techcable
    added
    docsDocumentation in the Doc dir
    on Jun 12, 2025
  2. github-project-automation
    added this to docs issueson Jun 12, 2025
  3. github-project-automation
    moved this to Todo in docs issueson Jun 12, 2025
  4. AA-Turner
    marked Python 3.14: undocumented opcodes #135628 as a duplicate of this issue on Jun 17, 2025
  5. picnixz
    added
    type-bugAn unexpected behavior, bug, or error
    3.14bugs and security fixes
    on Jun 19, 2025

  6. esc commented on Jun 24, 2025

    @esc
    esc
    on Jun 24, 2025
    Contributor

    Can you add POP_ITER:

    #128445 (comment)

    it seems to be missing too.

  7. esc commented on Jun 24, 2025

    @esc
    esc
    on Jun 24, 2025
    Contributor

    The description is not accurate, LOAD_SMALL_INT is documented:

    Image

  8. esc commented on Jun 24, 2025

    @esc
    esc
    on Jun 24, 2025
    Contributor

    Anyone know how CALL_FUNCTION_EX was changed, flags could be None?

  9. Techcable commented on Jun 25, 2025

    @Techcable
    Techcable
    on Jun 25, 2025
    Author

    Can you add POP_ITER:

    Added

    The description is not accurate, LOAD_SMALL_INT is documented:

    You are correct. It appears that some of the older 3.14 bytecodes are documented. Based on pycore_magic_number.h, LOAD_SMALL_INT was added in Python 3.14a2 with magic number 3609. Changes before this are documented, and changes to the bytecode after this are undocumented. I have updated the main comment with this fact and other bytecode changes.

    Anyone know how CALL_FUNCTION_EX was changed, flags could be None?
    Based on pycore_magic_number.h, I think the flag for has_kwargs has been dropped.

  10. esc commented on Jun 26, 2025

    @esc
    esc
    on Jun 26, 2025
    Contributor

    Can you add POP_ITER:

    Added

    Great!

    The description is not accurate, LOAD_SMALL_INT is documented:

    You are correct. It appears that some of the older 3.14 bytecodes are documented. Based on pycore_magic_number.h, LOAD_SMALL_INT was added in Python 3.14a2 with magic number 3609. Changes before this are documented, and changes to the bytecode after this are undocumented. I have updated the main comment with this fact and other bytecode changes.

    Great!

    Anyone know how CALL_FUNCTION_EX was changed, flags could be None?
    Based on pycore_magic_number.h, I think the flag for has_kwargs has been dropped.

    Yeah, that sounds correctish. I also found:

    https://github.com/python/cpython/pull/129226/files

    and that states:

        Python 3.14a5 3615 (CALL_FUNCTION_EX always take a kwargs argument)

  11. esc commented on Jun 26, 2025

    @esc
    esc
    on Jun 26, 2025
    Contributor

    Can you add POP_ITER:

    Added

    Great!

    FWIW: this is the PR that introduced POP_ITER: #128445

  12. esc commented on Jul 1, 2025

    @esc
    esc
    on Jul 1, 2025
    Contributor

    @Techcable can you update the issue, to note that BINARY_SUBSCR functionality is now part of BINARY_OP and also that BEFORE_WITH and BEFORE_ASYNC_WITH were removed and replaced by LOAD_SPECIAL?

  13. black-sliver commented on Aug 22, 2025

    @black-sliver
    black-sliver
    on Aug 22, 2025

    +1

    I am contributing support for newer python versions to a project that analyzes ops (to generate an ast to generate SQL) and missing documentation is really problematic.

    Two more missing pieces of documentation I found, that were both introduced back in 3.13 already:

    • LOAD_GLOBAL/LOAD_ATTR/CALL/... have the two elements on the stack swapped (the self/null and the e.g. callable)
    • need to use protected _varname_from_oparg instead of public co_varnames, not mentioned e.g. here

    Should I open a separate issue for those?

  14. AA-Turner
    added a commit that references this issue on Sep 28, 2025

    gh-135447: Document the ``NOT_TAKEN`` & ``POP_ITER`` bytecode instruc…

    519bc47
  15. miss-islington
    added a commit that references this issue on Sep 28, 2025

    pythongh-135447: Document the ``NOT_TAKEN`` & ``POP_ITER`` bytecode i…

    6ccc17e
  16. hugovk
    added a commit that references this issue on Sep 28, 2025

    [3.14] gh-135447: Document the ``NOT_TAKEN`` & ``POP_ITER`` bytecode …

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    3.14bugs and security fixesdocsDocumentation in the Doc dirtype-bugAn unexpected behavior, bug, or error

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions