3.13 dis: the show_caches argument is deprecated but the documentation is incomplete

[15r10nk]

Documentation

show_caches was deprecated in 3.13 for dis.get_instructions.

The documentation misses the following things:

get_instructions:

The documentation says:

The show_caches parameter is deprecated and has no effect. The cache_info field of each instruction is populated regardless of its value.

problems:

• What does 'no effect' mean?
• The cache_info field is also not well documented.

My first assumption was that "The cache_info field of each instruction" would mean that each instruction (including Cache instructions) would be part of the returned list, but this is not the case.

Bytecode:

Bytecode() has also a show_caches parameter which has no effect any more but the deprecation is not documented.

Questions

Is it still possible to get access to the Cache bytecodes? They are only visible with dis.dis(...,show_caches=True) but I found no way to access the Cache bytecode objects.

should this deprecation be part of the whatsnew page for 3.13?

Linked PRs

• gh-114616: Improve docs regarding changes to caches representation in dis #120033
• [3.13] gh-114616: Improve docs regarding changes to caches representation in dis (GH-120033) #120079

[iritkatriel]

What does 'no effect' mean?

It means that the same thing happens, no matter what value you pass in for this arg.

Is it still possible to get access to the Cache bytecodes?

No, representing the cache entries as if they are bytecodes doesn't really make sense, and should not have been done. The caches are a part of the instruction, and now they are represented by a field on the Instruction instance.

I'll look into the doc improvements you suggest (unless you beat me to it).

[15r10nk]

Thank you for the answer.
I'm ok with the new behavior.

I found also another related doc issue

Changed in version 3.6: Use 2 bytes for each instruction. Previously the number of bytes varied by instruction.

The doc says nothing different currently for 3.13. and this might break user code which relied on the behavior like:

bytecode_list=get_instructions(...)
bytecode_list[offset//2]

And yes, I can also try to fix the docs if you want. But I don't know which name should be added in the what's new section.

[iritkatriel]

Bytecode() has also a show_caches parameter which has no effect any more but the deprecation is not documented.

It is not deprecated in the Bytecode constructor - it is needed there because it's used in Bytecode.dis().

[iritkatriel]

I found also another related doc issue

Changed in version 3.6: Use 2 bytes for each instruction. Previously the number of bytes varied by instruction.

The doc says nothing different currently for 3.13. and this might break user code which relied on the behavior like:

bytecode_list=get_instructions(...)
bytecode_list[offset//2]

The change wasn't in 3.13, it was in 3.11 when the caches were added. The caches are mentioned in the doc under 3.11.

[15r10nk]

thank you.