Add enum, static/class method support, and pragma: no mutate: class/function

Features:
- Add enum class detection and external injection pattern for enum mutation
- Add staticmethod/classmethod support via external trampoline pattern
- Add parse_pragma_lines() for pragma: no mutate class/function
- Add build_enum_trampoline() template

Refactoring:
- Extract pragma_handling.py: parse_pragma_lines()
- Add utils/format_utils.py: make_mutant_key(), parse_mutant_key()
- Simplify orig_function_and_class_names_from_key() using parse_mutant_key()

Tests:
- Add test_enum_handling.py mirroring enum_handling module
- Add test_pragma_handling.py mirroring pragma_handling module

Config:
- Exclude AUTHORS.rst from merge conflict check in pre-commit

Author: nicklafleur

README.rst

@@ -53,8 +53,33 @@ it will try to figure out where the code to mutate is.
 
 
 You can stop the mutation run at any time and mutmut will restart where you
-left off. It will continue where it left off, and re-test functions that were
-modified since last run.
+left off.
+
+Incremental Testing
+~~~~~~~~~~~~~~~~~~~
+
+Mutmut is designed for incremental workflows. It remembers which mutants have
+been tested and their results, so subsequent runs skip already-tested mutants.
+
+**Function-level change detection:** Mutmut computes a hash of each function's
+source code. When you modify a function, mutmut detects the change and
+automatically re-tests all mutants in that function. Unchanged functions keep
+their previous results.
+
+**Limitation:** Change detection only tracks direct function changes, not
+transitive dependencies. If function A calls function B, and you modify B,
+mutants in A are not automatically re-tested. For significant changes to
+shared utilities, use ``mutmut run "module*"`` to re-test affected modules,
+or delete the ``mutants/`` directory for a full re-run.
+
+This means you can:
+
+- Run ``mutmut run``, stop partway through, and continue later
+- Modify your source code and re-run - only changed functions are re-tested
+- Update your tests and use ``mutmut browse`` to selectively re-test mutants
+
+The mutation data is stored in the ``mutants/`` directory. Delete this
+directory to start completely fresh.
 
 To work with the results, use `mutmut browse` where you can see the mutants,
 retest them when you've updated your tests.
@@ -226,6 +251,92 @@ whitelist lines are:
   to continue, but it's slower.
 
 
+Enum Classes and Metaclass Compatibility
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mutmut 3.x fully supports mutating enum classes. Methods inside enum classes
+(``Enum``, ``IntEnum``, ``Flag``, ``IntFlag``, ``StrEnum``) are automatically
+mutated using an external injection pattern that avoids conflicts with the
+enum metaclass.
+
+This means enums with methods like:
+
+.. code-block:: python
+
+    from enum import Enum
+
+    class Color(Enum):
+        RED = 1
+        GREEN = 2
+
+        def describe(self):
+            return self.name.lower()
+
+        @staticmethod
+        def count():
+            return 3
+
+...will have their methods mutated just like regular class methods.
+
+**Disabling Enum Mutation**
+
+If you prefer to skip enum mutation entirely, you can disable it in your config:
+
+.. code-block:: toml
+
+    # pyproject.toml
+    [tool.mutmut]
+    mutate_enums = false
+
+Or skip a specific enum class using the pragma:
+
+.. code-block:: python
+
+    class Color(Enum):  # pragma: no mutate class
+        RED = 1
+        GREEN = 2
+
+        def describe(self):
+            return f"Color is {self.name}"
+
+This tells mutmut to completely skip the class—no mutations will be created
+for any methods.
+
+Both syntax styles are supported:
+
+- ``# pragma: no mutate class``
+- ``# pragma: no mutate: class``
+
+**Note:** The regular ``# pragma: no mutate`` on a class line only prevents
+mutations on that specific line. It does NOT prevent mutations inside methods.
+Use ``# pragma: no mutate class`` to skip the entire class (kept for backward
+compatibility with <v3.5.0).
+
+
+Skipping Entire Functions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Similarly, you can skip an entire function from mutation using
+``# pragma: no mutate function``:
+
+.. code-block:: python
+
+    def complex_algorithm():  # pragma: no mutate function
+        # This function won't be mutated at all
+        return some_complex_calculation()
+
+Both syntax styles are supported:
+
+- ``# pragma: no mutate function``
+- ``# pragma: no mutate: function``
+
+This is useful for functions that:
+
+- Have complex side effects that make mutation testing impractical
+- Are performance-critical and you want to avoid trampoline overhead
+- Are known to cause issues with the mutation testing framework
+
+
 Modifying pytest arguments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

e2e_projects/my_lib/src/my_lib/__init__.py

@@ -1,10 +1,15 @@
 from collections.abc import Callable
+from enum import Enum
 from functools import cache
 from typing import Union
 import ctypes
 import asyncio
 
 
+def my_decorator(func):  # pragma: no mutate: function
+    return func
+
+
 def hello() -> str:
     return "Hello from my-lib!"
 
@@ -14,6 +19,13 @@ def badly_tested() -> str:
 def untested() -> str:
     return "Mutants for this method should survive"
 
+def skip_this_function() -> int:  # pragma: no mutate: function
+    return 1 + 2 * 3
+
+def also_skip_this_function() -> str:  # pragma: no mutate function
+    return "should" + " not" + " mutate"
+
+
 def make_greeter(name: Union[str, None]) -> Callable[[], str]:
     def hi():
         if name:
@@ -88,6 +100,30 @@ def from_coords(coords) -> 'Point':
     def coords(self):
         return self.x, self.y
 
+    @staticmethod
+    def skip_static_decorator_pragma(a: int, b: int) -> int:  # pragma: no mutate: function
+        return a + b * 2
+
+    @classmethod
+    def skip_class_decorator_pragma(cls, value: int) -> "Point":  # pragma: no mutate: function
+        return cls(value + 1, value * 2)
+
+    def skip_instance_method_pragma(self) -> int:  # pragma: no mutate: function
+        return self.x + self.y * 2
+
+    @staticmethod  # pragma: no mutate: function
+    def pragma_on_staticmethod_decorator(a: int, b: int) -> int:
+        return a + b * 2
+
+    @classmethod  # pragma: no mutate: function
+    def pragma_on_classmethod_decorator(cls, value: int) -> "Point":
+        return cls(value + 1, value * 2)
+
+    @my_decorator
+    @classmethod
+    def skip_multi_decorator(cls, value: int) -> "Point":
+        return cls(value + 1, value * 2)
+
 
 def escape_sequences():
     return "foo" \
@@ -111,3 +147,42 @@ def func_with_star(a, /, b, *, c, **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)
+
+
+class Color(Enum):
+    RED = 1
+    GREEN = 2
+    BLUE = 3
+
+    def is_primary(self) -> bool:
+        return self in (Color.RED, Color.GREEN, Color.BLUE)
+
+    def darken(self) -> int:
+        return self.value - 1
+
+    @staticmethod
+    def from_name(name: str) -> "Color":
+        return Color[name.upper()]
+
+    @classmethod
+    def default(cls) -> "Color":
+        return cls.RED
+
+
+class SkipThisClass:  # pragma: no mutate: class
+    def method_one(self) -> int:
+        return 1 + 2
+
+    def method_two(self) -> str:
+        return "hello" + " world"
+
+    @staticmethod
+    def static_method() -> int:
+        return 3 * 4
+
+
+class AlsoSkipThisClass:  # pragma: no mutate class
+    VALUE = 10 + 20
+
+    def compute(self) -> int:
+        return self.VALUE * 2

e2e_projects/my_lib/tests/test_my_lib.py

@@ -31,6 +31,28 @@ def test_point():
 def test_point_from_coords():
     assert Point.from_coords((1, 2)).x == 1
 
+
+def test_point_skip_static_decorator_pragma():
+    assert Point.skip_static_decorator_pragma(3, 4) == 11
+
+
+def test_point_skip_class_decorator_pragma():
+    p = Point.skip_class_decorator_pragma(5)
+    assert p.x == 6
+    assert p.y == 10
+
+
+def test_point_skip_instance_method_pragma():
+    p = Point(3, 4)
+    assert p.skip_instance_method_pragma() == 11
+
+
+def test_point_skip_multi_decorator():
+    p = Point.skip_multi_decorator(5)
+    assert p.x == 6
+    assert p.y == 10
+
+
 def test_fibonacci():
     assert fibonacci(1) == 1
     assert cached_fibonacci(1) == 1
@@ -66,3 +88,60 @@ def test_signature_functions_are_callable():
 
 def test_signature_is_coroutine():
     assert asyncio.iscoroutinefunction(async_consumer)
+
+
+# Tests for enum mutation
+def test_color_enum_values():
+    assert Color.RED.value == 1
+    assert Color.GREEN.value == 2
+    assert Color.BLUE.value == 3
+
+
+def test_color_is_primary():
+    assert Color.RED.is_primary() is True
+    assert Color.GREEN.is_primary() is True
+
+
+def test_color_darken():
+    assert Color.GREEN.darken() == 1
+    assert Color.BLUE.darken() == 2
+
+
+def test_color_from_name():
+    assert Color.from_name("red") == Color.RED
+    assert Color.from_name("BLUE") == Color.BLUE
+
+
+def test_color_default():
+    assert Color.default() == Color.RED
+
+
+def test_skip_this_function():
+    assert skip_this_function() == 7
+
+
+def test_also_skip_this_function():
+    assert also_skip_this_function() == "should not mutate"
+
+
+def test_skip_this_class():
+    obj = SkipThisClass()
+    assert obj.method_one() == 3
+    assert obj.method_two() == "hello world"
+    assert SkipThisClass.static_method() == 12
+
+
+def test_also_skip_this_class():
+    obj = AlsoSkipThisClass()
+    assert obj.VALUE == 30
+    assert obj.compute() == 60
+
+
+def test_pragma_on_staticmethod_decorator():
+    assert Point.pragma_on_staticmethod_decorator(3, 4) == 11
+
+
+def test_pragma_on_classmethod_decorator():
+    p = Point.pragma_on_classmethod_decorator(5)
+    assert p.x == 6
+    assert p.y == 10

src/mutmut/mutation/trampoline_templates.py

@@ -75,8 +75,7 @@ def {orig_name}({self_prefix}*args, **kwargs):
 
 {body}
 
-{orig_name}.__signature__ = _mutmut_signature({mangled_name}__mutmut_orig)
-{orig_name}.__annotations__ = {mangled_name}__mutmut_orig.__annotations__
+{orig_name} = _mutmut_wraps({mangled_name}__mutmut_orig)({orig_name})
 {mangled_name}__mutmut_orig.__name__ = '{mangled_name}'
 """)
 
@@ -132,7 +131,7 @@ def {prefix}_trampoline(self, *args, **kwargs):
 # noinspection PyUnresolvedReferences
 # language=python
 trampoline_impl = _mark_generated("""
-from inspect import signature as _mutmut_signature
+from functools import wraps as _mutmut_wraps
 from typing import Annotated
 from typing import Callable
 from typing import ClassVar

tests/e2e/test_e2e_my_lib.py

@@ -70,6 +70,17 @@ def test_my_lib_result_snapshot():
                 "my_lib.xǁPointǁfrom_coords__mutmut_4": 1,
                 "my_lib.xǁPointǁfrom_coords__mutmut_5": 1,
                 "my_lib.xǁPointǁfrom_coords__mutmut_6": 1,
+                "my_lib.xǁPointǁpragma_on_staticmethod_decorator__mutmut_1": 1,
+                "my_lib.xǁPointǁpragma_on_staticmethod_decorator__mutmut_2": 1,
+                "my_lib.xǁPointǁpragma_on_staticmethod_decorator__mutmut_3": 1,
+                "my_lib.xǁPointǁpragma_on_classmethod_decorator__mutmut_1": 1,
+                "my_lib.xǁPointǁpragma_on_classmethod_decorator__mutmut_2": 1,
+                "my_lib.xǁPointǁpragma_on_classmethod_decorator__mutmut_3": 1,
+                "my_lib.xǁPointǁpragma_on_classmethod_decorator__mutmut_4": 1,
+                "my_lib.xǁPointǁpragma_on_classmethod_decorator__mutmut_5": 1,
+                "my_lib.xǁPointǁpragma_on_classmethod_decorator__mutmut_6": 1,
+                "my_lib.xǁPointǁpragma_on_classmethod_decorator__mutmut_7": 1,
+                "my_lib.xǁPointǁpragma_on_classmethod_decorator__mutmut_8": 1,
                 "my_lib.x_escape_sequences__mutmut_1": 1,
                 "my_lib.x_escape_sequences__mutmut_2": 0,
                 "my_lib.x_escape_sequences__mutmut_3": 1,
@@ -85,6 +96,10 @@ def test_my_lib_result_snapshot():
                 "my_lib.x_func_with_star__mutmut_2": 1,
                 "my_lib.x_func_with_star__mutmut_3": 1,
                 "my_lib.x_func_with_arbitrary_args__mutmut_1": 1,
+                "my_lib.xǁColorǁis_primary__mutmut_1": 1,
+                "my_lib.xǁColorǁdarken__mutmut_1": 1,
+                "my_lib.xǁColorǁdarken__mutmut_2": 1,
+                "my_lib.xǁColorǁfrom_name__mutmut_1": 1,
             }
         }
     )

tests/e2e/test_e2e_type_checking.py

@@ -15,9 +15,9 @@ def test_type_checking_result_snapshot():
                 "type_checking.x_a_hello_wrapper__mutmut_2": 0,
                 "type_checking.xǁPersonǁset_name__mutmut_1": 37,
                 "type_checking.x_mutate_me__mutmut_1": 37,
-                "type_checking.x_mutate_me__mutmut_2": 1,
-                "type_checking.x_mutate_me__mutmut_3": 1,
-                "type_checking.x_mutate_me__mutmut_4": 1,
+                "type_checking.x_mutate_me__mutmut_2": 37,
+                "type_checking.x_mutate_me__mutmut_3": 37,
+                "type_checking.x_mutate_me__mutmut_4": 37,
                 "type_checking.x_mutate_me__mutmut_5": 37,
             }
         }