feat: add support for CPython 3.15

Author: P403n1x87

.github/workflows/cis.yml

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

src/bytecode/instr.py

@@ -16,7 +16,7 @@
     from typing_extensions import TypeGuard  # type: ignore
 
 import bytecode as _bytecode
-from bytecode.utils import PY312, PY313, PY314
+from bytecode.utils import PY312, PY313, PY314, PY315
 
 # --- Instruction argument tools and
 
@@ -53,6 +53,11 @@
 # Small integer related opcode
 SMALL_INT_OPS: Final[set[int]] = {_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: Final[set[int]] = (
+    {_opcode.opmap["GET_ITER"]} if PY315 else set()
+)
+
 # Special method loading related opcodes
 SPECIAL_OPS: Final[set[int]] = {_opcode.opmap["LOAD_SPECIAL"]} if PY314 else set()
 
@@ -419,8 +424,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),
+        "GET_YIELD_FROM_ITER": (-1, 1),  # removed in 3.15, filtered by if k in _opcode.opmap
         "GET_AWAITABLE": (-1, 1),
         "GET_AITER": (-1, 1),
         "GET_ANEXT": (-1, 2),
@@ -503,7 +508,14 @@ 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); 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.
+        "FOR_ITER": (
+            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
@@ -875,6 +887,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

@@ -4,3 +4,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

@@ -19,7 +19,7 @@
     SetLineno,
     dump_bytecode,
 )
-from bytecode.utils import PY312, PY313, PY314
+from bytecode.utils import PY312, PY313, PY314, PY315
 
 from . import TestCase, disassemble as _disassemble
 

tests/test_concrete.py

@@ -21,7 +21,7 @@
     SetLineno,
 )
 from bytecode.concrete import ExceptionTableEntry
-from bytecode.utils import PY312, PY313, PY314
+from bytecode.utils import PY312, PY313, PY314, PY315
 
 from . import TestCase, get_code
 
@@ -250,24 +250,37 @@ def test_attr(self):
         self.assertEqual(code.freevars, [])
         self.assertInstructionListEqual(
             list(code),
-            ([ConcreteInstr("RESUME", 0, lineno=0)])
-            + [
-                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)]
+                    + [
+                        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),
+                            ]
+                        )
+                    )
                 )
             ),
         )
@@ -739,6 +752,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

@@ -7,7 +7,7 @@
 
 import bytecode
 from bytecode import BasicBlock, Bytecode, ControlFlowGraph, Instr, Label
-from bytecode.utils import PY312, PY313, PY314
+from bytecode.utils import PY312, PY313, PY314, PY315
 
 from . import disassemble
 
@@ -422,7 +422,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
@@ -511,7 +537,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]