mutmut 3.5.0__tar.gz → 3.6.0__tar.gz

{mutmut-3.5.0 → mutmut-3.6.0}/HISTORY.rst

@@ -1,12 +1,53 @@
 Changelog
 ---------
 
+3.6.0
+~~~~~
+
+* Add `# pragma: no mutate block` and `# pragma: no mutate start/end` comments
+
+* Add `do_not_mutate_patterns` to disable mutations with a regex
+
+* Add `only_mutate` config to select which files get mutated
+
+* Also mutate methods decorated with (only) `@staticmethod` or `@classmethod`
+
+* Add `use_setproctitle` option to disable process renaming (automatically disabled on MacOS)
+
+* Add (unstable) `timeout_multiplier` and `timeout_constant` options
+
+* Rename `paths_to_mutate` to `source_paths`
+
+* Deprecate `tests_dir` in favor of `pytest_add_cli_args_test_selection`
+
+* Change `max_stack_depth` to only consider functions inside `source_paths`
+
+* Disable mutation of enums and `@staticmethod`/`@classmethod` methods when `type_check_command` is set, as these mutations break type checking
+
+* Fix mutation for enum class methods
+
+* Fix mutate_only_covered_lines when project uses custom coverage.py config
+
+* Fix execution when running mutmut via `python -m mutmut run`
+
+* Fix mutation of `class _SomePrivateClass` class methods
+
+* Fix mutation of default args
+
+* Fix `mutmut browse` crash when no file is selected yet
+
+* Fix timeout checker looking up the wrong mutant's expected test time, which could cause mutants to hang
+
+* Compare stats paths after resolving symlinks
+
+* Warn when mutmut cannot match mutants with the collected stats
+
 3.5.0
 ~~~~~
 
 * Filter mutants based on type annotations. This feature needs to be turned on with the `type_check_command` config.
 
-* Support running on Windows
+* Show error message when running on Windows
 
 * Save mutation stats for use with CI/CD pipeline (#460)
 

{mutmut-3.5.0 → mutmut-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mutmut
-Version: 3.5.0
+Version: 3.6.0
 Summary: mutation testing for Python 3
 Keywords: mutmut,mutant,mutation,test,testing
 Author: Anders Hovmöller
@@ -86,8 +86,7 @@ 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.
 
 To work with the results, use `mutmut browse` where you can see the mutants,
 retest them when you've updated your tests.
@@ -122,7 +121,7 @@ In `setup.cfg` in the root of your project you can configure mutmut if you need
 .. code-block:: ini
 
     [mutmut]
-    paths_to_mutate=src/
+    source_paths=src/
     pytest_add_cli_args_test_selection=tests/
 
 If you use `pyproject.toml`, you must specify the paths as array in a `tool.mutmut` section:
@@ -130,7 +129,7 @@ If you use `pyproject.toml`, you must specify the paths as array in a `tool.mutm
 .. code-block:: toml
 
     [tool.mutmut]
-    paths_to_mutate = [ "src/" ]
+    source_paths = [ "src/" ]
     pytest_add_cli_args_test_selection= [ "tests/" ]
 
 See below for more options for configuring mutmut.
@@ -162,8 +161,8 @@ introduced bug in those base functions will lead to many tests that fail which
 are hard to understand how they relate to the function with the change.
 
 You can configure mutmut to only count a test as being relevant for a function
-if the stack depth from the test to the function is below some limit. In your
-`setup.cfg` add:
+if the stack depth is below some limit. Only stack frames from code inside `source_paths`
+is counted towards the limit, 3rd party libraries are ignored. In your `setup.cfg` add:
 
 .. code-block:: ini
 
@@ -177,10 +176,14 @@ caught.
 Exclude files from mutation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+By default mutmut mutates all python files in `source_paths`.
 You can exclude files from mutation in `setup.cfg`:
 
 .. code-block::
 
+    only_mutate=
+        src/api/*
+        src/services/*
     do_not_mutate=
         *__tests.py
 
@@ -221,7 +224,7 @@ To enable this filtering, configure the `type_check_command` to output json resu
     # for pyrefly
     type_check_command = ['pyrefly', 'check', '--output-format=json']
     # for mypy
-    type_check_command = ['mypy', 'traces_parser', '--output', 'json']
+    type_check_command = ['mypy', 'your_source_dir', '--output', 'json', '--disable-error-code', 'unused-ignore']
 
 Currently, only `pyrefly` and `mypy` are supported.
 With `pyright` and `ty`, mutating a class method `Foo.bar()` can break the types of all methods of `Foo`,
@@ -242,22 +245,174 @@ to failing tests.
     debug=true
 
 
-Whitelisting
-~~~~~~~~~~~~
+Disable setproctitle (macOS)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can mark lines like this:
+Mutmut uses ``setproctitle`` to show the current mutant name in the process
+list, which is helpful for monitoring long runs. However, ``setproctitle``
+uses CoreFoundation APIs on macOS that are not fork-safe, causing segfaults
+in child processes.
 
-.. code-block:: python
+By default, mutmut automatically disables ``setproctitle`` on macOS and
+enables it on other platforms. If you need to override this (e.g. to enable it on
+macOS at your own risk, or to disable it on other platforms), set ``use_setproctitle``:
+
+.. code-block:: toml
+
+    # pyproject.toml
+    [tool.mutmut]
+    use_setproctitle = false
 
-    some_code_here()  # pragma: no mutate
 
-to stop mutation on those lines. Some cases we've found where you need to
-whitelist lines are:
+Disabling mutation on specific code
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- The version string on your library. You really shouldn't have a test for this :P
+If you do not want to mutate specific parts of your code, you can disable mutation
+via the following options. Examples where this could be relevant:
+
+- If you don't want to test exact log messages (e.g. `logging.info("Foo")` versus the mutated `logging.info("XXFooXX")`)
 - Optimizing break instead of continue. The code runs fine when mutating break
   to continue, but it's slower.
 
+Skipping via regex
+^^^^^^^^^^^^^^^^^^
+
+You can use a regex on the source code, to tell mutmut which expressions it should not mutate:
+
+.. code-block:: toml
+
+    # pyproject.toml
+    [tool.mutmut]
+    do_not_mutate_patterns = [
+        # disable mutations of all logger.info/debug/... statements
+        'logger\.\w+',
+        # disable mutating exceptions
+        'raise \w+',
+    ]
+
+Mutmut will match the regex on the source code
+and skip mutating any expression on the matched lines.
+
+Skipping via code comments
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can use following comments to disable mutation:
+
+- `# pragma: no mutate`: disable mutation on this single line
+- `# pragma: no mutate block`: disable mutation in the whole intendation block
+- `# pragma: no mutate start/end`: disable mutation between the start and end comments
+
+Skipping single lines
+^^^^^^^^^^^^^^^^^^^^^
+
+You can mark lines like this to stop mutating them:
+
+.. code-block:: python
+
+    some_code_here()  # pragma: no mutate
+
+
+Skipping Code Blocks
+^^^^^^^^^^^^^^^^^^^^
+
+You can skip an entire indentation block from mutation using
+``# pragma: no mutate block``. This works on any compound statement --
+functions, classes, ``if``/``elif``/``else``, loops, context managers, etc.
+
+Both syntax styles are supported:
+
+- ``# pragma: no mutate block``
+- ``# pragma: no mutate: block``
+
+**Skipping an entire function or class** -- place the pragma inline on the
+definition line. The entire node (including all children) is skipped and no
+trampoline is generated:
+
+.. code-block:: python
+
+    def complex_algorithm():  # pragma: no mutate block
+        return some_complex_calculation()
+
+    class MySettings:  # pragma: no mutate block
+        DEBUG = True
+        MAX_RETRIES = 3
+
+**Skipping only the body of a function** -- place the pragma on its own line
+inside the function. The function definition (including default arguments) is
+still mutable, but the body is suppressed:
+
+.. code-block:: python
+
+    def foo(val=1):
+        # pragma: no mutate block
+        x = 1
+        y = complex_calculation()
+        z = x + y
+
+    def bar():
+        # this function is still mutated normally
+        return 42
+
+**Skipping an ``if`` branch without affecting ``elif``/``else``** -- place
+the pragma inline on the ``if``. Only the ``if`` condition and its indented
+body are suppressed; sibling branches (``elif``, ``else``) remain mutable
+because they exit the original indentation scope:
+
+.. code-block:: python
+
+    if error_condition:  # pragma: no mutate block
+        log_error()
+        send_alert()
+    elif other_condition:
+        # still mutated -- this branch is outside the block scope
+        handle_other()
+    else:
+        # still mutated
+        handle_success()
+
+The same principle applies to ``for``/``else``, ``while``/``else``,
+``try``/``except``/``finally``, and ``match``/``case``.
+
+This is useful for:
+
+- Functions or classes that should be excluded from mutation entirely
+- 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
+
+
+Skipping Code Regions
+^^^^^^^^^^^^^^^^^^^^^
+
+For suppressing mutations across a range of lines regardless of indentation,
+use ``# pragma: no mutate start`` and ``# pragma: no mutate end``:
+
+.. code-block:: python
+
+    a = mutate_this()
+
+    # pragma: no mutate start
+    b = skip_this()
+    c = skip_this_too()
+    # pragma: no mutate end
+
+    d = mutate_this_too()
+
+Every line between the markers (inclusive) is suppressed. This works inside
+functions, classes, or at module level, and ignores indentation entirely.
+
+An unmatched ``# pragma: no mutate end`` without a preceding ``start`` raises
+a ``PragmaParseError`` at parse time.  An unclosed ``# pragma: no mutate start``
+(no matching ``end`` before end-of-file) raises a ``PragmaParseError``.
+Both errors include the filename and line number.
+
+**Nesting restriction:** opening a new ``block`` or ``start`` context while
+another context is already active is not allowed and raises a
+``PragmaParseError``.  The error message includes both the offending line and
+the line where the existing context was opened.  Close the current context
+first (dedent for ``block``, or ``# pragma: no mutate end`` for ``start``)
+before opening a new one.
+
 
 Modifying pytest arguments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -279,6 +434,20 @@ You can add and override pytest arguments:
     also_copy = ["mutmut_pytest.ini"]
 
 
+Unstable configs
+~~~~~~~~~~~~~~~~
+
+Following configurations exist, but may be changed in any minor version.
+If you use them, expect that a new version could change or break this feature.
+
+
+.. code-block:: toml
+
+    # Configure how long mutmut waits before killing a slow mutation
+    # Currently calculated as (duration_of_original_tests + timeout_constant) * timeout_multiplier seconds
+    timeout_constant = 1.0
+    timeout_multiplier = 15.0
+
 
 Example mutations
 -----------------

{mutmut-3.5.0 → mutmut-3.6.0}/README.rst

@@ -53,8 +53,7 @@ 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.
 
 To work with the results, use `mutmut browse` where you can see the mutants,
 retest them when you've updated your tests.
@@ -89,7 +88,7 @@ In `setup.cfg` in the root of your project you can configure mutmut if you need
 .. code-block:: ini
 
     [mutmut]
-    paths_to_mutate=src/
+    source_paths=src/
     pytest_add_cli_args_test_selection=tests/
 
 If you use `pyproject.toml`, you must specify the paths as array in a `tool.mutmut` section:
@@ -97,7 +96,7 @@ If you use `pyproject.toml`, you must specify the paths as array in a `tool.mutm
 .. code-block:: toml
 
     [tool.mutmut]
-    paths_to_mutate = [ "src/" ]
+    source_paths = [ "src/" ]
     pytest_add_cli_args_test_selection= [ "tests/" ]
 
 See below for more options for configuring mutmut.
@@ -129,8 +128,8 @@ introduced bug in those base functions will lead to many tests that fail which
 are hard to understand how they relate to the function with the change.
 
 You can configure mutmut to only count a test as being relevant for a function
-if the stack depth from the test to the function is below some limit. In your
-`setup.cfg` add:
+if the stack depth is below some limit. Only stack frames from code inside `source_paths`
+is counted towards the limit, 3rd party libraries are ignored. In your `setup.cfg` add:
 
 .. code-block:: ini
 
@@ -144,10 +143,14 @@ caught.
 Exclude files from mutation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+By default mutmut mutates all python files in `source_paths`.
 You can exclude files from mutation in `setup.cfg`:
 
 .. code-block::
 
+    only_mutate=
+        src/api/*
+        src/services/*
     do_not_mutate=
         *__tests.py
 
@@ -188,7 +191,7 @@ To enable this filtering, configure the `type_check_command` to output json resu
     # for pyrefly
     type_check_command = ['pyrefly', 'check', '--output-format=json']
     # for mypy
-    type_check_command = ['mypy', 'traces_parser', '--output', 'json']
+    type_check_command = ['mypy', 'your_source_dir', '--output', 'json', '--disable-error-code', 'unused-ignore']
 
 Currently, only `pyrefly` and `mypy` are supported.
 With `pyright` and `ty`, mutating a class method `Foo.bar()` can break the types of all methods of `Foo`,
@@ -209,22 +212,174 @@ to failing tests.
     debug=true
 
 
-Whitelisting
-~~~~~~~~~~~~
+Disable setproctitle (macOS)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can mark lines like this:
+Mutmut uses ``setproctitle`` to show the current mutant name in the process
+list, which is helpful for monitoring long runs. However, ``setproctitle``
+uses CoreFoundation APIs on macOS that are not fork-safe, causing segfaults
+in child processes.
 
-.. code-block:: python
+By default, mutmut automatically disables ``setproctitle`` on macOS and
+enables it on other platforms. If you need to override this (e.g. to enable it on
+macOS at your own risk, or to disable it on other platforms), set ``use_setproctitle``:
+
+.. code-block:: toml
+
+    # pyproject.toml
+    [tool.mutmut]
+    use_setproctitle = false
 
-    some_code_here()  # pragma: no mutate
 
-to stop mutation on those lines. Some cases we've found where you need to
-whitelist lines are:
+Disabling mutation on specific code
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- The version string on your library. You really shouldn't have a test for this :P
+If you do not want to mutate specific parts of your code, you can disable mutation
+via the following options. Examples where this could be relevant:
+
+- If you don't want to test exact log messages (e.g. `logging.info("Foo")` versus the mutated `logging.info("XXFooXX")`)
 - Optimizing break instead of continue. The code runs fine when mutating break
   to continue, but it's slower.
 
+Skipping via regex
+^^^^^^^^^^^^^^^^^^
+
+You can use a regex on the source code, to tell mutmut which expressions it should not mutate:
+
+.. code-block:: toml
+
+    # pyproject.toml
+    [tool.mutmut]
+    do_not_mutate_patterns = [
+        # disable mutations of all logger.info/debug/... statements
+        'logger\.\w+',
+        # disable mutating exceptions
+        'raise \w+',
+    ]
+
+Mutmut will match the regex on the source code
+and skip mutating any expression on the matched lines.
+
+Skipping via code comments
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can use following comments to disable mutation:
+
+- `# pragma: no mutate`: disable mutation on this single line
+- `# pragma: no mutate block`: disable mutation in the whole intendation block
+- `# pragma: no mutate start/end`: disable mutation between the start and end comments
+
+Skipping single lines
+^^^^^^^^^^^^^^^^^^^^^
+
+You can mark lines like this to stop mutating them:
+
+.. code-block:: python
+
+    some_code_here()  # pragma: no mutate
+
+
+Skipping Code Blocks
+^^^^^^^^^^^^^^^^^^^^
+
+You can skip an entire indentation block from mutation using
+``# pragma: no mutate block``. This works on any compound statement --
+functions, classes, ``if``/``elif``/``else``, loops, context managers, etc.
+
+Both syntax styles are supported:
+
+- ``# pragma: no mutate block``
+- ``# pragma: no mutate: block``
+
+**Skipping an entire function or class** -- place the pragma inline on the
+definition line. The entire node (including all children) is skipped and no
+trampoline is generated:
+
+.. code-block:: python
+
+    def complex_algorithm():  # pragma: no mutate block
+        return some_complex_calculation()
+
+    class MySettings:  # pragma: no mutate block
+        DEBUG = True
+        MAX_RETRIES = 3
+
+**Skipping only the body of a function** -- place the pragma on its own line
+inside the function. The function definition (including default arguments) is
+still mutable, but the body is suppressed:
+
+.. code-block:: python
+
+    def foo(val=1):
+        # pragma: no mutate block
+        x = 1
+        y = complex_calculation()
+        z = x + y
+
+    def bar():
+        # this function is still mutated normally
+        return 42
+
+**Skipping an ``if`` branch without affecting ``elif``/``else``** -- place
+the pragma inline on the ``if``. Only the ``if`` condition and its indented
+body are suppressed; sibling branches (``elif``, ``else``) remain mutable
+because they exit the original indentation scope:
+
+.. code-block:: python
+
+    if error_condition:  # pragma: no mutate block
+        log_error()
+        send_alert()
+    elif other_condition:
+        # still mutated -- this branch is outside the block scope
+        handle_other()
+    else:
+        # still mutated
+        handle_success()
+
+The same principle applies to ``for``/``else``, ``while``/``else``,
+``try``/``except``/``finally``, and ``match``/``case``.
+
+This is useful for:
+
+- Functions or classes that should be excluded from mutation entirely
+- 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
+
+
+Skipping Code Regions
+^^^^^^^^^^^^^^^^^^^^^
+
+For suppressing mutations across a range of lines regardless of indentation,
+use ``# pragma: no mutate start`` and ``# pragma: no mutate end``:
+
+.. code-block:: python
+
+    a = mutate_this()
+
+    # pragma: no mutate start
+    b = skip_this()
+    c = skip_this_too()
+    # pragma: no mutate end
+
+    d = mutate_this_too()
+
+Every line between the markers (inclusive) is suppressed. This works inside
+functions, classes, or at module level, and ignores indentation entirely.
+
+An unmatched ``# pragma: no mutate end`` without a preceding ``start`` raises
+a ``PragmaParseError`` at parse time.  An unclosed ``# pragma: no mutate start``
+(no matching ``end`` before end-of-file) raises a ``PragmaParseError``.
+Both errors include the filename and line number.
+
+**Nesting restriction:** opening a new ``block`` or ``start`` context while
+another context is already active is not allowed and raises a
+``PragmaParseError``.  The error message includes both the offending line and
+the line where the existing context was opened.  Close the current context
+first (dedent for ``block``, or ``# pragma: no mutate end`` for ``start``)
+before opening a new one.
+
 
 Modifying pytest arguments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -246,6 +401,20 @@ You can add and override pytest arguments:
     also_copy = ["mutmut_pytest.ini"]
 
 
+Unstable configs
+~~~~~~~~~~~~~~~~
+
+Following configurations exist, but may be changed in any minor version.
+If you use them, expect that a new version could change or break this feature.
+
+
+.. code-block:: toml
+
+    # Configure how long mutmut waits before killing a slow mutation
+    # Currently calculated as (duration_of_original_tests + timeout_constant) * timeout_multiplier seconds
+    timeout_constant = 1.0
+    timeout_multiplier = 15.0
+
 
 Example mutations
 -----------------

{mutmut-3.5.0 → mutmut-3.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mutmut"
-version = "3.5.0"
+version = "3.6.0"
 description = "mutation testing for Python 3"
 keywords = ["mutmut", "mutant", "mutation", "test", "testing"]
 authors = [
@@ -54,9 +54,11 @@ source-include = ["HISTORY.rst"]
 [dependency-groups]
 dev = [
     "inline-snapshot>=0.32.0",
-    "pyrefly>=0.53.0",
+    "mypy>=1.20.1",
+    "pre-commit>=4.5.1",
+    "pyrefly>=0.59.1",
     "pytest-asyncio>=1.0.0",
-    "ruff>=0.15.1",
+    "ruff>=0.15.7",
 ]
 
 [tool.pytest.ini_options]
@@ -67,3 +69,34 @@ asyncio_default_fixture_loop_scope = "function"
 
 [tool.inline-snapshot]
 format-command="ruff format --stdin-filename {filename}"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+extend-exclude = [
+    "docs/_themes/",
+    "docs/conf.py",
+    "e2e_projects/",
+    "tests/data/test_generation/",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "B", "C4", "UP", "I"]
+ignore = [
+    "E501",  # line too long - handled by formatter
+    "B007",  # unused loop control variable
+    "B018",  # useless expression
+    "B024",  # abstract base class without abstract methods
+    "B027",  # empty method in abstract base class without abstract decorator
+    "B028",  # no explicit stacklevel in warnings.warn
+    "B904",  # raise without from in except
+    "C405",  # unnecessary list literal
+    "C408",  # unnecessary dict() call
+    "C416",  # unnecessary list comprehension
+    "F402",  # import shadowed by loop variable
+    "F841",  # local variable assigned but never used
+    "UP007", # use X | Y for type annotations
+]
+
+[tool.ruff.lint.isort]
+force-single-line = true

mutmut-3.6.0/src/mutmut/__init__.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import importlib.metadata
+import warnings
+from collections import defaultdict
+
+from mutmut.configuration import Config
+
+__version__ = importlib.metadata.version("mutmut")
+
+
+stats_time: float | None = None
+duration_by_test: dict[str, float] = defaultdict(float)
+tests_by_mangled_function_name: dict[str, set[str]] = defaultdict(set)
+
+_stats: set[str] = set()
+_covered_lines: dict[str, set[int]] | None = None
+
+
+def __getattr__(name: str) -> object:
+    match name:
+        case "config":
+            warnings.warn(
+                "mutmut.config is deprecated as of 3.4.1, use mutmut.configuration.Config.get() instead",
+                FutureWarning,
+                stacklevel=2,
+            )
+            return Config.get()
+        case _:
+            raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def _reset_globals() -> None:
+    global duration_by_test, stats_time, _stats, tests_by_mangled_function_name
+    global _covered_lines
+
+    duration_by_test.clear()
+    stats_time = None
+    Config.reset()
+    _stats = set()
+    tests_by_mangled_function_name = defaultdict(set)
+    _covered_lines = None