Skip to content

Rewrite

rewrite

Pure classification of a whole-file rewrite target.

The predicate below is the SINGLE source of truth shared by batch_edit_check (dry-run diagnostics) and batch_edit (apply path), so the two tools can never drift apart on what a valid rewrite target is. It is pure by construction: it takes already-observed facts (booleans and digests), never a Path, and touches no filesystem.

Diagnostic codes, evaluated in this fixed order:

  • rewrite_target_missing — the target does not exist.
  • rewrite_target_not_regular — the target exists but is not a regular file (symlink, directory, device, ...).
  • rewrite_checksum_stale — the target is a regular file but its digest no longer matches the one the caller read.

None means the target is valid for a rewrite.

classify_rewrite_target(*, exists, is_regular, actual_checksum, expected_checksum)

Classify an observed rewrite target against its expected digest.

Parameters:

Name Type Description Default
exists bool

Whether the target path exists.

 required
is_regular bool

Whether the target is a regular file (not a symlink, directory or other special file).

 required
actual_checksum str | None

Digest of the bytes currently on disk, or None when no digest could be observed.

 required
expected_checksum str

Digest the caller read before proposing the rewrite.

 required

Returns:

Type Description
str | None

None when the target is valid, otherwise the first matching
str | None

diagnostic code in the documented order.
Source code in packages/axm-edit/src/axm_edit/core/rewrite.py
Python
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def classify_rewrite_target(
    *,
    exists: bool,
    is_regular: bool,
    actual_checksum: str | None,
    expected_checksum: str,
) -> str | None:
    """Classify an observed rewrite target against its expected digest.

    Args:
        exists: Whether the target path exists.
        is_regular: Whether the target is a regular file (not a symlink,
            directory or other special file).
        actual_checksum: Digest of the bytes currently on disk, or ``None``
            when no digest could be observed.
        expected_checksum: Digest the caller read before proposing the rewrite.

    Returns:
        ``None`` when the target is valid, otherwise the first matching
        diagnostic code in the documented order.
    """
    if not exists:
        return REWRITE_TARGET_MISSING
    if not is_regular:
        return REWRITE_TARGET_NOT_REGULAR
    if actual_checksum != expected_checksum:
        return REWRITE_CHECKSUM_STALE
    return None

compute_checksum(data)

Return the lowercase 64-char sha256 hex digest of data.

Parameters:

Name Type Description Default
data bytes

The exact bytes to digest (no decoding, no normalisation).

 required

Returns:

Type Description
str

hashlib.sha256(data).hexdigest().
Source code in packages/axm-edit/src/axm_edit/core/rewrite.py
Python
31
32
33
34
35
36
37
38
39
40
def compute_checksum(data: bytes) -> str:
    """Return the lowercase 64-char sha256 hex digest of ``data``.

    Args:
        data: The exact bytes to digest (no decoding, no normalisation).

    Returns:
        ``hashlib.sha256(data).hexdigest()``.
    """
    return hashlib.sha256(data).hexdigest()