### Mutatest Execution Example Output

Source: https://github.com/evankepner/mutatest/blob/master/docs/index.rst

This example demonstrates the output generated when running mutation trials using Mutatest. It shows the process of detecting mutations, running trials, and provides diagnostic summaries including source location, test commands, mutation counts, and timing details.

```text
Running clean trial
2 mutation targets found in example/a.py AST.
1 mutation targets found in example/b.py AST.
Setting random.seed to: 314
Total sample space size: 2
10 exceeds sample space, using full sample: 2.

Starting individual mutation trials!
Current target location: a.py, LocIndex(ast_class='BinOp', lineno=6, col_offset=11, op_type=<class '_ast.Add'>)
Detected mutation at example/a.py: (6, 11)
Detected mutation at example/a.py: (6, 11)
Surviving mutation at example/a.py: (6, 11)
Break on survival: stopping further mutations at location.

Current target location: b.py, LocIndex(ast_class='CompareIs', lineno=6, col_offset=11, op_type=<class '_ast.Is'>)
Detected mutation at example/b.py: (6, 11)
Running clean trial

Mutatest diagnostic summary
===========================
 - Source location: /home/user/Github/mutatest/docs/api_tutorial/example
 - Test commands: ['pytest']
 - Mode: s
 - Excluded files: []
 - N locations input: 10
 - Random seed: 314

Random sample details
---------------------
 - Total locations mutated: 2
 - Total locations identified: 2
 - Location sample coverage: 100.00 %


Running time details
--------------------
 - Clean trial 1 run time: 0:00:00.348999
 - Clean trial 2 run time: 0:00:00.350213
 - Mutation trials total run time: 0:00:01.389095

Trial Summary Report:

Overall mutation trial summary
==============================
 - DETECTED: 3
 - SURVIVED: 1
 - TOTAL RUNS: 4
 - RUN DATETIME: 2019-10-17 16:57:08.645355

Detected mutations:

DETECTED
--------
 - example/a.py: (l: 6, c: 11) - mutation from <class '_ast.Add'> to <class '_ast.Sub'>
 - example/a.py: (l: 6, c: 11) - mutation from <class '_ast.Add'> to <class '_ast.Mod'>
 - example/b.py: (l: 6, c: 11) - mutation from <class '_ast.Is'> to <class '_ast.IsNot'>

Surviving mutations:

SURVIVED
--------
 - example/a.py: (l: 6, c: 11) - mutation from <class '_ast.Add'> to <class '_ast.Mult'>

```

--------------------------------

### Mutatest Command Line Interface Examples

Source: https://context7.com/evankepner/mutatest/llms.txt

Examples demonstrating the use of the mutatest command-line interface for running mutation tests. These commands cover basic usage, random seeding, skipping/selecting mutation categories, excluding files, different running modes, parallel execution, timeouts, coverage filtering, outputting results, and error handling.

```bash
# Basic mutation testing with pytest
mutatest -s mypackage/ -t "pytest"

# Run with a random seed for reproducibility, limited to 20 locations
mutatest -s mypackage/ -t "pytest" -n 20 -r 42

# Skip specific mutation categories (e.g., skip binary operations)
mutatest -s mypackage/ -t "pytest" -k bn bc

# Only test specific mutation categories
mutatest -s mypackage/ -t "pytest" -y cp cs  # Only comparison mutations

# Exclude specific files from mutation
mutatest -s mypackage/ -t "pytest" -e mypackage/__init__.py -e mypackage/_utils.py

# Run in different modes: f=full, s=break on survival, d=break on detection, sd=both
mutatest -s mypackage/ -t "pytest" -m sd

# Enable parallel execution (Python 3.8+)
mutatest -s mypackage/ -t "pytest" --parallel

# Set timeout factor for mutation trials
mutatest -s mypackage/ -t "pytest" --timeout_factor 10

# Ignore coverage filtering
mutatest -s mypackage/ -t "pytest" --nocov

# Output results to RST file
mutatest -s mypackage/ -t "pytest" -o results/mutation_report.rst

# Raise exception if survivors exceed threshold (useful for CI)
mutatest -s mypackage/ -t "pytest" -x 5

# Debug mode with verbose output
mutatest -s mypackage/ -t "pytest" --debug
```

--------------------------------

### Execute and Execute Mutant Code

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Shows how to directly execute the mutant code using `exec()`. This is useful for testing the effect of a specific mutation. The example assumes a pre-existing 'mutant' object.

```ipython3
# You can directly execute the mutant_code
# This result is with the mutated target being
# applied as Mult instead of Add in a.py

exec(mutant.mutant_code)
```

--------------------------------

### Example Mutatest Configuration (INI)

Source: https://github.com/evankepner/mutatest/blob/master/docs/commandline.rst

This snippet shows an example configuration for Mutatest using the INI file format. It demonstrates how to set parameters like skipping mutation types, excluding specific files, defining the mutation mode, setting a random seed, specifying test commands, and controlling debug and coverage options.

```ini
[mutatest]

skip = nc su ix
exclude =
    mutatest/__init__.py
    mutatest/_devtools.py
mode = sd
rseed = 567
testcmds = pytest -m 'not slow'
debug = no
nocov = no
```

--------------------------------

### Install mutatest using pip

Source: https://github.com/evankepner/mutatest/blob/master/README.rst

Installs the mutatest package from PyPI using pip. This is the standard method for installing Python packages.

```bash
$ pip install mutatest
```

--------------------------------

### Install Mutatest from source

Source: https://github.com/evankepner/mutatest/blob/master/docs/index.rst

Installs mutatest directly from its source code after cloning the repository. This method is useful for developers who want to work with the latest code or contribute to the project.

```bash
cd mutatest
pip install .
```

--------------------------------

### Python Slice Mutation Examples

Source: https://github.com/evankepner/mutatest/blob/master/docs/mutants.rst

Demonstrates various slice mutation techniques in Python. This includes swapping bounds, making bounds unbounded, and examples of Slice_UnboundedUpper, Slice_UnboundedLower, and Slice_Unbounded mutations.

```python
# source code
w = a[:2]
x = a[4:]

# mutation
w = a[2:]  # Slice_UnboundedUpper, upper is now unbounded and lower has a value
x = a[4:]

# mutation
w = a[:2]
x = a[:4]  # Slice_UnboundedLower, lower is now unbounded and upper has a value

# mutation
w = a[:2]
x = a[:]  # Slice_Unbounded, both upper and lower are unbounded
```

--------------------------------

### Add Genome to Group

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Demonstrates adding a `Genome` object back into the `GenomeGroup` using the `add_genome()` method. The example shows the `GenomeGroup` after the genome has been added.

```ipython3
# add a Genome to the group

ggrp.add_genome(genome_a)
ggrp
```

--------------------------------

### Specify Source Code Location

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Defines the path to the example source code directory. This is used to locate Python files and their corresponding tests for mutation analysis.

```python
src_loc = Path("example")
```

--------------------------------

### Define Source Location (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Sets the path to the directory containing the example Python source files. This path is used later to reference the files for testing and mutation.

```python
# This folder and included .py files are in docs/api_tutoral/

src_loc = Path("example")
```

--------------------------------

### Run mutatest with pytest

Source: https://github.com/evankepner/mutatest/blob/master/README.rst

Example of running mutatest from the command line. It specifies the source directory (-s), the test command (-t), and a random seed (-r) for reproducibility. The output shows the mutation trial process and a diagnostic summary.

```bash
$ mutatest -s example/ -t "pytest" -r 314
```

--------------------------------

### Pop Genome from Group

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Shows how to remove a specific `Genome` from the `GenomeGroup` using the `pop()` method, identified by its source file path. The example then displays the modified `GenomeGroup`.

```ipython3
# pop a Genome out of the Group

genome_a = ggrp.pop(Path("example/a.py"))
ggrp
```

--------------------------------

### Set Filter Codes on GenomeGroup

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Shows how to apply filter codes to all `Genome` objects within a `GenomeGroup` using `ggrp.set_filter`. The example then displays the `targets` property, which is filtered based on the applied codes.

```ipython3
# Setting filter codes on all Genomes
# in the group

ggrp.set_filter(("cs",))
ggrp.targets
```

--------------------------------

### Run Mutatest with Default Settings

Source: https://github.com/evankepner/mutatest/blob/master/docs/commandline.rst

Executes Mutatest with default settings, automatically detecting the Python package and running tests with pytest. This is the simplest way to start mutation testing.

```bash
$ mutatest
```

--------------------------------

### Run Mutatest with Coverage Optimization

Source: https://github.com/evankepner/mutatest/blob/master/docs/commandline.rst

Runs Mutatest with coverage optimization using 'pytest --cov=mypackage'. This command is useful when the pytest.ini file does not already specify coverage settings. It includes the same trial count, mode, seed, and output file as the previous example.

```bash
$ mutatest -n 5 -m sd -r 345 -o mutation_345.rst -t "pytest --cov=mypackage"
```

--------------------------------

### Run Mutation Trial and Check Status (Mult vs Add)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Illustrates running a single mutation trial using `run.create_mutation_run_trial()`. It shows how a mutation to `ast.Mult` instead of `ast.Add` might 'survive' the tests, meaning the tests still pass.

```ipython3
# Alternatively, use run to do a single trial
# and return the result

mutant_trial_result = run.create_mutation_run_trial(
    genome, mutation_target, ast.Mult, ["pytest"], max_runtime=5
)

# In this case the mutation would survive
# The test passes if the value is
# greater than 10.

mutant_trial_result.status
```

--------------------------------

### Mutatest Genome.mutate Method for Creating Mutants (Python)

Source: https://context7.com/evankepner/mutatest/llms.txt

Illustrates the usage of the `Genome.mutate` method in Python to create a `Mutant` object. This method allows for generating specific mutations at a given AST target. The example shows how to find a binary operation target, get possible mutations, create a mutant with a specific operation, and discusses writing the mutant to the `__pycache__`.

```python
import ast
from mutatest.api import Genome
from mutatest.transformers import get_mutations_for_target

# Create a genome and select a target
genome = Genome(source_file="example/a.py")
targets = genome.targets

# Find a BinOp target (e.g., + operator)
binop_target = None
for target in targets:
    if target.ast_class == "BinOp":
        binop_target = target
        break

if binop_target:
    # Get valid mutations for this target
    valid_mutations = get_mutations_for_target(binop_target)
    print(f"Target: {binop_target.op_type}")
    print(f"Valid mutations: {valid_mutations}")

    # Create a mutant (e.g., change + to -)
    mutation_op = ast.Sub  # Change addition to subtraction
    mutant = genome.mutate(
        target_idx=binop_target,
        mutation_op=mutation_op,
        write_cache=False  # Don't write to __pycache__ yet
    )

    print(f"Created mutant:")
    print(f"  Source file: {mutant.src_file}")
    print(f"  Cache file: {mutant.cfile}")
    print(f"  Original op: {mutant.src_idx.op_type}")
    print(f"  Mutation: {mutant.mutation}")

    # Write the mutant to __pycache__ when ready
    # mutant.write_cache()
```

--------------------------------

### Run Mutation Trial and Check Status (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Illustrates running a mutation trial with a division operation, which is expected to be detected due to test failure. It shows how to create the trial and retrieve its status.

```python
mutant_trial_result = run.create_mutation_run_trial(
    genome, mutation_target, ast.Div, ["pytest"], max_runtime=5
)

mutant_trial_result.status
```

--------------------------------

### Install mutatest using conda

Source: https://github.com/evankepner/mutatest/blob/master/README.rst

Installs the mutatest package from the conda-forge channel using conda. This is an alternative installation method for users managing environments with conda.

```bash
$ conda install -c conda-forge mutatest
```

--------------------------------

### Run Mutation Trial and Check Status (Div vs Add)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Demonstrates running a mutation trial with `ast.Div` and observing that this mutation is 'detected'. This implies the tests fail when division is used instead of addition, indicating a successful mutation detection.

```ipython3
# Using a different operation, such as Div
# will be a detected mutation
# since the test will fail.

mutant_trial_result = run.create_mutation_run_trial(
    genome, mutation_target, ast.Div, ["pytest"], max_runtime=5
)

mutant_trial_result.status
```

--------------------------------

### Create and Inspect GenomeGroup

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Shows how to create a `GenomeGroup` from a source directory and iterate through its key-value pairs, which represent file paths and their corresponding `Genome` objects. This demonstrates the basic structure of a `GenomeGroup`.

```ipython3
ggrp = GenomeGroup(src_loc)
```

```ipython3
# key-value pairs in the GenomeGroup are
# the path to the source file
# and the Genome object for that file

for k,v in ggrp.items():
    print(k, v)
```

--------------------------------

### Test Directory Restructuring and Installation Testing

Source: https://github.com/evankepner/mutatest/blob/master/CHANGELOG.rst

The `tests` directory has been moved to be within the `mutatest` package. This change facilitates testing the installation using `pytest --pyargs mutatest` and allows testing directly from local source files with `pytest`.

```python
# Moved the ``tests`` directory to be within the package of ``mutatest``.
# This enabled the installation to be tested with ``pytest --pyargs mutatest`` as well
# as ``pytest`` from local source files.
# Test dependencies are still installed with ``pip install .[tests]``.
```

--------------------------------

### Mutation Trial Execution

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Demonstrates how to execute mutation trials with different operations and observe the results (SURVIVED or DETECTED).

```APIDOC
## Mutation Trial Execution Examples

### Description
These examples show how to run mutation trials using the `create_mutation_run_trial` function. You can specify the genome, mutation target, the type of mutation operation (e.g., `ast.Mult`, `ast.Div`), the tests to run, and a maximum runtime.

### Method
`run.create_mutation_run_trial`

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Example 1: Multiplication mutation (may survive)
mutant_trial_result = run.create_mutation_run_trial(
    genome, mutation_target, ast.Mult, ["pytest"], max_runtime=5
)
print(mutant_trial_result.status)
```

```python
# Example 2: Division mutation (likely detected)
mutant_trial_result = run.create_mutation_run_trial(
    genome, mutation_target, ast.Div, ["pytest"], max_runtime=5
)
print(mutant_trial_result.status)
```

### Response
#### Success Response (200)
- **status** (string) - The status of the mutation trial, either 'SURVIVED' or 'DETECTED'.

#### Response Example
```json
{
  "status": "SURVIVED"
}
```

```json
{
  "status": "DETECTED"
}
```
```

--------------------------------

### Inspect and Execute a Mutant Object in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Details the properties of a Mutant object, including its source file, mutation details, and the generated mutant code. It also shows how to directly execute the mutant code and observe the result.

```python
# mutants have all of the properties
# needed to write mutated __pycache__
print(mutant)

# You can directly execute the mutant_code
# This result is with the mutated target being
# applied as Mult instead of Add in a.py
exec(mutant.mutant_code)
```

--------------------------------

### Write Mutated Cache and Run Trials in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Demonstrates how to write the changes made by a mutant object to the __pycache__ using the write_cache() method. It also mentions the alternative of using run for single-trial execution.

```python
# Mutants have a write_cache() method to apply
# the change to __pycache__
mutant.write_cache()

# Alternatively, use run to do a single trial
```

--------------------------------

### Initialize GenomeGroup from Source Location (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Shows how to initialize a GenomeGroup object from a given source location. This GenomeGroup will manage multiple Genomes found at that location.

```python
ggrp = GenomeGroup(src_loc)
```

--------------------------------

### Display Contents of test_ab.py (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Opens and prints the content of `test_ab.py`, the test script for `a.py` and `b.py`. Includes `test_add_five` which is intentionally broken.

```python
# Contents of test_ab.py example test file

open_print(src_loc / "test_ab.py")
```

--------------------------------

### Compare Mutations in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/mutants.rst

Mutates comparison operations like '==', '>=', '<', etc. The example shows changing a '>=' comparison to '<', '>', or '!='.

```python
# source code
x >= y

# mutations
x < y  # ast.Lt
x > y  # ast.Gt
x != y  # ast.NotEq
```

--------------------------------

### Display Contents of b.py (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Opens and prints the content of `b.py`, which contains the `is_match` function. Demonstrates AST representation of the `ast.Is` operation.

```python
# Contents of b.py example source file

open_print(src_loc / "b.py")
```

--------------------------------

### Compare Is Mutations in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/mutants.rst

Mutates identity comparison operations 'is' and 'is not'. The example demonstrates changing 'x is None' to 'x is not None'.

```python
# source code
x is None

# mutation
x is not None
```

--------------------------------

### Compare In Mutations in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/mutants.rst

Mutates membership comparison operations 'in' and 'not in'. The example shows changing an 'x in [...]' to 'x not in [...]'.

```python
# source code
x in [1, 2, 3, 4]

# mutation
x not in [1, 2, 3, 4]
```

--------------------------------

### BoolOp Mutations in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/mutants.rst

Mutates boolean operations 'and' and 'or'. The example demonstrates changing an 'if x and y:' condition to 'if x or y:'.

```python
# source code
if x and y:

# mutation
if x or y:
```

--------------------------------

### Accessing the Abstract Syntax Tree (AST) in Mutatest Genome (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Explains how to access the Abstract Syntax Tree (AST) of the source file through the `genome.ast` property. It shows how to inspect the root of the AST, its body, and the dictionary representation of specific AST nodes like function definitions. This is fundamental for understanding the code structure and generating mutation targets.

```python
genome.ast
```

```python
genome.ast.body
```

```python
genome.ast.body[1].__dict__
```

--------------------------------

### Inspect Mutation Targets with Genome in IPython

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Demonstrates how to access all potential mutation targets and covered mutation targets using the 'targets' and 'covered_targets' properties of a Genome object in an IPython environment. It also shows how to find the difference between these sets to identify uncovered targets.

```ipython3
genome.targets

genome.covered_targets

genome.targets - genome.covered_targets
```

--------------------------------

### BinOp Bitwise Shift Mutations in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/mutants.rst

Mutates bitwise shift operations like '<<' and '>>'. The example shows transforming a right shift '>>' into a left shift '<<'.

```python
# source code
x >> y

# mutation
x << y
```

--------------------------------

### GenomeGroup Management API

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Explains how to create, populate, and manage GenomeGroups, which allow for handling multiple Genomes collectively.

```APIDOC
## GenomeGroups API

### Description
The `GenomeGroup` class provides a convenient way to manage and interact with multiple `Genome` objects. It allows you to load genomes from a folder, add individual genomes, access shared properties like filters and coverage, and iterate over genomes, targets, and covered targets.

### Method
`GenomeGroup(...)`

### Endpoint
N/A (Class instantiation)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Initialization Example
```python
from pathlib import Path
from mutatest.api import GenomeGroup

src_loc = Path("path/to/your/genome/files")
ggrp = GenomeGroup(src_loc)
```

### Iterating Through Genomes

#### Description
You can iterate through the `GenomeGroup` to access each `Genome` object and its corresponding source file path.

#### Code Example
```python
for k, v in ggrp.items():
    print(k, v)
```

#### Output Example
```
example/a.py <mutatest.api.Genome object at 0x7f689cfc8c10>
example/b.py <mutatest.api.Genome object at 0x7f689cfc8f70>
```

### Accessing Targets and Covered Targets

#### Description
Retrieve `GenomeGroupTarget` objects, which contain information about the source path and location index (`LocIdx`) of mutations.

#### Code Example for Targets
```python
for t in ggrp.targets:
    print(t.source_path, t.loc_idx)
```

#### Output Example for Targets
```
example/b.py LocIndex(ast_class='CompareIs', lineno=6, col_offset=11, op_type=<class '_ast.Is'>, end_lineno=6, end_col_offset=17)
example/a.py LocIndex(ast_class='Compare', lineno=10, col_offset=11, op_type=<class '_ast.Gt'>, end_lineno=10, end_col_offset=16)
example/a.py LocIndex(ast_class='BinOp', lineno=6, col_offset=11, op_type=<class '_ast.Add'>, end_lineno=6, end_col_offset=16)
```

#### Code Example for Covered Targets (with coverage file set)
```python
ggrp.set_coverage = Path(".coverage")
for t in ggrp.covered_targets:
    print(t.source_path, t.loc_idx)
```

#### Output Example for Covered Targets
```
example/b.py LocIndex(ast_class='CompareIs', lineno=6, col_offset=11, op_type=<class '_ast.Is'>, end_lineno=6, end_col_offset=17)
example/a.py LocIndex(ast_class='BinOp', lineno=6, col_offset=11, op_type=<class '_ast.Add'>, end_lineno=6, end_col_offset=16)
```

### Setting Filters and Coverage

#### Description
Apply common filters or coverage files to all `Genomes` within the `GenomeGroup`.

#### Code Example for Setting Coverage
```python
ggrp.set_coverage = Path(".coverage")
```

#### Code Example for Setting Filter Codes
```python
ggrp.set_filter(("cs",))
print(ggrp.targets)
```

#### Output Example after Setting Filter
```json
{
  "GenomeGroupTarget(source_path=PosixPath('example/b.py'), loc_idx=LocIndex(ast_class='CompareIs', lineno=6, col_offset=11, op_type=<class '_ast.Is'>, end_lineno=6, end_col_offset=17))"
}
```

#### Verifying Filter Codes per Genome
```python
for k, v in ggrp.items():
    print(k, v.filter_codes)
```

#### Output Example Verifying Filters
```
example/a.py {'cs'}
example/b.py {'cs'}
```

### MutableMapping Operations

#### Description
`GenomeGroup` implements the `MutableMapping` interface, allowing standard dictionary-like operations.

#### Example: `values()`
```python
ggrp.values()
```

#### Result Example: `values()`
```
dict_values([<mutatest.api.Genome object at 0x7f689cfc8c10>, <mutatest.api.Genome object at 0x7f689cfc8f70>])
```

#### Example: `keys()`
```python
ggrp.keys()
```

#### Result Example: `keys()`
```
dict_keys([PosixPath('example/a.py'), PosixPath('example/b.py')])
```

#### Example: `pop()`
```python
genome_a = ggrp.pop(Path("example/a.py"))
print(ggrp)
```

#### Result Example: `pop()`
```json
{
  "PosixPath('example/b.py')": "<mutatest.api.Genome object at 0x7f689cfc8f70>"
}
```

#### Example: `add_genome()`
```python
ggrp.add_genome(genome_a)
print(ggrp)
```

#### Result Example: `add_genome()`
```json
{
  "PosixPath('example/b.py')": "<mutatest.api.Genome object at 0x7f689cfc8f70>",
  "PosixPath('example/a.py')": "<mutatest.api.Genome object at 0x7f689cfc8c10>"
}
```

### Adding Genomes from a Folder

#### Description
Use `add_folder` to populate the `GenomeGroup` from a directory, with an option to include test files.

#### Code Example (including test files)
```python
ggrp_with_tests = GenomeGroup()
ggrp_with_tests.add_folder(
    src_loc, ignore_test_files=False
)

for k, v in ggrp_with_tests.items():
    print(k, v)
```

#### Output Example (including test files)
```
example/a.py <mutatest.api.Genome object at 0x7f68a4044700>
example/test_ab.py <mutatest.api.Genome object at 0x7f689cfd7340>
example/b.py <mutatest.api.Genome object at 0x7f689cfd74f0>
```
```

--------------------------------

### BinOp Bitwise Comparison Mutations in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/mutants.rst

Mutates bitwise comparison operations like '&', '|', '^'. The example illustrates changing an '&' operation to '|' or '^'.

```python
# source code
x = a & y

# mutations
x = a | y  # ast.BitOr
x = a ^ y  # ast.BitXor
```

--------------------------------

### Run Mutation Trial and Check Status (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Demonstrates running a mutation trial with a multiplication operation and checking its survival status. This involves creating a mutation run trial and accessing its status attribute.

```python
mutant_trial_result = run.create_mutation_run_trial(
    genome, mutation_target, ast.Mult, ["pytest"], max_runtime=5
)

mutant_trial_result.status
```

--------------------------------

### Set Coverage and Access Covered Targets (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Shows how to set a coverage file for a GenomeGroup and then access the covered targets. This filters targets based on the provided coverage information.

```python
ggrp.set_coverage = Path(".coverage")

for t in ggrp.covered_targets:
    print(
        t.source_path, t.loc_idx
    )
```

--------------------------------

### List and Filter Mutation Target Categories in IPython

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Explains how to list all available mutation target categories and their corresponding codes using 'transformers.CATEGORIES'. It also demonstrates how to set category filters on a Genome object and the error handling for invalid codes. Finally, it shows how to reset the filters.

```ipython3
# All available categories are listed
# in transformers.CATEGORIES

print(*[f"Category:{k}, Code: {v}"
        for k,v in transformers.CATEGORIES.items()],
      sep="\n")


# If you attempt to set an invalid code a ValueError is raised
# and the valid codes are listed in the message

try:
    genome.filter_codes = ("asdf",)

except ValueError as e:
    print(e)


# Set the filter using an iterable of the two-letter codes

genome.filter_codes = ("bn",)


# Targets and covered targets will only show the filtered value

genome.targets

genome.covered_targets


# Reset the filter_codes to an empty set
genome.filter_codes = set()


# All target classes are now listed again

genome.targets
```

--------------------------------

### NameConstant Mutations in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/mutants.rst

Mutates named constants like True, False, and None. The example shows a variable assignment from True, implying it could be mutated to False or None.

```python
# source code
x = True
```

--------------------------------

### Access AST Properties of a Genome Object in IPython

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Shows how to access the Abstract Syntax Tree (AST) of a source file through the 'ast' property of a Genome object. It further demonstrates accessing the AST's body and the dictionary representation of specific function definitions within the body.

```ipython3
genome.ast

genome.ast.body

genome.ast.body[1].__dict__
```

--------------------------------

### If Statement Mutations in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/mutants.rst

Mutates 'if' statements to always evaluate to True or False. The example shows converting an 'if a > b:' statement to 'if True:' or 'if False:'.

```python
# source code
if a > b:   # If_Statement
    ...

# Mutations
if True:   # If_True
    ...

if False:  # If_False
    ...
```

--------------------------------

### BinOp Mutations in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/mutants.rst

Mutates binary operations such as addition, subtraction, division, etc. The example shows replacing a '+' operation with other binary operations like '/' or '-'.

```python
# source code
x = a + b

# mutations
x = a / b  # ast.Div
x = a - b  # ast.Sub
```

--------------------------------

### Create a Mutation with Genome.mutate() in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Explains how to create a mutation by specifying a target location and a new AST operation. It shows the successful creation of a mutant object and the expected output when attempting an invalid mutation.

```python
# Set the Genome back to example a
# filter to only the BinOp targets
gnome.source_file = src_loc / "a.py"
gnome.filter_codes = ("bn",)

# there is only one Binop target
mutation_target = list(genome.targets)[0]
print(mutation_target)

# The mutate() method applies a mutation operation
# and returns a mutant
mutant = genome.mutate(mutation_target, ast.Mult)

# applying an invalid mutation
# raises a MutationException
try:
    genome.mutate(mutation_target, ast.IsNot)
    
except MutationException as e:
    print(e)
```

--------------------------------

### Import Mutatest API Components (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Imports necessary modules and classes from the mutatest library for API usage. This includes core components like run, transformers, Genome, GenomeGroup, and filters.

```python
import ast

from pathlib import Path

from mutatest import run
from mutatest import transformers
from mutatest.api import Genome, GenomeGroup, MutationException
from mutatest.filters import CoverageFilter, CategoryCodeFilter
```

--------------------------------

### Invert Filtering with Genome Targets and Source File

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Demonstrates how to invert the filtering logic for genome targets and source files. This is useful for selecting elements that do NOT match certain criteria.

```python
cov_filter.filter(
    genome.targets, genome.source_file,
    invert=True
)
```

--------------------------------

### Index Mutations in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/mutants.rst

Mutates index access for iterables, such as changing positive, negative, or zero indices. The example shows various mutations for indices like a[10], a[-4], and a[0].

```python
# source code
x = [a[10], a[-4], a[0]]

# mutations
x = [a[-1], a[-4], a[0]]  # a[10] mutated to Index_NumNeg
x = [a[10], a[0], a[0]]  # a[-4] mutated to Index_NumZero
x = [a[10], a[1], a[0]]  # a[-4] mutated to Index_NumPos
x = [a[10], a[-4], a[1]]  # a[0] mutated to Index_NumPos
```

--------------------------------

### Run Clean Trial (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Executes a 'clean trial' of the test commands using `mutatest.run.clean_trial`. This generates a `.coverage` file essential for the Genome and resets the `__pycache__`.

```python
# The return value of clean_trial is the time to run
# this is used in reporting from the CLI

run.clean_trial(
    src_loc, test_cmds=["pytest", "--cov=example"]
)
```

--------------------------------

### Filtering Targets with Category Code Filter

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Demonstrates how to use the CategoryCodeFilter to filter a set of targets based on the configured codes. It also shows how to invert the filter to select targets that do not match the criteria.

```python
# Filter a set of targets based on codes

catcode_filter.filter(genome.targets)
```

```python
# Optionally, invert the filter

catcode_filter.filter(
    genome.targets, invert=True
)
```

--------------------------------

### Access GenomeGroup Targets

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Demonstrates how to access the mutation targets within a `GenomeGroup`. It iterates through `ggrp.targets` and prints the source path and location index (`LocIndex`) for each target, showing the specific locations in the code where mutations can be applied.

```ipython3
# targets, and covered_targets produce
# GenomeGroupTarget objects that have
# attributes for the source path and
# LocIdx for the target

for t in ggrp.targets:
    print(
        t.source_path, t.loc_idx
    )
```

--------------------------------

### Specify Custom Test Commands

Source: https://github.com/evankepner/mutatest/blob/master/docs/commandline.rst

Allows users to provide custom arguments for the test runner. This example shows how to exclude tests marked with 'pytest.mark.slow' using the --testcmds argument.

```bash
$ mutatest --testcmds "pytest -m 'not slow'"
$ mutatest -t "pytest -m 'not slow'"
```

--------------------------------

### Filter Targets with CoverageFilter in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Demonstrates how to use the CoverageFilter class to filter mutation targets based on coverage information from a specified '.coverage' file. It shows how to instantiate the filter and use its 'filter' method with genome targets and source file path.

```python
from pathlib import Path
from mutatest.filters import CoverageFilter

cov_filter = CoverageFilter(coverage_file=Path(".coverage"))

# Use the filter method to filter targets based on
# a given source file.

cov_filter.filter(
    genome.targets, genome.source_file
)
```

--------------------------------

### Configuration Settings in setup.cfg

Source: https://github.com/evankepner/mutatest/blob/master/CHANGELOG.rst

Adds support for specifying Mutatest settings within the `setup.cfg` file. Users can now configure the tool using either `[mutatest]` or `[tool:mutatest]` sections, in addition to the existing `mutatest.ini` file.

```ini
; Example setup.cfg configuration

[mutatest]
; your settings here

[tool:mutatest]
; your settings here
```

--------------------------------

### Explore Mutation Categories and Transformers in Python

Source: https://context7.com/evankepner/mutatest/llms.txt

The transformers module provides definitions for mutation operations and utilities for AST manipulation. It includes a dictionary of available mutation categories (e.g., BinOp, Compare), functions to get compatible operation sets for mutations, and utilities to generate mutations for a given target. It also defines the LocIndex for representing mutation locations.

```python
from mutatest.transformers import (
    CATEGORIES,
    LocIndex,
    MutateAST,
    get_compatible_operation_sets,
    get_mutations_for_target
)

# View all mutation categories
print("Available mutation categories:")
for name, code in CATEGORIES.items():
    print(f"  {code}: {name}")

# Output:
#   aa: AugAssign      (+=, -=, *=, /=)
#   bn: BinOp          (+, -, *, /, %, //, **)
#   bc: BinOpBC        (&, |, ^)
#   bs: BinOpBS        (<<, >>)
#   bl: BoolOp         (and, or)
#   cp: Compare        (==, !=, <, <=, >, >=)
#   cn: CompareIn      (in, not in)
#   cs: CompareIs      (is, is not)
#   if: If             (True, False)
#   ix: Index          (i[0], i[1], i[-1])
#   nc: NameConstant   (True, False, None)
#   su: SliceUS        (x[1:] <-> x[:1])

# Get detailed operation sets
for opset in get_compatible_operation_sets():
    print(f"\n{opset.name} ({opset.category}):")
    print(f"  Description: {opset.desc}")
    print(f"  Operations: {opset.operations}")

# Create a LocIndex manually
loc = LocIndex(
    ast_class="BinOp",
    lineno=10,
    col_offset=15,
    op_type=type(None)  # Placeholder
)
```

--------------------------------

### Write Mutant Cache

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Demonstrates the use of the `write_cache()` method on a mutant object. This method applies the mutation to the __pycache__ directory, allowing for faster subsequent executions.

```ipython3
# Mutants have a write_cache() method to apply
# the change to __pycache__

mutant.write_cache()
```

--------------------------------

### Display Contents of a.py (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Opens and prints the content of `a.py`, which contains two functions: `add_five` and `greater_than`. Demonstrates AST representation of operations like `ast.Add` and `ast.Gt`.

```python
# Contents of a.py example source file
open_print(src_loc / "a.py")
```

--------------------------------

### List Files in Source Directory (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Prints the names of all files within the specified source directory. This helps in verifying the presence of the source and test files.

```python
print(*[i for i in src_loc.iterdir()
        if i.is_file()], sep="\n")
```

--------------------------------

### Initialize Genome with Source File (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Initializes a `Genome` object, representing a source code file. The `Genome` stores the AST, source file path, coverage file, and filter codes. By default, it uses the `.coverage` file.

```python
# Initialize with the source file location
# By default, the ".coverage" file is set
# for the coverage_file property

genome = Genome(src_loc / "a.py")
```

--------------------------------

### Check for .coverage File (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Verifies the existence of the `.coverage` file generated by the `clean_trial` method. This file is used by the `Genome` to determine code coverage.

```python
Path(".coverage").exists()
```

--------------------------------

### Using Custom Coverage Filters in Mutatest (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Demonstrates the use of `CoverageFilter` for advanced filtering of mutation targets. It shows how to instantiate a `CoverageFilter` with a coverage file path and use its `filter` method to include or exclude targets based on code coverage. This provides fine-grained control over which mutation targets are considered.

```python
cov_filter = CoverageFilter(coverage_file=Path(".coverage"))
```

```python
# Use the filter method to filter targets based on
# a given source file. 

cov_filter.filter(
    genome.targets, genome.source_file
)
```

```python
# You can invert the filtering as well

cov_filter.filter(
    genome.targets, genome.source_file,
    invert=True
)
```

--------------------------------

### Change Genome Source File and Inspect Targets in Python

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Demonstrates changing the source file of a Genome object and observing the effects on its targets and covered targets. This highlights how resetting the source file impacts the genome's internal state.

```python
genome.source_file = src_loc / "b.py"

print(genome.targets)
print(genome.covered_targets)
```

--------------------------------

### Display Mutatest help information

Source: https://github.com/evankepner/mutatest/blob/master/docs/index.rst

Shows the help message for the mutatest command-line tool, listing all available arguments, options, and their descriptions. This is useful for understanding the tool's capabilities and configuration.

```bash
mutatest --help
```

--------------------------------

### Iterate Through GenomeGroup Items (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Demonstrates iterating through the key-value pairs of a GenomeGroup. The keys are file paths and the values are Genome objects.

```python
for k,v in ggrp.items():
    print(k, v)
```

--------------------------------

### Category Code Filter Initialization and Validation

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.rst

Shows how to instantiate a CategoryCodeFilter with specific codes and how to access the valid codes and categories it supports. This filter helps in selecting mutations based on AST node types.

```python
# Instantiate using a set of codes
# or add them later

catcode_filter = CategoryCodeFilter(codes=("bn",))
```

```python
# Valid codes provide all potential values

catcode_filter.valid_codes
```

```python
# Valid categories are also available

catcode_filter.valid_categories
```

--------------------------------

### Listing and Applying Category Filters in Mutatest (Python)

Source: https://github.com/evankepner/mutatest/blob/master/docs/api_tutorial/api_tutorial.ipynb

Shows how to list available mutation target category codes using `transformers.CATEGORIES` and how to apply these filters to a Mutatest Genome object using the `filter_codes` property. It also demonstrates error handling for invalid codes and how to reset the filters. This allows users to focus mutations on specific AST node types.

```python
# All available categories are listed
# in transformers.CATEGORIES

print(*[f"Category:{k}, Code: {v}"
        for k,v in transformers.CATEGORIES.items()],
      sep="\n")
```

```python
# If you attempt to set an invalid code a ValueError is raised
# and the valid codes are listed in the message

try:
    genome.filter_codes = ("asdf",)
    
except ValueError as e:
    print(e)
```

```python
# Set the filter using an iterable of the two-letter codes

gnome.filter_codes = ("bn",)
```

```python
# Targets and covered targets will only show the filtered value

gnome.targets
```

```python
genome.covered_targets
```

```python
# Reset the filter_codes to an empty set
gnome.filter_codes = set()
```

```python
# All target classes are now listed again

gnome.targets
```