gh-135447: Document `NOT_TAKEN` & `POP_ITER` bytecode instructions by Yzi-Li · Pull Request #135803 · python/cpython · GitHub

Document:

BUILD_TEMPLATE
BUILD_INTERPOLATION
NOT_TAKEN
POP_ITER
Remove BINARY_SUBSCR

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

📚 Documentation preview 📚: https://cpython-previews--135803.org.readthedocs.build/

@Fidget-Spinner I did a PR to fix the issue. I'm not sure if my expression is correct, so could you take a look? Thanks!

I think there's some misconception happening here, but no worries, I'll explain how to interpret the bytecode.

To document a new bytecode, you need to go to this file https://github.com/python/cpython/blob/main/Python/bytecodes.c . Then, find the bytecode definition (for example, inst(BUILD_INTERPOLATION). Everything after the comma and to the left of the -- are the stack inputs, everything to the right are stack outputs. So for example, inst(BUILD_INTERPOLATION, (value, str, format[oparg & 1] -- interpolation)) should be documented as:

``BUILD_INTERPOLATION`` expects as stack inputs:
* ``STACK[oparg & 1]`` should be ``format``
* ``STACK[-1 - (oparg & 1)]`` should be ``str``
* ``STACK[-2 - (oparg & 1)]`` should be ``value``

``BUILD_INTERPOLATION`` outputs the interpolation object to TOS after consuming its inputs

Based on this, are you able to infer the behavior of BUILD_TEMPLATE :) ?

Based on this, are you able to infer the behavior of BUILD_TEMPLATE :) ?

I have seen what you wrote. And I think I am able to express it.

But I've been a little busy recently so I might need a couple of days — sorry for the delay.

Nice, this is pretty close. One small error: it's the other way around, interpolations is STACK[-1], string is STACK[-2]. This is because the bytecode definition file models a stack (LIFO), which means the rightmost element is the top of the stack.

Co-authored-by: Ken Jin <kenjin4096@gmail.com>

I forgot what NOT_TAKEN does, but the rest look good. Maybe @iritkatriel knows?

It indeed does nothing. Not sure it's related to prediction though. It think it's to give tracing applications like code coverage a way to distinguish between the taken/not taken branches.

CC @markshannon

pure inst(NOP, (--)) {
}

family(RESUME, 0) = {
    RESUME_CHECK,
};

macro(NOT_TAKEN) = NOP;

Can we consider its behavior to be the same as NOP?

Yes its a NOP but I forgot if its a hint or not.

Sorry, I did some meaningless commits.

I'm off next week. If no one else gets to it, I'll review the new changes the 2 weeks from now.

@Fidget-Spinner do you have any further comments/reviews/objections? Would be good to document the 3.14 bytecodes, either in this PR or a different one.

A

…N docs

I'll merge this, it adds documentation for two missing bytecode instructions for 3.14. Further improvements & other bytecodes can come later.

A

Thanks @Yzi-Li for the PR, and @AA-Turner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

…nstructions (pythonGH-135803) (cherry picked from commit 519bc47) Co-authored-by: Yongzi Li <204532581+Yzi-Li@users.noreply.github.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Ken Jin <kenjin4096@gmail.com>

GH-139399 is a backport of this pull request to the 3.14 branch.

…instructions (GH-135803) (#139399) Co-authored-by: Yongzi Li <204532581+Yzi-Li@users.noreply.github.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Ken Jin <kenjin4096@gmail.com>

Document BUILD_TEMPLATE

94bf17a

bedevere-app Bot added docs Documentation in the Doc dir skip news labels Jun 22, 2025

github-project-automation Bot added this to Docs PRs Jun 22, 2025

bedevere-app Bot mentioned this pull request Jun 22, 2025

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

Open

6 tasks

github-project-automation Bot moved this to Todo in Docs PRs Jun 22, 2025

Yzi-Li added 5 commits June 22, 2025 09:41

Add newline

43f3a54

Document BUILD_INTERPOLATION

528ca6f

Use it

f1c4585

Document NOT_TAKEN

7bb0dc5

Delete refs

bdd8855

Yzi-Li commented Jun 22, 2025

View reviewed changes

Comment thread Doc/library/dis.rst Outdated

Comment thread Doc/library/dis.rst Outdated

Yzi-Li marked this pull request as ready for review June 22, 2025 03:42

bedevere-app Bot added the awaiting review label Jun 22, 2025

Yzi-Li added 2 commits June 25, 2025 20:00

Fix according to bytecodes.c

ce4ffa6

Fix lint

2a05bc6

Fidget-Spinner reviewed Jun 25, 2025

View reviewed changes

Fix a small error

c88907c

Fidget-Spinner reviewed Jun 25, 2025

View reviewed changes

Comment thread Doc/library/dis.rst Outdated

Update Doc/library/dis.rst

265a88a

Co-authored-by: Ken Jin <kenjin4096@gmail.com>

Fidget-Spinner reviewed Jun 25, 2025

View reviewed changes

Yzi-Li added 6 commits July 6, 2025 12:55

Document BUILD_TEMPLATE

2ddfa8e

Add newline

0352fe3

Document BUILD_INTERPOLATION

d54d487

Use it

30b8007

Document NOT_TAKEN

7e53639

Delete refs

c51e87d

Yzi-Li added 6 commits July 6, 2025 12:55

Fix according to bytecodes.c

1d79895

Fix lint

e279660

Fix a small error

572b3a0

Merge branch 'main' into fix-issue-135447

52cef36

Fix conflict

a5f4482

Add POP_ITER

a1ee14c

Yzi-Li requested a review from Fidget-Spinner July 11, 2025 10:55

Merge branch 'main' into fix-issue-135447

0550bd2

AA-Turner added the needs backport to 3.14 bugs and security fixes label Sep 21, 2025

AA-Turner added 2 commits September 28, 2025 17:02

Merge branch 'main' into fix-issue-135447

542aaa4

Remove duplicate BUILD_INTERPOLATION/BUILD_TEMPLATE; clarify NOT_TAKE…

cabee26

…N docs

AA-Turner changed the title gh-135447: Document new bytecodes in 3.14 gh-135447: Document NOT_TAKEN & POP_ITER bytecode instructions Sep 28, 2025

AA-Turner enabled auto-merge (squash) September 28, 2025 16:39

AA-Turner merged commit 519bc47 into python:main Sep 28, 2025
27 checks passed

github-project-automation Bot moved this from Todo to Done in Docs PRs Sep 28, 2025

bedevere-app Bot removed the awaiting review label Sep 28, 2025

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Sep 28, 2025

Yzi-Li deleted the fix-issue-135447 branch October 12, 2025 05:06

-                 Create a Template object consuming interpolations and a string from the stack,
-                 and pushes it onto the stack.
+                 It consumes ``STACK[-1]``(string) and ``STACK[-2]``(interpolations) and

		Do nothing code. Used as a hint to the interpreter that a branch was predicted
		as not taken.

gh-135447: Document `NOT_TAKEN` & `POP_ITER` bytecode instructions by Yzi-Li · Pull Request #135803 · python/cpython · GitHub

Uh oh!

Uh oh!

gh-135447: Document NOT_TAKEN & POP_ITER bytecode instructions - #135803

gh-135447: Document NOT_TAKEN & POP_ITER bytecode instructions#135803AA-Turner merged 25 commits intopython:mainpython/cpython:mainfrom Yzi-Li:fix-issue-135447Yzi-Li/cpython:fix-issue-135447Copy head branch name to clipboard

Conversation

Yzi-Li commented Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Yzi-Li commented Jun 22, 2025

Uh oh!

Fidget-Spinner commented Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Yzi-Li commented Jun 23, 2025

Uh oh!

Fidget-Spinner Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Fidget-Spinner Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

iritkatriel Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Yzi-Li Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Fidget-Spinner Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Yzi-Li commented Jul 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Fidget-Spinner commented Jul 11, 2025

Uh oh!

AA-Turner commented Sep 21, 2025

Uh oh!

AA-Turner commented Sep 28, 2025

Uh oh!

Uh oh!

miss-islington-app Bot commented Sep 28, 2025

Uh oh!

bedevere-app Bot commented Sep 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

gh-135447: Document NOT_TAKEN & POP_ITER bytecode instructions#135803
AA-Turner merged 25 commits into
python:mainfrom
Yzi-Li:fix-issue-135447

Yzi-Li commented Jun 22, 2025 •
edited
Loading

Fidget-Spinner commented Jun 22, 2025 •
edited
Loading

Yzi-Li commented Jul 6, 2025 •
edited
Loading