gh-135447: Document NOT_TAKEN & POP_ITER bytecode instructions

[Yzi-Li]

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/

[Yzi-Li]

@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!

[Fidget-Spinner]

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 :) ?

[Yzi-Li]

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.

[Fidget-Spinner]

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.

[Fidget-Spinner]

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

[iritkatriel]

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

[Yzi-Li]

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

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

macro(NOT_TAKEN) = NOP;

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

[Fidget-Spinner]

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

[Yzi-Li]

Sorry, I did some meaningless commits.

[Fidget-Spinner]

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

[AA-Turner]

@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

[AA-Turner]

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

A

[miss-islington-app]

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

[bedevere-app]

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