### Example Package Setup

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/how-tos/operators.rst.txt

Minimal setup.py for a Python package intended to provide custom operators. This file defines the package name and version.

```python
from setuptools import setup

setup(
    name='example',
    version='0.1.0',
)
```

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

### Navigate to Example Project Directory

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/reference/tests.rst.txt

Change the current directory to the example project for running 'adam' tests. This is a prerequisite for initializing a Cosmic Ray session.

```bash
cd tests/example_project
```

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

### Install Testing Dependencies

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/tests.html

Run this command to install the necessary dependencies for testing Cosmic Ray.

```bash
pip install -e .[dev,test]

```

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

### Operator Arguments and Examples

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.html

Information on how to define and use arguments and examples for operators.

```APIDOC
## Operator Arguments and Examples

### Description
This section details the structure for defining arguments and examples within operators.

### Classes
- `Argument`:
  - `name` (string): The name of the argument.
  - `description` (string): A description of the argument.
- `Example`:
  - `pre_mutation_code` (string): The code before mutation.
  - `post_mutation_code` (string): The code after mutation.
  - `occurrence` (integer): The occurrence number of the example.
  - `operator_args` (list): Arguments used for the operator in this example.

### Methods
- `Operator.arguments()`: Returns the arguments for the operator.
- `Operator.examples()`: Returns the examples for the operator.
```

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

### Baseline Output Example (Text)

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/intro/index.rst.txt

Example output from the 'baseline' command, indicating successful execution and reading of configuration.

```text
[07/23/21 10:00:20] INFO     INFO:root:Reading config from 'tutorial.toml'                                                                                                                                            config.py:103
                        INFO     INFO:cosmic_ray.commands.execute:Beginning execution                                                                                                                                     execute.py:45
```

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

### Install Cosmic Ray from source

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/intro/index.rst.txt

Install Cosmic Ray from its source code. This can be done in a standard or editable mode.

```bash
pip install .
```

```bash
pip install -e .
```

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

### Install Cosmic Ray from source

Source: https://cosmic-ray.readthedocs.io/en/latest/tutorials/intro/index.html

Install Cosmic Ray directly from its source code. Change to the directory containing setup.py before running.

```bash
pip install .

```

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

### Navigate to Example Project Directory

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/tests.html

Before running 'adam' tests, change to the 'test_project' directory.

```bash
cd tests/example_project

```

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

### Install Testing Dependencies

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/reference/tests.rst.txt

Install the necessary dependencies for testing Cosmic Ray. This command should be run from the project root.

```bash
pip install -e .[dev,test]
```

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

### Sample Project Test Suite (test_mod.py)

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/distributed/index.rst.txt

This is a simple test suite for the example module, used to verify mutations.

```python
from mod import add, subtract

def test_add():
    assert add(1, 1) == 2
    assert add(0, 0) == 0

def test_subtract():
    assert subtract(1, 1) == 0
    assert subtract(5, 3) == 2
```

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

### Install Cosmic Ray from source (editable mode)

Source: https://cosmic-ray.readthedocs.io/en/latest/tutorials/intro/index.html

Install Cosmic Ray from source in editable mode, allowing for direct code changes to affect the installed package.

```bash
pip install -e .

```

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

### Install Cosmic Ray with pip

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/intro/index.rst.txt

Use pip to install Cosmic Ray. It is generally recommended to do this within a virtual environment.

```bash
pip install cosmic-ray
```

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

### Sample Project Module (mod.py)

Source: https://cosmic-ray.readthedocs.io/en/latest/tutorials/distributed/index.html

Defines a simple function to be used in the mutation testing example.

```python
def func():
    return 1234

```

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

### Sample Project Module (mod.py)

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/distributed/index.rst.txt

This is a simple Python module used as an example for distributed mutation testing.

```python
def add(a, b):
    return a + b

def subtract(a, b):
    return a - b
```

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

### Configuration prompts and answers

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/intro/index.rst.txt

Example of interactive prompts and user answers when creating a new Cosmic Ray configuration file.

```text
[?] Top-level module path: mod.py
[?] Test execution timeout (seconds): 10
[?] Test command: python -m unittest test_mod.py
-- MENU: Distributor --
  (0) http
  (1) local
[?] Enter menu selection: 1   
```

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

### Example Class

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

Stores pre and post mutation code snippets for testing operator mutations.

```APIDOC
## class Example

Bases: `object`
A structure to store pre and post mutation operator code snippets, including optional specification of occurrence and operator args.
This is used for testing whether the pre-mutation code is correctly mutated to the post-mutation code at the given occurrence (if specified) and for the given operator args (if specified).

### Attributes
#### occurrence
_: int | None_

#### operator_args
_: dict | None_

#### post_mutation_code
_: str_

#### pre_mutation_code
_: str_
```

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

### Start HTTP Workers with cr-http-workers

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/distributed/index.rst.txt

Start multiple mutation testing workers by providing a configuration file and the path to the git repository to clone.

```bash
cr-http-workers config.toml .
```

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

### Example of Pending Mutations Output

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/intro/index.rst.txt

This is an example of the output from `cr-report --show-pending` before execution, showing detected mutations.

```text
[job-id] f168ef23dff24b75846a730858fe0111
mod.py core/NumberReplacer 0
[job-id] 929a563b613242b48dae0f2de74ad2af
mod.py core/NumberReplacer 1
total jobs: 2
no jobs completed
```

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

### Start an HTTP Worker

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/distributed/index.rst.txt

Command to start a Cosmic Ray HTTP worker. Ensure it runs in the same directory as your tests.

```bash
cd $ROOT
cosmic-ray --verbosity INFO http-worker --port 9876
```

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

### Start Workers with cr-http-workers

Source: https://cosmic-ray.readthedocs.io/en/latest/tutorials/distributed/index.html

Starts multiple Cosmic Ray workers using `cr-http-workers`. This tool clones a specified Git repository for each worker and starts a worker process within that clone.

```bash
cr-http-workers config.toml .

```

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

### Example of Executed Mutations Output

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/intro/index.rst.txt

This is an example of the output from `cr-report --show-pending` after execution, indicating that both mutations were killed.

```text
[job-id] f168ef23dff24b75846a730858fe0111
mod.py core/NumberReplacer 0
worker outcome: normal, test outcome: killed
[job-id] 929a563b613242b48dae0f2de74ad2af
mod.py core/NumberReplacer 1
worker outcome: normal, test outcome: killed
total jobs: 2
complete: 2 (100.00%)
surviving mutants: 0 (0.00%)
```

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

### Start First HTTP Worker

Source: https://cosmic-ray.readthedocs.io/en/latest/tutorials/distributed/index.html

Start the first Cosmic Ray HTTP worker in its own terminal, specifying a unique port.

```bash
cd $ROOT/worker1
cosmic-ray --verbosity INFO http-worker --port 9876
```

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

### Configure Distributor (TOML)

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/intro/index.rst.txt

Define how mutation jobs are distributed to workers. This example uses the default 'local' distributor for sequential execution.

```toml
"distributor": "local"
```

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

### Cosmic Ray Worker Output Example

Source: https://cosmic-ray.readthedocs.io/en/latest/tutorials/distributed/index.html

This is an example of the output you might see in the worker terminal during mutation testing, showing applied mutations and test executions.

```text
[05/16/21 11:31:10] INFO     INFO:cosmic_ray.mutating:Applying mutation: path=mod.py,                                mutating.py:111
                             op=<cosmic_ray.operators.number_replacer.NumberReplacer object at 0x10d2b9550>,
                             occurrence=1
                    INFO     INFO:cosmic_ray.testing:Running test (timeout=10.0): python -m unittest test_mod.py       testing.py:36
                    INFO     INFO:aiohttp.access:::1 [16/May/2021:09:31:10 +0000] "POST / HTTP/1.1" 200 899 "-"       web_log.py:206
                             "Python/3.7 aiohttp/3.7.4.post0"
                    INFO     INFO:cosmic_ray.mutating:Applying mutation: path=mod.py,                                mutating.py:111
                             op=<cosmic_ray.operators.number_replacer.NumberReplacer object at 0x10d4cdf60>,
                             occurrence=0
                    INFO     INFO:cosmic_ray.testing:Running test (timeout=10.0): python -m unittest test_mod.py       testing.py:36
[05/16/21 11:31:11] INFO     INFO:aiohttp.access:::1 [16/May/2021:09:31:10 +0000] "POST / HTTP/1.1" 200 899 "-"       web_log.py:206
                             "Python/3.7 aiohttp/3.7.4.post0"

```

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

### Implement mutate Method

Source: https://cosmic-ray.readthedocs.io/en/latest/how-tos/operators.html

Implement the `mutate` method to perform the actual mutation. This example increments the value of a numeric constant.

```python
def mutate(self, node, index):
    """Modify the numeric value on `node`. """

    assert isinstance(node, parso.python.tree.Number)

    val = eval(node.value) + 1
    return parso.python.tree.Number(' ' + str(val), node.start_pos)
```

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

### Start HTTP Worker

Source: https://cosmic-ray.readthedocs.io/en/latest/tutorials/distributed/index.html

Launches an HTTP worker process for Cosmic Ray. Ensure the worker runs in the same directory as your project's code.

```bash
cd $ROOT
cosmic-ray --verbosity INFO http-worker --port 9876

```

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

### ReplaceBinaryOperator_Pow_Mod

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

This operator replaces the power operator (**) with modulo (%). It provides methods to get examples of mutations and identify mutation positions.

```APIDOC
## ReplaceBinaryOperator_Pow_Mod

### Description
This class represents an operator that mutates by replacing the power operator (**) with modulo (%).

### Methods
#### `examples()`
*Class method*
Examples of the mutations that this operator can make. This is primarily for testing purposes, but it could also be used for documentation.

Each example takes the following arguments:
- `pre_mutation_code`: code prior to applying the mutation.
- `post_mutation_code`: code after (successfully) applying the mutation.
- `occurrence`: the index of the occurrence to which the mutation is applied (optional, default=0).
- `operator_args`: a dictionary of arguments to be **-unpacked to the operator (optional, default={}).

*Returns*: An iterable of Examples.

#### `mutate(_node_, _index_)`
Mutate a node in an operator-specific manner. Return the new, mutated node. Return `None` if the node has been deleted. Return `node` if there is no mutation at all for some reason.

*Parameters*:
- `_node_`: The AST node being mutated.
- `_index_`: The index of the occurrence to mutate.

*Returns*: The mutated node or None.

#### `mutation_positions(_node_)`
All positions where this operator can mutate `node`. An operator might be able to mutate a node in multiple ways, and this function should produce a position description for each of these mutations. Critically, if an operator can make multiple mutations to the same position, this should produce a position for each of these mutations (i.e. multiple identical positions).

*Parameters*:
- `_node_`: The AST node being mutated.

*Returns*:
An iterable of `((start-line, start-col), (stop-line, stop-col))` tuples describing the locations where this operator will mutate `node`.
```

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

### ZeroIterationForLoop Operator Example

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

Demonstrates the usage of the `ZeroIterationForLoop` operator, which modifies for-loops to execute zero times. This is primarily for testing and documentation.

```python
from cosmic_ray.testing import assert_mutation_is_valid
from cosmic_ray.operators.zero_iteration_for_loop import ZeroIterationForLoop


assert_mutation_is_valid(
    "for i in range(10):\n    pass",
    ZeroIterationForLoop(),
    "for i in range(10):\n    pass",
)

```

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

### ReplaceBinaryOperator_Pow_LShift

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

This operator replaces the power operator (**) with left shift (<<). It provides methods to get examples of mutations and identify mutation positions.

```APIDOC
## ReplaceBinaryOperator_Pow_LShift

### Description
This class represents an operator that mutates by replacing the power operator (**) with left shift (<<).

### Methods
#### `examples()`
*Class method*
Examples of the mutations that this operator can make. This is primarily for testing purposes, but it could also be used for documentation.

Each example takes the following arguments:
- `pre_mutation_code`: code prior to applying the mutation.
- `post_mutation_code`: code after (successfully) applying the mutation.
- `occurrence`: the index of the occurrence to which the mutation is applied (optional, default=0).
- `operator_args`: a dictionary of arguments to be **-unpacked to the operator (optional, default={}).

*Returns*: An iterable of Examples.

#### `mutate(_node_, _index_)`
Mutate a node in an operator-specific manner. Return the new, mutated node. Return `None` if the node has been deleted. Return `node` if there is no mutation at all for some reason.

*Parameters*:
- `_node_`: The AST node being mutated.
- `_index_`: The index of the occurrence to mutate.

*Returns*: The mutated node or None.

#### `mutation_positions(_node_)`
All positions where this operator can mutate `node`. An operator might be able to mutate a node in multiple ways, and this function should produce a position description for each of these mutations. Critically, if an operator can make multiple mutations to the same position, this should produce a position for each of these mutations (i.e. multiple identical positions).

*Parameters*:
- `_node_`: The AST node being mutated.

*Returns*:
An iterable of `((start-line, start-col), (stop-line, stop-col))` tuples describing the locations where this operator will mutate `node`.
```

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

### ReplaceBinaryOperator_Mul_Sub

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

This operator replaces multiplication (*) with subtraction (-). It provides methods to get examples of mutations, mutate a node, and find mutation positions.

```APIDOC
## ReplaceBinaryOperator_Mul_Sub

### Description
Replaces multiplication (*) with subtraction (-).

### Methods
- `examples()`: Class method to retrieve examples of mutations.
- `mutate(_node_, _index_)`: Mutates a node in an operator-specific manner.
- `mutation_positions(_node_)`: Returns all positions where this operator can mutate the given node.

### Parameters for `mutation_positions`
- **node** (AST node) - The AST node being mutated.

### Returns for `mutation_positions`
An iterable of `((start-line, start-col), (stop-line, stop-col))` tuples describing the mutation locations.
```

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

### Configure setup.py for Entry Point

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/how-tos/operators.rst.txt

Configure the setup.py file to register the custom operator provider as a plugin using the 'cosmic_ray.operator_providers' entry point.

```python
setup(
        . . .
        entry_points={
            'cosmic_ray.operator_providers': [
                'example = example.provider:Provider'
            ]
        })
```

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

### ReplaceComparisonOperator_Gt_Lt

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

This class represents an operator that replaces the '>' comparison operator with '<'. It provides methods to get mutation positions, examples of mutations, and to perform the mutation.

```APIDOC
## ReplaceComparisonOperator_Gt_Lt

### Description
This operator replaces the '>' comparison operator with '<'.

### Methods
- `mutation_positions(_node_)`: Returns all positions where this operator can mutate the given AST node.
- `mutate(_node_, _index_)`: Mutates the AST node at the specified index.
- `examples()`: Provides examples of mutations that this operator can make.
```

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

### Run tests to verify setup

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/intro/index.rst.txt

Execute the unit tests using Python's unittest module to ensure the test suite is working correctly before proceeding with mutation testing.

```bash
python -m unittest test_mod.py
```

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

### ReplaceBinaryOperator

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

Represents a mutation operator that replaces binary operators. It provides methods to get examples, mutate nodes, and find mutation positions.

```APIDOC
## ReplaceBinaryOperator

### Description
This class represents a mutation operator that replaces binary operators. It provides methods to get examples of mutations, mutate a given AST node, and identify all possible mutation positions within a node.

### Methods

- `_classmethod _examples()`: Returns examples of mutations that this operator can make.
- `mutate(_node_, _index_)`: Mutates a node in an operator-specific manner. Returns the mutated node, None if deleted, or the original node if no mutation occurs.
- `mutation_positions(_node_)`: Returns all positions where this operator can mutate the given node. Each position is described by a tuple of start and stop coordinates.
```

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

### ReplaceBinaryOperator_Sub_Div

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

Represents an operator that replaces a division operator. It provides methods to get mutation examples, mutate a node, and identify mutation positions.

```APIDOC
## ReplaceBinaryOperator_Sub_Div

### Description
Represents an operator that replaces a division operator. It provides methods to get mutation examples, mutate a node, and identify mutation positions.

### Methods

- `examples()`: Class method to generate examples of mutations.
- `mutate(_node_, _index_)`: Mutates a node at a specific index.
- `mutation_positions(_node_)`: Returns all positions where the operator can mutate the given node.

### Parameters for `mutation_positions`

- **node** (AST Node) - The AST node being mutated.

### Returns for `mutation_positions`

An iterable of `((start-line, start-col), (stop-line, stop-col))` tuples describing the locations where this operator will mutate `node`.
```

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

### Run HTTP Worker

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/cli.html

Start an HTTP worker process for the 'http' distributor. Listens for requests on a specified port or Unix domain socket.

```bash
cosmic-ray http-worker [OPTIONS]
```

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

### ReplaceBinaryOperator_Sub_BitOr

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

Represents an operator that replaces a bitwise OR operator. It provides methods to get mutation examples, mutate a node, and identify mutation positions.

```APIDOC
## ReplaceBinaryOperator_Sub_BitOr

### Description
Represents an operator that replaces a bitwise OR operator. It provides methods to get mutation examples, mutate a node, and identify mutation positions.

### Methods

- `examples()`: Class method to generate examples of mutations.
- `mutate(_node_, _index_)`: Mutates a node at a specific index.
- `mutation_positions(_node_)`: Returns all positions where the operator can mutate the given node.

### Parameters for `mutation_positions`

- **node** (AST Node) - The AST node being mutated.

### Returns for `mutation_positions`

An iterable of `((start-line, start-col), (stop-line, stop-col))` tuples describing the locations where this operator will mutate `node`.
```

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

### ReplaceBinaryOperator_Pow_FloorDiv

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

This operator replaces the power operator (**) with floor division (//). It provides methods to get examples of mutations and identify mutation positions.

```APIDOC
## ReplaceBinaryOperator_Pow_FloorDiv

### Description
This class represents an operator that mutates by replacing the power operator (**) with floor division (//).

### Methods
#### `examples()`
*Class method*
Examples of the mutations that this operator can make. This is primarily for testing purposes, but it could also be used for documentation.

Each example takes the following arguments:
- `pre_mutation_code`: code prior to applying the mutation.
- `post_mutation_code`: code after (successfully) applying the mutation.
- `occurrence`: the index of the occurrence to which the mutation is applied (optional, default=0).
- `operator_args`: a dictionary of arguments to be **-unpacked to the operator (optional, default={}).

*Returns*: An iterable of Examples.

#### `mutate(_node_, _index_)`
Mutate a node in an operator-specific manner. Return the new, mutated node. Return `None` if the node has been deleted. Return `node` if there is no mutation at all for some reason.

*Parameters*:
- `_node_`: The AST node being mutated.
- `_index_`: The index of the occurrence to mutate.

*Returns*: The mutated node or None.

#### `mutation_positions(_node_)`
All positions where this operator can mutate `node`. An operator might be able to mutate a node in multiple ways, and this function should produce a position description for each of these mutations. Critically, if an operator can make multiple mutations to the same position, this should produce a position for each of these mutations (i.e. multiple identical positions).

*Parameters*:
- `_node_`: The AST node being mutated.

*Returns*:
An iterable of `((start-line, start-col), (stop-line, stop-col))` tuples describing the locations where this operator will mutate `node`.
```

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

### ReplaceBinaryOperator_FloorDiv_BitOr

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

This operator replaces a floor division (//) with a bitwise OR (|) operation. It provides methods to get mutation examples and identify mutation positions.

```APIDOC
## ReplaceBinaryOperator_FloorDiv_BitOr

### Description
This class represents an operator that mutates a floor division (//) into a bitwise OR (|).

### Methods
#### `examples()`
Class method to provide examples of mutations.

#### `mutate(_node_, _index_)`
Mutates a node in an operator-specific manner. Returns the mutated node, None if deleted, or the original node if no mutation occurs.

#### `mutation_positions(_node_)`
Returns all positions where this operator can mutate the given node. Each position is described by start and stop line/column tuples.
```

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

### Implement mutation_positions Method

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/how-tos/operators.rst.txt

Implement the mutation_positions method to yield the start and end positions of nodes that the operator can mutate. This example targets numeric constants.

```python
def mutation_positions(self, node):
        if isinstance(node, parso.python.tree.Number):
            yield (node.start_pos, node.end_pos)
```

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

### ReplaceComparisonOperator_Gt_IsNot

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

This class represents an operator that replaces the '>' comparison operator with 'is not'. It provides methods to get mutation positions, examples of mutations, and to perform the mutation.

```APIDOC
## ReplaceComparisonOperator_Gt_IsNot

### Description
This operator replaces the '>' comparison operator with 'is not'.

### Methods
- `mutation_positions(_node_)`: Returns all positions where this operator can mutate the given AST node.
- `mutate(_node_, _index_)`: Mutates the AST node at the specified index.
- `examples()`: Provides examples of mutations that this operator can make.
```

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

### Badge Configuration Example

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/reference/badge.rst.txt

Configure the badge generation, including the label, format, and color thresholds. Thresholds define colors based on the failure percentage.

```ini
[cosmic-ray.badge]
label = "mutation"
format = "%.2f %%"

[cosmic-ray.badge.thresholds]
50  = 'red'
70  = 'orange'
100 = 'yellow'
101 = 'green'
```

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

### ReplaceComparisonOperator_Gt_Is

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

This class represents an operator that replaces the '>' comparison operator with 'is'. It provides methods to get mutation positions, examples of mutations, and to perform the mutation.

```APIDOC
## ReplaceComparisonOperator_Gt_Is

### Description
This operator replaces the '>' comparison operator with 'is'.

### Methods
- `mutation_positions(_node_)`: Returns all positions where this operator can mutate the given AST node.
- `mutate(_node_, _index_)`: Mutates the AST node at the specified index.
- `examples()`: Provides examples of mutations that this operator can make.
```

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

### ReplaceBinaryOperator_Sub_BitXor

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

Represents an operator that replaces a bitwise XOR operator. It provides methods to get mutation examples, mutate a node, and identify mutation positions.

```APIDOC
## ReplaceBinaryOperator_Sub_BitXor

### Description
Represents an operator that replaces a bitwise XOR operator. It provides methods to get mutation examples, mutate a node, and identify mutation positions.

### Methods

- `examples()`: Class method to generate examples of mutations.
- `mutate(_node_, _index_)`: Mutates a node at a specific index.
- `mutation_positions(_node_)`: Returns all positions where the operator can mutate the given node.

### Parameters for `mutation_positions`

- **node** (AST Node) - The AST node being mutated.

### Returns for `mutation_positions`

An iterable of `((start-line, start-col), (stop-line, stop-col))` tuples describing the locations where this operator will mutate `node`.
```

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

### cosmic_ray.commands.init.init

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.commands.html

Clears and initializes a work-db with new work items, replacing any existing data.

```APIDOC
## init(_module_paths_, _work_db: WorkDB_, _operator_cfgs_)

### Description
Clear and initialize a work-db with work items. Any existing data in the work-db will be cleared and replaced with entirely new work orders. In particular, this means that any results in the db are removed.

### Parameters
* **module_paths**: iterable of pathlib.Paths of modules to mutate.
* **work_db**: A WorkDB instance into which the work orders will be saved.
* **operator_cfgs**: A dict mapping operator names to parameterization dicts.

### Raises
* **TypeError**: Arguments provided for an operator are invalid.
```

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

### ReplaceBinaryOperator_Sub_BitAnd

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

Represents an operator that replaces a subtraction operator with a bitwise AND operator. It provides methods to get mutation examples, mutate a node, and identify mutation positions.

```APIDOC
## class _cosmic_ray.operators.binary_operator_replacement.ReplaceBinaryOperator_Sub_BitAnd

### Description
Bases: `Operator`

### Methods
#### classmethod _examples()
Examples of the mutations that this operator can make. This is primarily for testing purposes, but it could also be used for documentation.

Each example takes the following arguments:
pre_mutation_code: code prior to applying the mutation. post_mutation_code: code after (successfully) applying the mutation. occurrence: the index of the occurrence to which the mutation is applied (optional, default=0).
operator_args: a dictionary of arguments to be **-unpacked to the operator (optional, default={}).
Returns: An iterable of Examples.

#### mutate(_node_ , _index_)
Mutate a node in an operator-specific manner.
Return the new, mutated node. Return `None` if the node has been deleted. Return `node` if there is no mutation at all for some reason.

#### mutation_positions(_node_)
All positions where this operator can mutate `node`.
An operator might be able to mutate a node in multiple ways, and this function should produce a position description for each of these mutations. Critically, if an operator can make multiple mutations to the same position, this should produce a position for each of these mutations (i.e. multiple identical positions).

Parameters:
**node** – The AST node being mutated.

Returns:
An iterable of `((start-line, start-col), (stop-line, stop-col))` tuples describing the locations where this operator will mutate `node`.
```

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

### ReplaceBinaryOperator_Sub_Add

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

Represents an operator that replaces a subtraction operator with an addition operator. It provides methods to get mutation examples, mutate a node, and identify mutation positions.

```APIDOC
## class _cosmic_ray.operators.binary_operator_replacement.ReplaceBinaryOperator_Sub_Add

### Description
Bases: `Operator`

### Methods
#### classmethod _examples()
Examples of the mutations that this operator can make. This is primarily for testing purposes, but it could also be used for documentation.

Each example takes the following arguments:
pre_mutation_code: code prior to applying the mutation. post_mutation_code: code after (successfully) applying the mutation. occurrence: the index of the occurrence to which the mutation is applied (optional, default=0).
operator_args: a dictionary of arguments to be **-unpacked to the operator (optional, default={}).
Returns: An iterable of Examples.

#### mutate(_node_ , _index_)
Mutate a node in an operator-specific manner.
Return the new, mutated node. Return `None` if the node has been deleted. Return `node` if there is no mutation at all for some reason.

#### mutation_positions(_node_)
All positions where this operator can mutate `node`.
An operator might be able to mutate a node in multiple ways, and this function should produce a position description for each of these mutations. Critically, if an operator can make multiple mutations to the same position, this should produce a position for each of these mutations (i.e. multiple identical positions).

Parameters:
**node** – The AST node being mutated.

Returns:
An iterable of `((start-line, start-col), (stop-line, stop-col))` tuples describing the locations where this operator will mutate `node`.
```

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

### ReplaceBinaryOperator_Div_BitOr

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

This operator replaces the division operator with a bitwise OR operator. It provides methods to get mutation examples, mutate AST nodes, and find mutation positions.

```APIDOC
## ReplaceBinaryOperator_Div_BitOr

### Description
Replaces the division operator with a bitwise OR operator.

### Methods
- `_classmethod _examples()`: Returns examples of mutations.
- `mutate(_node_, _index_)`: Mutates a node.
- `mutation_positions(_node_)`: Returns all positions where this operator can mutate the node.
```

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

### Cosmic Ray configuration prompts

Source: https://cosmic-ray.readthedocs.io/en/latest/tutorials/intro/index.html

Example answers to the interactive prompts when creating a new Cosmic Ray configuration. This sets the module path, test timeout, and test command.

```text
[?] Top-level module path: mod.py
[?] Test execution timeout (seconds): 10
[?] Test command: python -m unittest test_mod.py
-- MENU: Distributor --
  (0) http
  (1) local
[?] Enter menu selection: 1

```

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

### ReplaceBinaryOperator_Div_BitAnd

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

This operator replaces the division operator with a bitwise AND operator. It provides methods to get mutation examples, mutate AST nodes, and find mutation positions.

```APIDOC
## ReplaceBinaryOperator_Div_BitAnd

### Description
Replaces the division operator with a bitwise AND operator.

### Methods
- `_classmethod _examples()`: Returns examples of mutations.
- `mutate(_node_, _index_)`: Mutates a node.
- `mutation_positions(_node_)`: Returns all positions where this operator can mutate the node.
```

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

### List Distributor Plugins

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/cli.html

List all available distributor plugins for Cosmic Ray.

```bash
cosmic-ray distributors [OPTIONS]
```

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

### ReplaceBinaryOperator_RShift_Sub

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

Represents an operator that replaces a right shift operator with a subtraction operator. It provides methods to get mutation examples, mutate a node, and identify mutation positions.

```APIDOC
## class _cosmic_ray.operators.binary_operator_replacement.ReplaceBinaryOperator_RShift_Sub

### Description
Bases: `Operator`

### Methods
#### classmethod _examples()
Examples of the mutations that this operator can make. This is primarily for testing purposes, but it could also be used for documentation.

Each example takes the following arguments:
pre_mutation_code: code prior to applying the mutation. post_mutation_code: code after (successfully) applying the mutation. occurrence: the index of the occurrence to which the mutation is applied (optional, default=0).
operator_args: a dictionary of arguments to be **-unpacked to the operator (optional, default={}).
Returns: An iterable of Examples.

#### mutate(_node_ , _index_)
Mutate a node in an operator-specific manner.
Return the new, mutated node. Return `None` if the node has been deleted. Return `node` if there is no mutation at all for some reason.

#### mutation_positions(_node_)
All positions where this operator can mutate `node`.
An operator might be able to mutate a node in multiple ways, and this function should produce a position description for each of these mutations. Critically, if an operator can make multiple mutations to the same position, this should produce a position for each of these mutations (i.e. multiple identical positions).

Parameters:
**node** – The AST node being mutated.

Returns:
An iterable of `((start-line, start-col), (stop-line, stop-col))` tuples describing the locations where this operator will mutate `node`.
```

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

### ReplaceBinaryOperator_RShift_BitAnd

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

This operator replaces the right shift (>>) operator with the bitwise AND (&) operator. It provides methods to get examples of mutations, perform the mutation on a node, and identify mutation positions.

```APIDOC
## ReplaceBinaryOperator_RShift_BitAnd

### Description
Replaces the right shift (>>) operator with the bitwise AND (&) operator.

### Methods
- `_classmethod _examples()`: Provides examples of mutations this operator can make.
- `mutate(_node_, _index_)`: Mutates a node in an operator-specific manner.
- `mutation_positions(_node_)`: Returns all positions where this operator can mutate the given node.

### Parameters for `mutation_positions`
- **node** (AST node): The AST node being mutated.

### Returns for `mutation_positions`
An iterable of `((start-line, start-col), (stop-line, stop-col))` tuples describing the mutation locations.
```

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

### cosmic-ray init

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/cli.html

Initialize a mutation testing session from a configuration. This primarily creates a session - a database of “work to be done” - which describes all of the mutations and test runs that need to be executed for a full mutation testing run. The configuration specifies the top-level module to mutate, the tests to run, and how to run them. This command doesn’t actually run any tests. Instead, it scans the modules-under-test and simply generates the work order which can be executed with other commands.

```APIDOC
## cosmic-ray init

Initialize a mutation testing session from a configuration. This primarily creates a session - a database of “work to be done” - which describes all of the mutations and test runs that need to be executed for a full mutation testing run. The configuration specifies the top-level module to mutate, the tests to run, and how to run them.
This command doesn’t actually run any tests. Instead, it scans the modules-under-test and simply generates the work order which can be executed with other commands.

### Usage
```
cosmic-ray init [OPTIONS] CONFIG_FILE SESSION_FILE
```

### Options
#### --force
    Re-initialize the session even if it already contains results

### Arguments
#### CONFIG_FILE
    Required argument
#### SESSION_FILE
    Required argument
```

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

### Initialize Git Repository for Workers

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/distributed/index.rst.txt

Use these bash commands to initialize a git repository from your existing code, which will be cloned by the workers.

```bash
cd $ROOT
git init
git add mod.py 
git add test_mod.py
git commit -a -m "initialized repo"
```

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

### ReplaceBinaryOperator_Div_BitXor

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.operators.html

This operator replaces the division operator with a bitwise XOR operator. It provides methods to get mutation examples, mutate AST nodes, and find mutation positions.

```APIDOC
## ReplaceBinaryOperator_Div_BitXor

### Description
Replaces the division operator with a bitwise XOR operator.

### Methods
- `_classmethod _examples()`: Returns examples of mutations.
- `mutate(_node_, _index_)`: Mutates a node.
- `mutation_positions(_node_)`: Returns all positions where this operator can mutate the node.
```

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

### Register Operator Provider in setup.py

Source: https://cosmic-ray.readthedocs.io/en/latest/how-tos/operators.html

Register your operator provider as a Cosmic Ray plugin by defining an entry point in your `setup.py` file.

```python
setup(
    . . .
    entry_points={
        'cosmic_ray.operator_providers': [
            'example = example.provider:Provider'
        ]
    })
```

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

### Run Local Release Script

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/reference/continuous_integration.rst.txt

Execute the local release script to manage version bumping and tagging. Use --help for available options like --dry-run or --from-ref.

```bash
tools/release.py patch
```

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

### Initialize Git Repository for Workers

Source: https://cosmic-ray.readthedocs.io/en/latest/tutorials/distributed/index.html

Prepares a Git repository for use with `cr-http-workers`. This involves initializing a new repository, adding relevant files, and committing them.

```bash
cd $ROOT
git init
git add mod.py
git add test_mod.py
git commit -a -m "initialized repo"

```

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

### cosmic_ray.commands.init

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/reference/api/cosmic_ray.commands.rst.txt

The init module is used for initializing new Cosmic Ray configurations.

```APIDOC
## Module: cosmic_ray.commands.init

This module provides utilities for initializing Cosmic Ray projects and configurations.

### Members

- **init()**: Function to create a new Cosmic Ray configuration file.
- **(other members)**: Additional functions and attributes within the init module.
```

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

### Cosmic Ray CLI Help

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/cli.html

Display help information for the main cosmic-ray command. Use --help for any command to get specific usage details.

```bash
cosmic-ray [OPTIONS] COMMAND [ARGS]...
```

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

### Run unittest suite

Source: https://cosmic-ray.readthedocs.io/en/latest/tutorials/intro/index.html

Execute the unittest suite for 'test_mod.py' using the Python unittest module. This verifies that the tests are correctly set up before mutation testing.

```bash
python -m unittest test_mod.py

```

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

### Initialize Mutation Testing Session

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/cli.html

Initialize a new mutation testing session from a configuration file. Creates a work order without running tests.

```bash
cosmic-ray init [OPTIONS] CONFIG_FILE SESSION_FILE
```

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

### Update and Report Progress

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.html

This example demonstrates how to update a progress message and report it. It uses a global variable for the message and a decorator to manage progress reporting.

```python
_progress_message = ""

def _update_foo_progress(i, n):
    global _progress_message
    _progress_message = "{i} of {n} complete".format(i=i, n=n)

def _report_foo_progress(stream):
    print(_progress_message, file=stream)

@reports_progress(_report_foo_progress)
def foo(n):
for i in range(n):
    _update_foo_progress(i, n)

# ...

signal.signal(signal.SIGINFO,
              lambda *args: report_progress())

```

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

### Baseline Test Suite (Bash)

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/intro/index.rst.txt

Run the baseline command to ensure the test suite passes on unmutated code before starting mutation testing. Use '--verbosity=INFO' for more details.

```bash
cosmic-ray --verbosity=INFO baseline tutorial.toml
```

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

### Start Second HTTP Worker

Source: https://cosmic-ray.readthedocs.io/en/latest/tutorials/distributed/index.html

Start the second Cosmic Ray HTTP worker in its own terminal, using a different port than the first worker.

```bash
cd $ROOT/worker2
cosmic-ray --verbosity INFO http-worker --port 9877
```

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

### Initialize and Execute Mutation Tests

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/distributed/index.rst.txt

Run the standard Cosmic Ray init and exec commands to distribute mutation tests to the running workers. Ensure this is run in a separate terminal.

```bash
cd $ROOT
cosmic-ray init config.toml session.sqlite
cosmic-ray exec config.toml session.sqlite
```

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

### Command Line Usage for Badge Generation

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/reference/badge.rst.txt

Use this command to generate a badge file. Specify a configuration file and the output badge file path, along with the session file.

```bash
cr-badge [--config <config_file>]  <badge_file> <session-file>
```

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

### Start HTTP worker on a specific port

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/tutorials/distributed/index.rst.txt

Start an HTTP worker process for Cosmic Ray on a given port. Ensure each worker uses a unique port.

```bash
cd $ROOT/worker1
cosmic-ray --verbosity INFO http-worker --port 9876
```

```bash
cd $ROOT/worker2
cosmic-ray --verbosity INFO http-worker --port 9877
```

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

### Create a New Configuration File

Source: https://cosmic-ray.readthedocs.io/en/latest/concepts.html

Use this command to generate a skeleton TOML configuration file for Cosmic Ray. You will need to edit this file to specify modules to mutate, test execution details, and other settings.

```bash
cosmic-ray new-config <config file>
```

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

### Navigate and test AST nodes with ASTQuery

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.ast.html

Use ASTQuery to navigate into any object and test attributes. At each step, you receive an ObjTest object. You can call any properties or functions of the base object for navigation. Conditional navigation is supported using IF and FI.

```python
ASTQuery(node).parent.match(Node, type=’node’)
ASTQuery(node).parent.children[2].get_next_sibling()
ASTQuery(node).match(attr=’value’).match(Class)
ASTQuery(node).match(Class, attr=’value’)
ASTQuery(node).IF.match(attr=’intermediate’).parent.FI
ASTQuery(node).ok
bool(ASTQuery(node))
```

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

### Cosmic Ray Configuration Example

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/concepts.rst.txt

This INI configuration is used to set up Cosmic Ray for running tests. It specifies module paths, timeouts, excluded modules, and the test command. The distributor name is set to 'local'.

```ini
[cosmic-ray]
module-path = "allele"
timeout = 10
excluded-modules = []
test-command = python -m unittest allele_tests
distributor.name = "local"
```

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

### Get AST from file path

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/cosmic_ray.ast.html

Use get_ast_from_path to get the AST for the code in a specified file. This function takes a pathlib.Path object to the file and returns the parso parse tree.

```python
cosmic_ray.ast.get_ast_from_path(_module_path : Path_)
```

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

### Initialize Cosmic Ray Session

Source: https://cosmic-ray.readthedocs.io/en/latest/tutorials/distributed/index.html

Initializes a Cosmic Ray session for distributed testing. Ensure you are in the project root directory.

```bash
cd $ROOT
cosmic-ray init config.toml session.sqlite

```

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

### MutationSpec

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/api/modules.html

Represents a specification for a mutation, including its starting position.

```APIDOC
## MutationSpec.start_pos

### Description
Specifies the starting position of a mutation within the source code.

### Type
(Type not specified in source)

### Usage
Access the `start_pos` attribute of a `MutationSpec` object.
```

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

### cr-http-workers

Source: https://cosmic-ray.readthedocs.io/en/latest/_sources/reference/cli.rst.txt

Starts an HTTP server to manage workers for distributed mutation testing.

```APIDOC
## cr-http-workers

### Description
Starts an HTTP server to manage workers for distributed mutation testing.

### Usage
Use `cr-http-workers --help` for detailed usage information.
```

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

### List Operator Plugins

Source: https://cosmic-ray.readthedocs.io/en/latest/reference/cli.html

List all available operator plugins for Cosmic Ray.

```bash
cosmic-ray operators [OPTIONS]
```