gh-102676: Add more convenience properties to `dis.Instruction` (#103969)

Adds start_offset, cache_offset, end_offset, baseopcode,
baseopname, jump_target and oparg to dis.Instruction.

Also slightly improves the disassembly output by allowing
opnames to overflow into the space reserved for opargs.

1 files changed, 42 insertions, 0 deletions

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 9b90f1e..507b829 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -342,10 +342,25 @@ details of bytecode instructions as :class:`Instruction` instances:
       human readable name for operation
 
 
+   .. data:: baseopcode
+
+      numeric code for the base operation if operation is specialized;
+      otherwise equal to :data:`opcode`
+
+
+   .. data:: baseopname
+
+      human readable name for the base operation if operation is specialized;
+      otherwise equal to :data:`opname`
+
+
    .. data:: arg
 
       numeric argument to operation (if any), otherwise ``None``
 
+   .. data:: oparg
+
+      alias for :data:`arg`
 
    .. data:: argval
 
@@ -363,6 +378,22 @@ details of bytecode instructions as :class:`Instruction` instances:
       start index of operation within bytecode sequence
 
 
+   .. data:: start_offset
+
+      start index of operation within bytecode sequence, including prefixed
+      ``EXTENDED_ARG`` operations if present; otherwise equal to :data:`offset`
+
+
+   .. data:: cache_offset
+
+      start index of the cache entries following the operation
+
+
+   .. data:: end_offset
+
+      end index of the cache entries following the operation
+
+
    .. data:: starts_line
 
       line started by this opcode (if any), otherwise ``None``
@@ -373,6 +404,12 @@ details of bytecode instructions as :class:`Instruction` instances:
       ``True`` if other code jumps to here, otherwise ``False``
 
 
+   .. data:: jump_target
+
+      bytecode index of the jump target if this is a jump operation,
+      otherwise ``None``
+
+
    .. data:: positions
 
       :class:`dis.Positions` object holding the
@@ -384,6 +421,11 @@ details of bytecode instructions as :class:`Instruction` instances:
 
       Field ``positions`` is added.
 
+   .. versionchanged:: 3.13
+
+      Added fields ``start_offset``, ``cache_offset``, ``end_offset``,
+      ``baseopname``, ``baseopcode``, ``jump_target`` and ``oparg``.
+
 
 .. class:: Positions