oct.mutation.engine Namespace Reference

Classes
class	MutantNotFoundError
class	Mutant
class	_Site
class	_SiteCollector

Functions
tuple[ast.Module, list[_Site]]	_collect_tree_and_sites (str source, str relpath)
list[Mutant]	enumerate_source (str source, str relpath)
list[Mutant]	enumerate_file (str|Path path, str|Path|None root=None)
str	relative_id (str|Path path, str|Path|None root)
str	apply_mutant (str source, str mutant_id, str relpath)

Detailed Description

Purpose
-------
Enumerate and apply deterministic source mutants over the pinned v1 operator set.

Responsibilities
----------------
- Derive every mutant of a module purely from its syntax tree, in source order.
- Give each mutant a stable ``relpath:line:col:op-code`` identity.
- Render a readable before/after preview for each mutant without touching disk.
- Apply exactly one named mutant to a source string and return the new text.

Diagnostics
-----------
Domain: OCT-MUTATION
Levels:
    L2 - lifecycle
    L3 - enumeration details
    L4 - deep tracing

Contracts
---------
- The same source text always yields the same mutants with the same ids.
- Enumeration is read-only; nothing in this module writes to the filesystem.
- A mutant never reproduces the original source, so no enumerated mutant is a
  guaranteed survivor by construction.
- ``SyntaxError`` propagates so callers report an unparsable target honestly.

Dependencies
------------
- ast (syntax tree, mutation, and source rendering)
- tokenize (declared source encodings)

Function Documentation

_collect_tree_and_sites()

tuple[ast.Module, list[_Site]] oct.mutation.engine._collect_tree_and_sites ( str source, str relpath )

protected

Return the parsed tree alongside the sites that edit it in place.

Definition at line 313 of file engine.py.

Here is the caller graph for this function:

apply_mutant()

str oct.mutation.engine.apply_mutant	(	str	source,
		str	mutant_id,
		str	relpath )

Return ``source`` with exactly the named mutant applied.

The result is re-rendered by :func:`ast.unparse`, so comments and original
formatting are not preserved. That is safe only because the runner writes
this text transiently and always restores the pristine bytes afterwards.

Definition at line 360 of file engine.py.

Here is the call graph for this function:

enumerate_file()

list[Mutant] oct.mutation.engine.enumerate_file	(	str | Path	path,
		str | Path | None	root = None )

Return every v1 mutant of one file, identified relative to ``root``.

Definition at line 336 of file engine.py.

Here is the call graph for this function:

enumerate_source()

list[Mutant] oct.mutation.engine.enumerate_source	(	str	source,
		str	relpath )

Return every v1 mutant of ``source`` in deterministic source order.

Definition at line 331 of file engine.py.

Here is the call graph for this function:

Here is the caller graph for this function:

relative_id()

str oct.mutation.engine.relative_id	(	str | Path	path,
		str | Path | None	root )

Return the forward-slash relative path used inside mutant ids.

Ids are anchored to ``root`` so they stay stable when the same tree is
checked out at a different absolute location; a target outside ``root``
falls back to its bare filename rather than leaking an absolute path.

Definition at line 344 of file engine.py.

Here is the caller graph for this function: