[3.12] gh-114480: Add docs for f_trace_opcodes behavior on 3.12

[gaogaotiantian]

3.12 introduced a weird behavior for f_trace_opcodes due to PEP 669. We should document it. However, this behavior is fixed in main (3.13) so we only need to document it in 3.12 branch.

• Issue: sys.settrace does not receive opcode events in 3.12.x #114480

---

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

[gaogaotiantian]

Hi @AlexWaygood , do you think a version change section works for this behavior description? Thanks!

[AlexWaygood]

Thanks! This looks good, but I think it's worth pointing out:

1. in the 3.12 docs that the behaviour has already changed in 3.13
2. in the 3.13 docs that the behaviour changed between Python 3.12 and Python 3.13

We had a similar situation with typing.NewType. In the 3.10 branch, there's a .. versionchanged note in the typing module docs that says:

Changed in version 3.10: NewType is now a class rather than a function. There is some additional runtime cost when calling NewType over a regular function. However, this cost will be reduced in 3.11.0.

In the 3.11 branch, there are two .. versionchanged notes that say:

Changed in version 3.10: NewType is now a class rather than a function. As a result, there is some additional runtime cost when calling NewType over a regular function.

Changed in version 3.11: The performance of calling NewType has been restored to its level in Python 3.9.

Could we do something similar here?

[gaogaotiantian]

We can surely mention that the behavior has changed in 3.13 in 3.12 docs. I was wondering if we should mention this in 3.13. This behavior was consistent until 3.12, and simply went back to what it used to be in 3.13. Will the extra doc confuse users if they never realize the change in 3.12? It's not difficult to add the docs to 3.13, just thinking about what's the best for the users.

[AlexWaygood]

Good point; maybe it's sufficient just to mention this in the 3.12 docs, as long as we say that it will change back in python 3.13

[gaogaotiantian]

Do you think it's better now? I used "is" instead of "will be" because we have 3.13 alpha release now and it should already be different. Not sure what's the best to phrase it.

[AlexWaygood]

Thanks!