Repository: python/cpython
Pull request: gh-114616: Improve docs regarding changes to caches representation in dis
Fix #114616 .

<!-- gh-issue-number: gh-114616 -->
* Issue: gh-114616
<!-- /gh-issue-number -->


<!-- readthedocs-preview cpython-previews start -->
----
📚 Documentation preview 📚: https://cpython-previews--120033.org.readthedocs.build/

<!-- readthedocs-preview cpython-previews end -->

Problem statement:
3.13 dis: the show_caches argument is deprecated but the documentation is incomplete
# 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?


<!-- gh-linked-prs -->
### Linked PRs
* gh-120033
* gh-120079
<!-- /gh-linked-prs -->

Hints from issue discussion:
> 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).
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. 
> 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()`.

> 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.

Commit message: gh-114616: Improve docs regarding changes to caches representation in dis

Patch to review:
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index fda46d260bcb46..ea8e8fb8287844 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -336,9 +336,10 @@ operation is being performed, so the intermediate analysis object isn't useful:
       Added the *show_caches* and *adaptive* parameters.
 
    .. versionchanged:: 3.13
-      The *show_caches* parameter is deprecated and has no effect. The *cache_info*
-      field of each instruction is populated regardless of its value.
-
+      The *show_caches* parameter is deprecated and has no effect. The iterator
+      generates the :class:`Instruction` instances with the *cache_info*
+      field populated (regardless of the value of *show_caches*) and it does not
+      generate separate items for the cache entries as it did before.
 
 .. function:: findlinestarts(code)
 
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index 903de3c04b4a07..35497a03800f90 100644
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -706,6 +706,13 @@ dis
   the ``show_offsets`` parameter.
   (Contributed by Irit Katriel in :gh:`112137`.)
 
+* :meth:`~dis.get_instructions` no longer represents cache entries as
+  separate instructions. Instead, it returns them as part of the
+  :class:`~dis.Instruction`, in the new *cache_info* field. The
+  *show_caches* argument to :meth:`~dis.get_instructions` is
+  deprecated and no longer has any effect.
+  (Contributed by Irit Katriel in :gh:`112962`.)
+
 .. _whatsnew313-doctest:
 
 doctest


Code review comments:
diff_hunk: @@ -336,9 +336,10 @@ operation is being performed, so the intermediate analysis object isn't useful:
       Added the *show_caches* and *adaptive* parameters.
 
    .. versionchanged:: 3.13
-      The *show_caches* parameter is deprecated and has no effect. The *cache_info*
-      field of each instruction is populated regardless of its value.
-
+      The *show_caches* parameter is deprecated and has no effect. The iterator
+      generates the :class:`Instruction` instances with the *cache_info*
+      field populated (regardless of the value of *show_caches*) and it does not
+      generate separate items for the cache entries as it did before.
path: Doc/library/dis.rst
text: @author:
```suggestion
      field populated (regardless of the value of *show_caches*) and it no longer
      generates separate items for the cache entries.
```