Add pragma: no mutate block and document no mutate class

Support ignoring entire indentation blocks via `# pragma: no mutate block`.
When placed on its own line, all lines at the same or deeper indent are
skipped. When placed inline, only deeper-indented lines are skipped.

Also makes pragma parsing more flexible with multiple comma-separated
pragmas on a single line, and documents both the block and class pragmas
in the README.

Author: nicklafleur

README.rst

@@ -268,6 +268,73 @@ This is useful for functions that:
 - Are known to cause issues with the mutation testing framework
 
 
+Skipping Entire Classes
+~~~~~~~~~~~~~~~~~~~~~~~
+
+You can skip an entire class (including all of its methods) from mutation
+using ``# pragma: no mutate class``:
+
+.. code-block:: python
+
+    class MySettings:  # pragma: no mutate class
+        DEBUG = True
+        MAX_RETRIES = 3
+
+Both syntax styles are supported:
+
+- ``# pragma: no mutate class``
+- ``# pragma: no mutate: class``
+
+This is useful for configuration classes, constants containers, or any class
+where mutations would not produce meaningful test failures.
+
+
+Skipping Code Blocks
+~~~~~~~~~~~~~~~~~~~~
+
+You can skip an entire indentation block from mutation using
+``# pragma: no mutate block``. The pragma suppresses mutations for all
+subsequent lines at the same or deeper indentation level, until the
+indentation drops back.
+
+When placed on its own line, it ignores everything at the same indent level
+and below:
+
+.. code-block:: python
+
+    def foo():
+        # pragma: no mutate block
+        x = 1
+        y = complex_calculation()
+        z = x + y
+
+    def bar():
+        # this function is still mutated normally
+        return 42
+
+When placed inline after code, it ignores only the indented body:
+
+.. code-block:: python
+
+    if error_condition:  # pragma: no mutate block
+        log_error()
+        send_alert()
+    else:
+        # the else branch is still mutated normally
+        handle_success()
+
+Both syntax styles are supported:
+
+- ``# pragma: no mutate block``
+- ``# pragma: no mutate: block``
+
+This is useful for:
+
+- Error-handling branches that are hard to unit test in isolation
+- Logging or telemetry blocks that don't affect program correctness
+- Generated or boilerplate code within an otherwise mutable function
+
+
 Modifying pytest arguments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

src/mutmut/mutation/pragma_handling.py

@@ -1,5 +1,8 @@
 """Pragma comment parsing for mutation control."""
 
+from enum import Enum
+from enum import auto
+
 
 def parse_pragma_lines(source: str) -> tuple[set[int], set[int], set[int]]:
     """Parse all pragma: no mutate variants.
@@ -12,30 +15,80 @@ def parse_pragma_lines(source: str) -> tuple[set[int], set[int], set[int]]:
         - ``# pragma: no mutate: class`` - skip entire class (alternative syntax)
         - ``# pragma: no mutate function`` - skip entire function
         - ``# pragma: no mutate: function`` - skip entire function (alternative syntax)
+        - ``# pragma: no mutate block`` - skip all lines in the current indentation block
+        - ``# pragma: no mutate: block`` - skip all lines in the current indentation block (alternative syntax)
+
+    Block pragma behaviour depends on placement:
+        - On its own line (``# pragma: no mutate block``): all subsequent lines at
+          the **same or deeper** indentation are skipped until a dedent.
+        - Inline after code (``if cond:  # pragma: no mutate block``): all lines
+          indented **deeper** than the pragma line are skipped.
 
     :return: A tuple of (no_mutate_lines, class_lines, function_lines)
     """
+
+    class BlockMode(Enum):
+        INLINE = auto()
+        INDENT = auto()
+
     no_mutate_lines: set[int] = set()
     class_lines: set[int] = set()
     function_lines: set[int] = set()
 
+    block_level: int | None = None
+    block_mode: BlockMode | None = None
+
     for i, line in enumerate(source.split("\n")):
+        line_num = i + 1
+
+        if block_level is not None:
+            stripped = line.lstrip()
+            if stripped == "":
+                no_mutate_lines.add(line_num)
+                continue
+
+            curr = len(line) - len(stripped)
+            if block_mode == BlockMode.INDENT:
+                filter = curr >= block_level
+            elif block_mode == BlockMode.INLINE:
+                filter = curr > block_level
+            else:
+                raise ValueError(f"block_mode cannot be {block_mode}")
+
+            if filter:
+                no_mutate_lines.add(line_num)
+                continue
+            else:
+                block_level = None
+                block_mode = None
+
         if "# pragma:" not in line:
             continue
 
         pragma_content = line.partition("# pragma:")[-1]
-        line_num = i + 1
 
         if "no mutate" not in pragma_content:
             continue
 
-        # Check for specific variants first (more specific matches)
-        if "no mutate class" in pragma_content or "no mutate: class" in pragma_content:
-            class_lines.add(line_num)
-        elif "no mutate function" in pragma_content or "no mutate: function" in pragma_content:
-            function_lines.add(line_num)
-        else:
-            # Generic "no mutate" (not class or function)
-            no_mutate_lines.add(line_num)
+        pragma_content = line.partition("no mutate")[-1].strip()
+        tokens = pragma_content.lstrip(": ").split(",", 1)[0].split()
+        tok = tokens[0] if tokens else None
+        match tok:
+            # Check for specific variants first (more specific matches)
+            case "class":
+                class_lines.add(line_num)
+            case "function":
+                function_lines.add(line_num)
+                # Generic "no mutate" (not class or function)
+            case "block":
+                no_mutate_lines.add(line_num)
+                stripped = line.lstrip()
+                block_level = len(line) - len(stripped)
+                if stripped.startswith("# pragma"):
+                    block_mode = BlockMode.INDENT
+                else:
+                    block_mode = BlockMode.INLINE
+            case _:
+                no_mutate_lines.add(line_num)
 
     return no_mutate_lines, class_lines, function_lines

tests/mutation/test_pragma_handling.py

@@ -95,3 +95,65 @@ def test_other_pragma_ignored(self):
         assert no_mutate == set()
         assert class_lines == set()
         assert function_lines == set()
+
+    def test_block_pragma_own_line(self):
+        source = "if condition:\n    # pragma: no mutate block\n    x = 1\n    y = 2\nz = 3\n"
+        no_mutate, class_lines, function_lines = parse_pragma_lines(source)
+        assert no_mutate == {2, 3, 4}
+        assert class_lines == set()
+        assert function_lines == set()
+
+    def test_block_pragma_own_line_with_colon(self):
+        source = "if condition:\n    # pragma: no mutate: block\n    x = 1\n    y = 2\nz = 3\n"
+        no_mutate, class_lines, function_lines = parse_pragma_lines(source)
+        assert no_mutate == {2, 3, 4}
+        assert class_lines == set()
+        assert function_lines == set()
+
+    def test_block_pragma_inline(self):
+        source = "if condition:  # pragma: no mutate block\n    x = 1\n    y = 2\nz = 3\n"
+        no_mutate, class_lines, function_lines = parse_pragma_lines(source)
+        assert no_mutate == {1, 2, 3}
+        assert class_lines == set()
+        assert function_lines == set()
+
+    def test_block_pragma_does_not_affect_code_after_dedent(self):
+        source = "def foo():\n    # pragma: no mutate block\n    x = 1\n    y = 2\n\ndef bar():\n    z = 3\n"
+        no_mutate, class_lines, function_lines = parse_pragma_lines(source)
+        assert no_mutate == {2, 3, 4, 5}
+        assert 6 not in no_mutate
+        assert 7 not in no_mutate
+
+    def test_block_pragma_includes_nested_indentation(self):
+        source = "def foo():\n    # pragma: no mutate block\n    if True:\n        x = 1\n    y = 2\nz = 3\n"
+        no_mutate, class_lines, function_lines = parse_pragma_lines(source)
+        assert no_mutate == {2, 3, 4, 5}
+        assert 6 not in no_mutate
+
+    def test_block_pragma_inline_only_ignores_deeper(self):
+        """Inline block pragma on an if-statement: the else branch at the same
+        indentation is NOT ignored because it is not deeper."""
+        source = "if condition:  # pragma: no mutate block\n    x = 1\n    y = 2\nelse:\n    z = 3\n"
+        no_mutate, class_lines, function_lines = parse_pragma_lines(source)
+        assert no_mutate == {1, 2, 3}
+        assert 4 not in no_mutate
+        assert 5 not in no_mutate
+
+    def test_block_pragma_with_other_pragmas(self):
+        source = (
+            "class Skipped:  # pragma: no mutate class\n"
+            "    pass\n"
+            "\n"
+            "def foo():\n"
+            "    # pragma: no mutate block\n"
+            "    x = 1\n"
+            "    y = 2\n"
+            "\n"
+            "def bar():\n"
+            "    z = 3  # pragma: no mutate\n"
+        )
+        no_mutate, class_lines, function_lines = parse_pragma_lines(source)
+        assert class_lines == {1}
+        assert 5 in no_mutate and 6 in no_mutate and 7 in no_mutate
+        assert 10 in no_mutate
+        assert 9 not in no_mutate