mutmut 2.4.4__tar.gz → 2.4.5__tar.gz

{mutmut-2.4.4 → mutmut-2.4.5}/AUTHORS.rst

@@ -28,3 +28,11 @@ Credits
 * Daniel Versoza Alves <daniel.alves@voxy.com>
 * Zac Hatfield-Dodds <zac.hatfield.dodds@gmail.com>
 * Jan Królikowski <yanekk86@gmail.com>
+* Tal Amuyal <talamuyal@gmail.com>
+* Eivind Jahren <eivind.jahren@gmail.com>
+* WiredNerd <pbuschmail-gitlab@yahoo.com>
+* Kees Hink <kees@fourdigits.nl>
+* Jim Rybarski <jim@rybarski.com>
+* Christopher J. Brody <chris.brody+brodybits@gmail.com>
+* Century-ss <hgfc7543ggfdch@gmail.com>
+* Michael Champagne <michael.champagne@elapsetech.com>

{mutmut-2.4.4 → mutmut-2.4.5}/HISTORY.rst

@@ -1,6 +1,17 @@
 Changelog
 ---------
 
+2.4.5
+~~~~~
+
+* Add skipped column in html index report
+
+* Untested/skipped in show all does not show skipped
+
+* mutmut should pick up the config before running the original tests. That allows to specify test suits you want to run
+
+* improved some high-level help text & documentation
+
 2.4.4
 ~~~~~
 

{mutmut-2.4.4 → mutmut-2.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mutmut
-Version: 2.4.4
+Version: 2.4.5
 Summary: mutation testing for Python 3
 Home-page: https://github.com/boxed/mutmut
 Author: Anders Hovmöller
@@ -56,16 +56,24 @@ Description: mutmut - python mutation tester
         
         This will by default run pytest (or unittest if pytest is unavailable)
         on tests in the "tests" or "test" folder and
-        it will try to figure out where the code to mutate lies. Run
+        it will try to figure out where the code to mutate lies.
+        
+        NOTE that mutmut will apply the mutations directly, one at a time;
+        it is **highly** recommended to add all changes to source control
+        before running.
+        
+        Enter
         
         .. code-block:: console
         
-            mutmut --help
+            mutmut run --help
         
         for the available flags, to use other runners, etc. The recommended way to use
-        mutmut if the defaults aren't working for you is to add a block in ``setup.cfg``.
+        mutmut if the defaults aren't working for you is to add a
+        block in ``setup.cfg`` or ``project.toml``.
         Then when you come back to mutmut weeks later you don't have to figure out the
-        flags again, just run ``mutmut run`` and it works. Like this:
+        flags again, just run ``mutmut run`` and it works.
+        Like this in ``setup.cfg``:
         
         .. code-block:: ini
         
@@ -76,6 +84,14 @@ Description: mutmut - python mutation tester
             tests_dir=tests/
             dict_synonyms=Struct, NamedStruct
         
+        or like this in ``pyproject.toml``:
+        
+        .. code-block:: ini
+        
+            [tool.mutmut]
+            paths_to_mutate="src"
+            runner="python -m hammett -x"
+        
         To use multiple paths either in the ``paths_to_mutate`` or ``tests_dir`` option
         use a comma or colon separated list. For example:
         
@@ -94,11 +110,11 @@ Description: mutmut - python mutation tester
         all mutants for a specific file with ``mutmut show path/to/file.py`` or all mutants
         with ``mutmut show all``.
         
-        
         You can also write a mutant to disk with ``mutmut apply 3``. You should **REALLY**
         have the file you mutate under source code control and committed before you apply
         a mutant!
         
+        To generate a HTML report for a web browser: ``mutmut html``
         
         Whitelisting
         ------------

{mutmut-2.4.4 → mutmut-2.4.5}/README.rst

@@ -48,16 +48,24 @@ You can get started with a simple:
 
 This will by default run pytest (or unittest if pytest is unavailable)
 on tests in the "tests" or "test" folder and
-it will try to figure out where the code to mutate lies. Run
+it will try to figure out where the code to mutate lies.
+
+NOTE that mutmut will apply the mutations directly, one at a time;
+it is **highly** recommended to add all changes to source control
+before running.
+
+Enter
 
 .. code-block:: console
 
-    mutmut --help
+    mutmut run --help
 
 for the available flags, to use other runners, etc. The recommended way to use
-mutmut if the defaults aren't working for you is to add a block in ``setup.cfg``.
+mutmut if the defaults aren't working for you is to add a
+block in ``setup.cfg`` or ``project.toml``.
 Then when you come back to mutmut weeks later you don't have to figure out the
-flags again, just run ``mutmut run`` and it works. Like this:
+flags again, just run ``mutmut run`` and it works.
+Like this in ``setup.cfg``:
 
 .. code-block:: ini
 
@@ -68,6 +76,14 @@ flags again, just run ``mutmut run`` and it works. Like this:
     tests_dir=tests/
     dict_synonyms=Struct, NamedStruct
 
+or like this in ``pyproject.toml``:
+
+.. code-block:: ini
+
+    [tool.mutmut]
+    paths_to_mutate="src"
+    runner="python -m hammett -x"
+
 To use multiple paths either in the ``paths_to_mutate`` or ``tests_dir`` option
 use a comma or colon separated list. For example:
 
@@ -86,11 +102,11 @@ grouped by file. You can now look at a specific mutant diff with ``mutmut show 3
 all mutants for a specific file with ``mutmut show path/to/file.py`` or all mutants
 with ``mutmut show all``.
 
-
 You can also write a mutant to disk with ``mutmut apply 3``. You should **REALLY**
 have the file you mutate under source code control and committed before you apply
 a mutant!
 
+To generate a HTML report for a web browser: ``mutmut html``
 
 Whitelisting
 ------------

{mutmut-2.4.4 → mutmut-2.4.5}/mutmut/__init__.py

@@ -1,4 +1,6 @@
 # -*- coding: utf-8 -*-
+from __future__ import annotations
+
 import fnmatch
 import itertools
 import multiprocessing
@@ -10,6 +12,7 @@ import sys
 import toml
 from configparser import ConfigParser
 from copy import copy as copy_obj
+from dataclasses import dataclass, field
 from functools import wraps
 from io import (
     open,
@@ -25,11 +28,12 @@ from threading import (
     Thread,
 )
 from time import time
+from typing import Callable, Dict, Iterator, List, Optional, Set, Tuple
 
 from parso import parse
 from parso.python.tree import Name, Number, Keyword, FStringStart, FStringEnd
 
-__version__ = '2.4.4'
+__version__ = '2.4.5'
 
 
 if os.getcwd() not in sys.path:
@@ -40,21 +44,12 @@ except ImportError:
     mutmut_config = None
 
 
-class RelativeMutationID(object):
-    def __init__(self, line, index, line_number, filename=None):
-        self.line = line
-        self.index = index
-        self.line_number = line_number
-        self.filename = filename
-
-    def __repr__(self):
-        return 'MutationID(line="{}", index={}, line_number={}, filename={})'.format(self.line, self.index, self.line_number, self.filename)
-
-    def __eq__(self, other):
-        return (self.line, self.index, self.line_number) == (other.line, other.index, other.line_number)
-
-    def __hash__(self):
-        return hash((self.line, self.index, self.line_number))
+@dataclass(frozen=True)
+class RelativeMutationID:
+    line: str
+    index: int
+    line_number: int
+    filename: Optional[str] = field(default=None, compare=False, hash=False)
 
 
 ALL = RelativeMutationID(filename='%all%', line='%all%', index=-1, line_number=-1)
@@ -64,7 +59,7 @@ class InvalidASTPatternException(Exception):
     pass
 
 
-class ASTPattern(object):
+class ASTPattern:
     def __init__(self, source, **definitions):
         if definitions is None:
             definitions = {}
@@ -288,12 +283,10 @@ def lambda_mutation(children, **_):
 NEWLINE = {'formatting': [], 'indent': '', 'type': 'endl', 'value': ''}
 
 
-def argument_mutation(children, context, **_):
+def argument_mutation(children, context: Context, **_):
     """Mutate the arguments one by one from dict(a=b) to dict(aXXX=b).
 
     This is similar to the mutation of dict literals in the form {'a': b}.
-
-    :type context: Context
     """
     if len(context.stack) >= 3 and context.stack[-3].type in ('power', 'atom_expr'):
         stack_pos_of_power_node = -3
@@ -474,7 +467,7 @@ mutations_by_type = {
 # TODO: detect regexes and mutate them in nasty ways? Maybe mutate all strings as if they are regexes
 
 
-def should_exclude(context, config):
+def should_exclude(context, config: Optional[Config]):
     if config is None or config.covered_lines_by_filename is None:
         return False
 
@@ -495,8 +488,16 @@ def should_exclude(context, config):
     return False
 
 
-class Context(object):
-    def __init__(self, source=None, mutation_id=ALL, dict_synonyms=None, filename=None, config=None, index=0):
+class Context:
+    def __init__(
+        self,
+        source: Optional[str] = None,
+        mutation_id=ALL,
+        dict_synonyms=None,
+        filename=None,
+        config: Optional[Config] = None,
+        index=0,
+    ):
         self.index = index
         self.remove_newline_at_end = False
         self._source = None
@@ -562,11 +563,9 @@ class Context(object):
         return self.mutation_id in (ALL, self.mutation_id_of_current_index)
 
 
-def mutate(context):
+def mutate(context: Context) -> Tuple[str, int]:
     """
-    :type context: Context
     :return: tuple of mutated source code and number of mutations performed
-    :rtype: Tuple[str, int]
     """
     try:
         result = parse(context.source, error_recovery=False)
@@ -590,10 +589,7 @@ def mutate(context):
     return mutated_source, len(context.performed_mutation_ids)
 
 
-def mutate_node(node, context):
-    """
-    :type context: Context
-    """
+def mutate_node(node, context: Context):
     context.stack.append(node)
     try:
         if node.type in ('tfpdef', 'import_from', 'import_name'):
@@ -665,10 +661,7 @@ def mutate_node(node, context):
         context.stack.pop()
 
 
-def mutate_list_of_nodes(node, context):
-    """
-    :type context: Context
-    """
+def mutate_list_of_nodes(node, context: Context):
     return_annotation_started = False
 
     for child_node in node.children:
@@ -688,22 +681,13 @@ def mutate_list_of_nodes(node, context):
             return
 
 
-def list_mutations(context):
-    """
-    :type context: Context
-    """
+def list_mutations(context: Context):
     assert context.mutation_id == ALL
     mutate(context)
     return context.performed_mutation_ids
 
 
-def mutate_file(backup, context):
-    """
-    :type backup: bool
-    :type context: Context
-
-    :return: Tuple[str, str]
-    """
+def mutate_file(backup: bool, context: Context) -> Tuple[str, str]:
     with open(context.filename) as f:
         original = f.read()
     if backup:
@@ -715,7 +699,13 @@ def mutate_file(backup, context):
     return original, mutated
 
 
-def queue_mutants(*, progress, config, mutants_queue, mutations_by_file):
+def queue_mutants(
+    *,
+    progress: Progress,
+    config: Config,
+    mutants_queue,
+    mutations_by_file: Dict[str, List[RelativeMutationID]],
+):
     from mutmut.cache import get_cached_mutation_statuses
 
     try:
@@ -810,7 +800,9 @@ def run_mutation(context: Context, callback) -> str:
             return BAD_TIMEOUT
 
         time_elapsed = time() - start
-        if not survived and time_elapsed > config.test_time_base + (config.baseline_time_elapsed * config.test_time_multipler):
+        if not survived and time_elapsed > config.test_time_base + (
+            config.baseline_time_elapsed * config.test_time_multiplier
+        ):
             return OK_SUSPICIOUS
 
         if survived:
@@ -830,31 +822,31 @@ def run_mutation(context: Context, callback) -> str:
                 callback(result)
 
 
-class Config(object):
-    def __init__(self, swallow_output, test_command, covered_lines_by_filename,
-                 baseline_time_elapsed, test_time_multiplier, test_time_base,
-                 dict_synonyms, total, using_testmon,
-                 tests_dirs, hash_of_tests, pre_mutation, post_mutation,
-                 coverage_data, paths_to_mutate, mutation_types_to_apply, no_progress, ci, rerun_all):
-        self.swallow_output = swallow_output
-        self.test_command = self._default_test_command = test_command
-        self.covered_lines_by_filename = covered_lines_by_filename
-        self.baseline_time_elapsed = baseline_time_elapsed
-        self.test_time_multipler = test_time_multiplier
-        self.test_time_base = test_time_base
-        self.dict_synonyms = dict_synonyms
-        self.total = total
-        self.using_testmon = using_testmon
-        self.tests_dirs = tests_dirs
-        self.hash_of_tests = hash_of_tests
-        self.post_mutation = post_mutation
-        self.pre_mutation = pre_mutation
-        self.coverage_data = coverage_data
-        self.paths_to_mutate = paths_to_mutate
-        self.mutation_types_to_apply = mutation_types_to_apply
-        self.no_progress = no_progress
-        self.ci = ci
-        self.rerun_all = rerun_all
+@dataclass
+class Config:
+    swallow_output: bool
+    test_command: str
+    _default_test_command: str = field(init=False)
+    covered_lines_by_filename: Optional[Dict[str, set[Optional[int]]]]
+    baseline_time_elapsed: float
+    test_time_multiplier: float
+    test_time_base: float
+    dict_synonyms: List[str]
+    total: int
+    using_testmon: bool
+    tests_dirs: List[str]
+    hash_of_tests: str
+    post_mutation: str
+    pre_mutation: str
+    coverage_data: Dict[str, Dict[int, List[str]]]
+    paths_to_mutate: List[str]
+    mutation_types_to_apply: Set[str]
+    no_progress: bool
+    ci: bool
+    rerun_all: bool
+
+    def __post_init__(self):
+        self._default_test_command = self.test_command
 
 
 def tests_pass(config: Config, callback) -> bool:
@@ -923,11 +915,9 @@ def status_printer():
     return p
 
 
-def guess_paths_to_mutate():
-    """Guess the path to source code to mutate
 
-    :rtype: str
-    """
+def guess_paths_to_mutate() -> str:
+    """Guess the path to source code to mutate"""
     this_dir = os.getcwd().split(os.sep)[-1]
     if isdir('lib'):
         return 'lib'
@@ -950,7 +940,7 @@ def guess_paths_to_mutate():
         'section.')
 
 
-class Progress(object):
+class Progress:
     def __init__(self, total, output_legend, no_progress=False):
         self.total = total
         self.output_legend = output_legend
@@ -1009,24 +999,18 @@ def get_mutations_by_file_from_cache(mutation_pk):
     return {filename: [mutation_id]}
 
 
-def popen_streaming_output(cmd, callback, timeout=None):
+def popen_streaming_output(
+    cmd: str, callback: Callable[[str], None], timeout: Optional[float] = None
+) -> int:
     """Open a subprocess and stream its output without hard-blocking.
 
     :param cmd: the command to execute within the subprocess
-    :type cmd: str
-
     :param callback: function that intakes the subprocess' stdout line by line.
         It is called for each line received from the subprocess' stdout stream.
-    :type callback: Callable[[Context], bool]
-
     :param timeout: the timeout time of the subprocess
-    :type timeout: float
-
     :raises TimeoutError: if the subprocess' execution time exceeds
         the timeout time
-
     :return: the return code of the executed subprocess
-    :rtype: int
     """
     if os.name == 'nt':  # pragma: no cover
         process = subprocess.Popen(
@@ -1088,7 +1072,7 @@ def popen_streaming_output(cmd, callback, timeout=None):
     return process.returncode
 
 
-def hammett_tests_pass(config, callback):
+def hammett_tests_pass(config: Config, callback) -> bool:
     # noinspection PyUnresolvedReferences
     from hammett import main_cli
     modules_before = set(sys.modules.keys())
@@ -1143,12 +1127,12 @@ def hammett_tests_pass(config, callback):
 
 CYCLE_PROCESS_AFTER = 100
 
-def run_mutation_tests(config, progress, mutations_by_file):
-    """
-    :type config: Config
-    :type progress: Progress
-    :type mutations_by_file: dict[str, list[RelativeMutationID]]
-    """
+
+def run_mutation_tests(
+    config: Config,
+    progress: Progress,
+    mutations_by_file: Dict[str, List[RelativeMutationID]],
+):
     from mutmut.cache import update_mutant_status
 
     # Need to explicitly use the spawn method for python < 3.8 on macOS
@@ -1211,10 +1195,9 @@ def run_mutation_tests(config, progress, mutations_by_file):
             update_mutant_status(file_to_mutate=filename, mutation_id=mutation_id, status=status, tests_hash=config.hash_of_tests)
 
 
-def read_coverage_data():
+def read_coverage_data() -> Dict[str, Dict[int, List[str]]]:
     """
     Reads the coverage database and returns a dictionary which maps the filenames to the covered lines and their contexts.
-    :rtype: dict[str, dict[int, list[str]]]
     """
     try:
         # noinspection PyPackageRequirements,PyUnresolvedReferences
@@ -1227,7 +1210,7 @@ def read_coverage_data():
     return {filepath: data.contexts_by_lineno(filepath) for filepath in data.measured_files()}
 
 
-def read_patch_data(patch_file_path):
+def read_patch_data(patch_file_path: str):
     try:
         # noinspection PyPackageRequirements
         import whatthepatch
@@ -1242,12 +1225,12 @@ def read_patch_data(patch_file_path):
     }
 
 
-def add_mutations_by_file(mutations_by_file, filename, dict_synonyms, config):
-    """
-    :type mutations_by_file: dict[str, list[RelativeMutationID]]
-    :type filename: str
-    :type dict_synonyms: list[str]
-    """
+def add_mutations_by_file(
+    mutations_by_file: Dict[str, List[RelativeMutationID]],
+    filename: str,
+    dict_synonyms: List[str],
+    config: Optional[Config],
+):
     with open(filename) as f:
         source = f.read()
     context = Context(
@@ -1260,27 +1243,28 @@ def add_mutations_by_file(mutations_by_file, filename, dict_synonyms, config):
     try:
         mutations_by_file[filename] = list_mutations(context)
         from mutmut.cache import register_mutants
+
         register_mutants(mutations_by_file)
     except Exception as e:
-        raise RuntimeError('Failed while creating mutations for {}, for line "{}"'.format(context.filename, context.current_source_line)) from e
+        raise RuntimeError(
+            'Failed while creating mutations for {}, for line "{}"'.format(
+                context.filename, context.current_source_line
+            )
+        ) from e
 
 
-def python_source_files(path, tests_dirs, paths_to_exclude=None):
+def python_source_files(
+    path: str, tests_dirs: List[str], paths_to_exclude: Optional[List[str]] = None
+) -> Iterator[str]:
     """Attempt to guess where the python source files to mutate are and yield
     their paths
 
     :param path: path to a python source file or package directory
-    :type path: str
-
     :param tests_dirs: list of directory paths containing test files
         (we do not want to mutate these!)
-    :type tests_dirs: list[str]
-
     :param paths_to_exclude: list of UNIX filename patterns to exclude
-    :type paths_to_exclude: list[str]
 
     :return: generator listing the paths to the python source files to mutate
-    :rtype: Generator[str, None, None]
     """
     paths_to_exclude = paths_to_exclude or []
     if isdir(path):
@@ -1297,10 +1281,12 @@ def python_source_files(path, tests_dirs, paths_to_exclude=None):
         yield path
 
 
-def compute_exit_code(progress, exception=None, ci=False):
+def compute_exit_code(
+    progress: Progress, exception: Optional[Exception] = None, ci: bool = False
+) -> int:
     """Compute an exit code for mutmut mutation testing
 
-    The following exit codes are available for mutmut:
+    The following exit codes are available for mutmut (as documented for the CLI run command):
      * 0 if all mutants were killed (OK_KILLED)
      * 1 if a fatal error occurred
      * 2 if one or more mutants survived (BAD_SURVIVED)
@@ -1314,14 +1300,10 @@ def compute_exit_code(progress, exception=None, ci=False):
      1 for a fatal error or 0 for any other case.
 
     :param exception:
-    :type exception: Exception
     :param progress:
-    :type progress: Progress
     :param ci:
-    :type ci: bool
 
     :return: integer noting the exit code of the mutation tests.
-    :rtype: int
     """
     code = 0
     if exception is not None: