feat: add support for CPython 3.15

Author: P403n1x87

.github/workflows/cis.yml

@@ -52,8 +52,10 @@ jobs:
             toxenv: py312
           - python-version: "3.13"
             toxenv: py313
-          - python-version: "3.14-dev"
+          - python-version: "3.14"
             toxenv: py314
+          - python-version: "3.15-dev"
+            toxenv: py315
     steps:
       - uses: actions/checkout@v5
       - name: Get history and tags for SCM versioning to work

src/bytecode/instr.py

@@ -14,7 +14,7 @@
     from typing_extensions import TypeGuard  # type: ignore
 
 import bytecode as _bytecode
-from bytecode.utils import PY311, PY312, PY313, PY314
+from bytecode.utils import PY311, PY312, PY313, PY314, PY315
 
 # --- Instruction argument tools and
 
@@ -49,6 +49,11 @@
 # Small integer related opcode
 SMALL_INT_OPS = {_opcode.opmap["LOAD_SMALL_INT"]} if PY314 else set()
 
+# Opcodes that gained a cache-only argument in 3.15 (arg is always 0 and not user-visible)
+CACHE_ONLY_ARG_OPCODES: Set[int] = (
+    {_opcode.opmap["GET_ITER"]} if PY315 else set()
+)
+
 # Special method loading related opcodes
 SPECIAL_OPS = {_opcode.opmap["LOAD_SPECIAL"]} if PY314 else set()
 
@@ -371,8 +376,8 @@ def opcode_has_argument(opcode: int) -> bool:
     "DUP_TOP": (-1, 2),
     "DUP_TOP_TWO": (-2, 4),
     "GET_LEN": (-1, 2),
-    "GET_ITER": (-1, 1),
-    "GET_YIELD_FROM_ITER": (-1, 1),
+    "GET_ITER": (-1, 2) if PY315 else (-1, 1),
+    **({} if PY315 else {"GET_YIELD_FROM_ITER": (-1, 1)}),
     "GET_AWAITABLE": (-1, 1),
     "GET_AITER": (-1, 1),
     "GET_ANEXT": (-1, 2),
@@ -451,7 +456,16 @@ def opcode_has_argument(opcode: int) -> bool:
     "MAP_ADD": lambda effect, arg, jump: (-arg, arg - 2),
     "FORMAT_VALUE": lambda effect, arg, jump: (effect - 1, 1),
     # FOR_ITER needs TOS to be an iterator, hence a prerequisite of 1 on the stack
-    "FOR_ITER": lambda effect, arg, jump: (effect, 0) if jump else (-1, 2),
+    # In 3.15, GET_ITER pushes (iter, null_or_index) so FOR_ITER keeps those and
+    # pushes/keeps the value; when exhausted it jumps to POP_ITER leaving stack unchanged.
+    "FOR_ITER": (
+        # In 3.15, GET_ITER pushes (iter, null_or_index); FOR_ITER always pushes the
+        # next value (+1). When exhausted it jumps to END_FOR (which pops it) then
+        # POP_ITER cleans up (iter, null_or_index). Matches dis.stack_effect = 1 always.
+        lambda __effect, __arg, __jump: (0, 1)
+    ) if PY315 else (
+        lambda effect, __arg, jump: (effect, 0) if jump else (-1, 2)
+    ),
     "BUILD_INTERPOLATION": lambda effect, arg, jump: (-(2 + (arg & 1)), 1),
     **{
         # Instr(UNPACK_* , n) pops 1 and pushes n
@@ -842,6 +856,9 @@ def _set(self, name: str, arg: A) -> None:
                 "Only base opcodes are supported"
             )
 
+        if arg is UNSET and opcode in CACHE_ONLY_ARG_OPCODES:
+            arg = 0  # type: ignore
+
         self._check_arg(name, opcode, arg)
 
         self._name = name

src/bytecode/utils.py

@@ -6,3 +6,4 @@
 PY312: Final[bool] = sys.version_info >= (3, 12)
 PY313: Final[bool] = sys.version_info >= (3, 13)
 PY314: Final[bool] = sys.version_info >= (3, 14)
+PY315: Final[bool] = sys.version_info >= (3, 15)

tests/test_cfg.py

@@ -20,7 +20,7 @@
     dump_bytecode,
 )
 from bytecode.concrete import OFFSET_AS_INSTRUCTION
-from bytecode.utils import PY311, PY312, PY313, PY314
+from bytecode.utils import PY311, PY312, PY313, PY314, PY315
 
 from . import TestCase, disassemble as _disassemble
 

tests/test_concrete.py

@@ -21,7 +21,7 @@
     SetLineno,
 )
 from bytecode.concrete import OFFSET_AS_INSTRUCTION, ExceptionTableEntry
-from bytecode.utils import PY310, PY311, PY312, PY313, PY314
+from bytecode.utils import PY310, PY311, PY312, PY313, PY314, PY315
 
 from . import TestCase, get_code
 
@@ -256,24 +256,37 @@ def test_attr(self):
         self.assertEqual(code.freevars, [])
         self.assertInstructionListEqual(
             list(code),
-            ([ConcreteInstr("RESUME", 0, lineno=0)] if PY311 else [])
-            + [
-                ConcreteInstr("LOAD_CONST", 0, lineno=1),
-                ConcreteInstr("STORE_NAME", 0, lineno=1),
-            ]
-            + (
+            (
                 [
-                    ConcreteInstr("LOAD_SMALL_INT", 1, lineno=1),
+                    ConcreteInstr("RESUME", 0, lineno=0),
+                    ConcreteInstr("CACHE", 0, lineno=0),
+                    ConcreteInstr("LOAD_SMALL_INT", 5, lineno=1),
+                    ConcreteInstr("STORE_NAME", 0, lineno=1),
+                    ConcreteInstr("LOAD_CONST", 1, lineno=1),
                     ConcreteInstr("RETURN_VALUE", lineno=1),
                 ]
-                if PY314
+                if PY315
                 else (
-                    [ConcreteInstr("RETURN_CONST", 1, lineno=1)]
-                    if PY312
-                    else [
-                        ConcreteInstr("LOAD_CONST", 1, lineno=1),
-                        ConcreteInstr("RETURN_VALUE", lineno=1),
+                    ([ConcreteInstr("RESUME", 0, lineno=0)] if PY311 else [])
+                    + [
+                        ConcreteInstr("LOAD_CONST", 0, lineno=1),
+                        ConcreteInstr("STORE_NAME", 0, lineno=1),
                     ]
+                    + (
+                        [
+                            ConcreteInstr("LOAD_SMALL_INT", 1, lineno=1),
+                            ConcreteInstr("RETURN_VALUE", lineno=1),
+                        ]
+                        if PY314
+                        else (
+                            [ConcreteInstr("RETURN_CONST", 1, lineno=1)]
+                            if PY312
+                            else [
+                                ConcreteInstr("LOAD_CONST", 1, lineno=1),
+                                ConcreteInstr("RETURN_VALUE", lineno=1),
+                            ]
+                        )
+                    )
                 )
             ),
         )
@@ -824,6 +837,31 @@ def foo(x: int, y: int):
 
         # without EXTENDED_ARG
         concrete = ConcreteBytecode.from_code(code_obj)
+        if PY315:
+            ann_code = concrete.consts[0]
+            func_code = concrete.consts[1]
+            expected_py315 = [
+                ConcreteInstr("RESUME", 0, lineno=0),
+                ConcreteInstr("CACHE", 0, lineno=0),
+                ConcreteInstr("LOAD_CONST", 0, lineno=1),
+                ConcreteInstr("MAKE_FUNCTION", lineno=1),
+                ConcreteInstr("LOAD_CONST", 1, lineno=1),
+                ConcreteInstr("MAKE_FUNCTION", lineno=1),
+                ConcreteInstr("SET_FUNCTION_ATTRIBUTE", 16, lineno=1),
+                ConcreteInstr("STORE_NAME", 0, lineno=1),
+                ConcreteInstr("LOAD_CONST", 2, lineno=1),
+                ConcreteInstr("RETURN_VALUE", lineno=1),
+            ]
+            self.assertSequenceEqual(concrete.names, ["foo"])
+            self.assertSequenceEqual(concrete.consts, [ann_code, func_code, None])
+            self.assertInstructionListEqual(list(concrete), expected_py315)
+            concrete = ConcreteBytecode.from_code(code_obj, extended_arg=True)
+            ann_code = concrete.consts[0]
+            func_code = concrete.consts[1]
+            self.assertEqual(concrete.names, ["foo"])
+            self.assertEqual(concrete.consts, [ann_code, func_code, None])
+            self.assertInstructionListEqual(list(concrete), expected_py315)
+            return
         if PY314:
             ann_code = concrete.consts[0]
             func_code = concrete.consts[1]

tests/test_misc.py

@@ -8,7 +8,7 @@
 import bytecode
 from bytecode import BasicBlock, Bytecode, ControlFlowGraph, Instr, Label
 from bytecode.concrete import OFFSET_AS_INSTRUCTION
-from bytecode.utils import PY311, PY312, PY313, PY314
+from bytecode.utils import PY311, PY312, PY313, PY314, PY315
 
 from . import disassemble
 
@@ -529,7 +529,33 @@ def func(test):
         code = code.to_concrete_bytecode()
 
         # without line numbers
-        if PY314:
+        if PY315:
+            # RESUME gained a CACHE entry in 3.15, shifting all offsets by 2
+            expected = """
+  0    RESUME 0
+  2    CACHE 0
+  4    LOAD_FAST_BORROW 0
+  6    LOAD_SMALL_INT 1
+  8    COMPARE_OP 88
+ 10    CACHE 0
+ 12    POP_JUMP_IF_FALSE 3
+ 14    CACHE 0
+ 16    NOT_TAKEN
+ 18    LOAD_SMALL_INT 1
+ 20    RETURN_VALUE
+ 22    LOAD_FAST_BORROW 0
+ 24    LOAD_SMALL_INT 2
+ 26    COMPARE_OP 88
+ 28    CACHE 0
+ 30    POP_JUMP_IF_FALSE 3
+ 32    CACHE 0
+ 34    NOT_TAKEN
+ 36    LOAD_SMALL_INT 2
+ 38    RETURN_VALUE
+ 40    LOAD_SMALL_INT 3
+ 42    RETURN_VALUE
+"""
+        elif PY314:
             # COMPARE_OP use the 4 lowest bits as a cache
             expected = """
   0    RESUME 0
@@ -635,7 +661,32 @@ def func(test):
         self.check_dump_bytecode(code, expected.lstrip("\n"))
 
         # with line numbers
-        if PY314:
+        if PY315:
+            expected = """
+L.  1   0: RESUME 0
+        2: CACHE 0
+L.  2   4: LOAD_FAST_BORROW 0
+        6: LOAD_SMALL_INT 1
+        8: COMPARE_OP 88
+       10: CACHE 0
+       12: POP_JUMP_IF_FALSE 3
+       14: CACHE 0
+       16: NOT_TAKEN
+L.  3  18: LOAD_SMALL_INT 1
+       20: RETURN_VALUE
+L.  4  22: LOAD_FAST_BORROW 0
+       24: LOAD_SMALL_INT 2
+       26: COMPARE_OP 88
+       28: CACHE 0
+       30: POP_JUMP_IF_FALSE 3
+       32: CACHE 0
+       34: NOT_TAKEN
+L.  5  36: LOAD_SMALL_INT 2
+       38: RETURN_VALUE
+L.  6  40: LOAD_SMALL_INT 3
+       42: RETURN_VALUE
+"""
+        elif PY314:
             expected = """
 L.  1   0: RESUME 0
 L.  2   2: LOAD_FAST_BORROW 0

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = py3, py38, py39, py310, py311, py312, py313, py314, fmt, docs
+envlist = py3, py38, py39, py310, py311, py312, py313, py314, py315, fmt, docs
 isolated_build = true
 
 [testenv]