support signatures with PEP 649 deferred annotations

Author: Otto-AA

e2e_projects/my_lib/src/my_lib/__init__.py

@@ -97,3 +97,17 @@ def create_a_segfault_when_mutated():
     # when we mutate False->True, then this will segfault
     if False:
         ctypes.string_at(0)
+
+def some_func_clone(a, b: str = "111", c: Callable[[str], int] | None = None) -> int | None: pass  # pragma: no mutate
+def some_func(a, b: str = "111", c: Callable[[str], int] | None = None) -> int | None:
+    if a and c:
+        return c(b)
+    return None
+
+def func_with_star_clone(a, *, b, **kwargs): pass  # pragma: no mutate
+def func_with_star(a, *, b, **kwargs):
+    return a + b + len(kwargs)
+
+def func_with_arbitrary_args_clone(*args, **kwargs): pass  # pragma: no mutate
+def func_with_arbitrary_args(*args, **kwargs):
+    return len(args) + len(kwargs)

e2e_projects/my_lib/tests/test_my_lib.py

@@ -1,4 +1,5 @@
-from my_lib import hello, Point, badly_tested, make_greeter, fibonacci, cached_fibonacci, escape_sequences, simple_consumer, async_consumer, create_a_segfault_when_mutated
+import inspect
+from my_lib import *
 import pytest
 
 """These tests are flawed on purpose, some mutants survive and some are killed."""
@@ -47,3 +48,17 @@ async def test_async_consumer():
 
 def test_handles_segfaults():
     create_a_segfault_when_mutated()
+
+def test_that_signatures_are_preserved():
+    assert inspect.signature(some_func) == inspect.signature(some_func_clone)
+    assert inspect.signature(func_with_star) == inspect.signature(func_with_star_clone)
+    assert inspect.signature(func_with_arbitrary_args) == inspect.signature(func_with_arbitrary_args_clone)
+
+    assert inspect.get_annotations(some_func) == inspect.get_annotations(some_func_clone)
+    assert inspect.get_annotations(func_with_star) == inspect.get_annotations(func_with_star_clone)
+    assert inspect.get_annotations(func_with_arbitrary_args) == inspect.get_annotations(func_with_arbitrary_args_clone)
+
+def test_signature_functions_are_callable():
+    assert some_func(True, c=lambda s: int(s), b="222") == 222
+    assert func_with_star(1, b=2, x='x', y='y', z='z') == 6
+    assert func_with_arbitrary_args('a', 'b', foo=123, bar=456) == 4

e2e_projects/py3_14_features/README.md

@@ -0,0 +1 @@
+This project will be E2E tested. It mainly serves as a "canary" that alerts you when code changes affect which mutants survive.

e2e_projects/py3_14_features/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "py3-14-features"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = []
+requires-python = ">=3.14"
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+]
+
+[tool.mutmut]
+debug = true
+
+[tool.pytest.ini_options]
+asyncio_default_fixture_loop_scope = "function"

e2e_projects/py3_14_features/src/py3_14_features/__init__.py

@@ -0,0 +1,23 @@
+from typing import TYPE_CHECKING
+from dataclasses import dataclass
+
+if TYPE_CHECKING:
+    from collections.abc import Collection
+
+# verify that mutmut can handle type-check-only annotations
+def get_len(data: Collection):
+    # (the + 0 is just so we get a surviving and a killed mutant; not relevant for this test case)
+    return len(data) + 0
+
+def get_len_clone(data: Collection): pass  # pragma: no mutate
+
+
+# verify that mutmut can handle annotations that area 
+def get_foo_len(data: Foo) -> int:
+    return len(data.foo) + 0
+
+def get_foo_len_clone(data: Foo) -> int: pass  # pragma: no mutate
+
+@dataclass
+class Foo:
+    foo: list[str]

e2e_projects/py3_14_features/tests/test_py3_14_features.py

@@ -0,0 +1,21 @@
+import annotationlib
+import inspect
+from py3_14_features import get_len, get_foo_len_clone, get_foo_len, get_len_clone, Foo
+
+def test_func_with_type_only_annotation():
+    assert get_len([1, 2, 3]) == 3
+
+def test_lazy_loaded_signature():
+    assert get_foo_len(Foo(["abc", "def"])) == 2
+
+def test_annotations():
+    # the get_len trampoline should have the correct annotations
+    assert annotationlib.get_annotations(get_len, format=annotationlib.Format.STRING) == {'data': 'Collection'}
+
+    # 'Foo' should be available at this point, so we do not need the STRING format
+    assert annotationlib.get_annotations(get_foo_len) == annotationlib.get_annotations(get_foo_len_clone)
+
+def test_signature():
+    # mutmut currently only achieves a stringified version, because we cannot eagerly evalute the signature
+    assert inspect.signature(get_len, annotation_format=inspect.Format.STRING) == inspect.signature(get_len_clone, annotation_format=inspect.Format.STRING)
+

e2e_projects/py3_14_features/uv.lock

@@ -21,7 +21,7 @@ def {orig_name}({'self, ' if class_name is not None else ''}*args, **kwargs):
     result = {trampoline_name}({access_prefix}{mangled_name}__mutmut_orig{access_suffix}, {access_prefix}{mangled_name}__mutmut_mutants{access_suffix}, args, kwargs{self_arg})
     return result 
 
-{orig_name}.__signature__ = _mutmut_signature({mangled_name}__mutmut_orig)
+_mutmut_copy_signature({orig_name}, {mangled_name}__mutmut_orig)
 {mangled_name}__mutmut_orig.__name__ = '{mangled_name}'
 """
 
@@ -37,11 +37,30 @@ def mangle_function_name(*, name, class_name):
 # noinspection PyUnresolvedReferences
 # language=python
 trampoline_impl = """
-from inspect import signature as _mutmut_signature
+import inspect as _mutmut_inspect
+import sys as _mutmut_sys
 from typing import Annotated
 from typing import Callable
 from typing import ClassVar
 
+def _mutmut_copy_signature(trampoline, original_method):
+    if _mutmut_sys.version_info >= (3, 14):
+        # PEP 649 introduced deferred loading for annotations
+        # When some_method.__annotations__ is accessed, Python uses some_method.__annotate__(format) to compute it
+        # By copying the original __annotate__ method, we provide get the original annotations
+        trampoline.__annotate__ = original_method.__annotate__
+    else:
+        # On Python 3.13 and earlier, __annotations__ can be accessed immediately
+        trampoline.__annotations__ = original_method.__annotations__
+
+    try:
+        trampoline.__signature__ = _mutmut_inspect.signature(original_method)
+    except NameError:
+        # Also, because of PEP 649, it can happen that we cannot eagerly evaluate the signature
+        # In this case, fall back to stringifying the signature (which could cause different behaviour with runtime introspection)
+        trampoline.__signature__ = _mutmut_inspect.signature(original_method, annotation_format=_mutmut_inspect.Format.STRING)
+
+
 
 MutantDict = Annotated[dict[str, Callable], "Mutant"]
 

src/mutmut/trampoline_templates.py

@@ -64,6 +64,12 @@
     "my_lib.x_escape_sequences__mutmut_5": 0,
     "my_lib.x_create_a_segfault_when_mutated__mutmut_1": -11,
     "my_lib.x_create_a_segfault_when_mutated__mutmut_2": 0,
-    "my_lib.x_create_a_segfault_when_mutated__mutmut_3": 0
+    "my_lib.x_create_a_segfault_when_mutated__mutmut_3": 0,
+    "my_lib.x_some_func__mutmut_1": 0,
+    "my_lib.x_some_func__mutmut_2": 0,
+    "my_lib.x_some_func__mutmut_3": 1,
+    "my_lib.x_func_with_star__mutmut_1": 1,
+    "my_lib.x_func_with_star__mutmut_2": 1,
+    "my_lib.x_func_with_arbitrary_args__mutmut_1": 1
   }
 }

tests/e2e/snapshots/my_lib.json

@@ -0,0 +1,8 @@
+{
+  "mutants/src/py3_14_features/__init__.py.meta": {
+    "py3_14_features.x_get_len__mutmut_1": 0,
+    "py3_14_features.x_get_len__mutmut_2": 1,
+    "py3_14_features.x_get_foo_len__mutmut_1": 0,
+    "py3_14_features.x_get_foo_len__mutmut_2": 1
+  }
+}