oct.mutation.sandbox Namespace Reference

Classes
class	MutationRefusal

Functions
Path	ensure_recoverable_target (str|Path path)
str	_repo_relative (Path resolved, Path repo_root)
None	_refuse_untracked (str relative, Path repo_root)
None	_refuse_dirty (str relative, Path repo_root)
tuple[bytes, str, str]	read_target (str|Path path)
Iterator[str]	mutated_target (str|Path path, str mutant_id, str relpath)

Detailed Description

Purpose
-------
Apply one mutant to a real file and guarantee the pristine bytes come back.

Responsibilities
----------------
- Refuse a target that git cannot restore before anything is written.
- Record the pristine bytes, write the mutant, and restore unconditionally.
- Preserve the target's declared source encoding when writing a mutant.

Diagnostics
-----------
Domain: OCT-MUTATION
Levels:
    L2 - lifecycle
    L3 - apply and restore details
    L4 - deep tracing

Contracts
---------
- Restoration runs in a ``finally``, so it also executes on ``KeyboardInterrupt``
  and on any exception raised inside the managed block.
- Restoration writes the recorded bytes back unconditionally, so it repairs a
  target that the managed block replaced rather than merely mutated.
- A refusal is raised before the first write, never after a partial one.
- This module makes no claim about processes it did not start: a child that
  outlives the managed block can still observe or rewrite the target, which is
  a named residual rather than a closed gap.

Dependencies
------------
- oct.core.git (repository discovery and working-tree state, read-only)
- oct.mutation.engine (mutant application)
- tokenize (declared source encodings)

Function Documentation

_refuse_dirty()

None oct.mutation.sandbox._refuse_dirty ( str relative, Path repo_root )

protected

Refuse a target that carries uncommitted working-tree or index changes.

Definition at line 115 of file sandbox.py.

_refuse_untracked()

None oct.mutation.sandbox._refuse_untracked ( str relative, Path repo_root )

protected

Refuse a target git does not track.

Definition at line 98 of file sandbox.py.

_repo_relative()

str oct.mutation.sandbox._repo_relative ( Path resolved, Path repo_root )

protected

Return the target's repo-relative posix path for git plumbing calls.

Definition at line 88 of file sandbox.py.

ensure_recoverable_target()

Path oct.mutation.sandbox.ensure_recoverable_target

(

str | Path

path

)

Return the repository root for a target git can restore, or refuse.

The refusal is the point of the function. Mutation rewrites a real file in
place, so the only honest precondition is that a committed copy exists to
fall back on if the process dies between the write and the restore. An
untracked or already-modified target has no such copy.

Definition at line 61 of file sandbox.py.

mutated_target()

Iterator[str] oct.mutation.sandbox.mutated_target	(	str | Path	path,
		str	mutant_id,
		str	relpath )

Write one mutant to ``path``, yield its text, and always restore.

The pristine bytes are captured before anything else happens and written
back in a ``finally``, so restoration survives an exception in the body, a
``KeyboardInterrupt``, and a body that replaced the file outright. The
restore is a plain unconditional write rather than a conditional repair:
comparing first would leave a window where a crash between the comparison
and the write loses the original.

Definition at line 145 of file sandbox.py.

Here is the call graph for this function:

read_target()

tuple[bytes, str, str] oct.mutation.sandbox.read_target

(

str | Path

path

)

Return a target's pristine bytes, decoded source, and declared encoding.

Definition at line 136 of file sandbox.py.

Here is the caller graph for this function: