Byte report

byte_report

Byte-exact reporting on a payload already read from disk.

Pure, in-memory helpers: every function receives bytes or decoded text and returns a report. No file, network or process boundary is crossed here — the I/O belongs to the calling AXMTool.

The module implements lesson L4: an escape sequence present on disk is a run of ASCII characters (chr(92) + "u00e9" is six characters), not a single codepoint. Comparing the two requires looking at the bytes, never at a value that Python already decoded.

MAX_OCCURRENCES = 50 module-attribute

Upper bound on every occurrence list carried by a report.

MISMATCH_WINDOW = 40 module-attribute

Characters kept on each side of the first divergence.

ByteReport dataclass

Byte-exact verdict on a payload, with its supporting evidence.

Source code in packages/axm-edit/src/axm_edit/core/byte_report.py

@dataclass(frozen=True, slots=True)
class ByteReport:
    """Byte-exact verdict on a payload, with its supporting evidence."""

    sha256: str
    size: int
    encoding_ok: bool
    verdict: Verdict
    hint: str
    non_ascii_total: int = 0
    literal_escapes_total: int = 0
    mismatch: MismatchDetail | None = None
    non_ascii: list[NonAsciiOccurrence] = field(default_factory=list)
    literal_escapes: list[LiteralEscape] = field(default_factory=list)

LiteralEscape dataclass

An escape sequence present verbatim, as ASCII text, on disk.

Source code in packages/axm-edit/src/axm_edit/core/byte_report.py

@dataclass(frozen=True, slots=True)
class LiteralEscape:
    """An escape sequence present verbatim, as ASCII text, on disk."""

    offset: int
    sequence: str

MismatchDetail dataclass

Localised divergence between the expected and the actual content.

Source code in packages/axm-edit/src/axm_edit/core/byte_report.py

@dataclass(frozen=True, slots=True)
class MismatchDetail:
    """Localised divergence between the expected and the actual content."""

    first_diff_offset: int
    expected_repr: str
    actual_repr: str

NonAsciiOccurrence dataclass

A single non-ASCII character located in the decoded text.

Source code in packages/axm-edit/src/axm_edit/core/byte_report.py

@dataclass(frozen=True, slots=True)
class NonAsciiOccurrence:
    """A single non-ASCII character located in the decoded text."""

    line: int
    col: int
    char: str
    codepoint: str
    byte_offset: int

build_hint(verdict)

Return an actionable message for verdict (empty when ok).

Source code in packages/axm-edit/src/axm_edit/core/byte_report.py

def build_hint(verdict: Verdict) -> str:
    """Return an actionable message for ``verdict`` (empty when ``ok``)."""
    return _HINTS.get(verdict, "")

build_report(data, expected=None, expect_escaped=None)

Build the byte-exact report for data.

data is hashed as-is, decoded strictly to determine encoding_ok, then decoded tolerantly so a readable report can be produced even for undecodable bytes. No exception escapes this function.

Source code in packages/axm-edit/src/axm_edit/core/byte_report.py

def build_report(
    data: bytes,
    expected: str | None = None,
    expect_escaped: bool | None = None,
) -> ByteReport:
    """Build the byte-exact report for ``data``.

    ``data`` is hashed as-is, decoded strictly to determine ``encoding_ok``,
    then decoded tolerantly so a readable report can be produced even for
    undecodable bytes. No exception escapes this function.
    """
    encoding_ok = _is_utf8(data)
    text = data.decode("utf-8", errors="replace")
    non_ascii, non_ascii_total = _bounded(_iter_non_ascii(text), MAX_OCCURRENCES)
    escapes, escapes_total = _bounded(_iter_literal_escapes(text), MAX_OCCURRENCES)
    mismatch = None if expected is None else compare_expected(expected, text)
    verdict = decide_verdict(
        encoding_ok, mismatch, non_ascii_total, escapes_total, expect_escaped
    )
    return ByteReport(
        sha256=hashlib.sha256(data).hexdigest(),
        size=len(data),
        encoding_ok=encoding_ok,
        verdict=verdict,
        hint=build_hint(verdict),
        non_ascii_total=non_ascii_total,
        literal_escapes_total=escapes_total,
        mismatch=mismatch,
        non_ascii=non_ascii,
        literal_escapes=escapes,
    )

compare_expected(expected, actual)

Return the first divergence between two texts, None if equal.

Source code in packages/axm-edit/src/axm_edit/core/byte_report.py

def compare_expected(expected: str, actual: str) -> MismatchDetail | None:
    """Return the first divergence between two texts, ``None`` if equal."""
    offset = _first_difference(expected, actual)
    if offset is None:
        return None
    start = max(0, offset - MISMATCH_WINDOW)
    end = offset + MISMATCH_WINDOW
    return MismatchDetail(
        first_diff_offset=offset,
        expected_repr=ascii(expected[start:end]),
        actual_repr=ascii(actual[start:end]),
    )

decide_verdict(encoding_ok, mismatch, non_ascii_total, literal_escapes_total, expect_escaped=None)

Pick the verdict under a strict priority.

Decode error first, then divergence, then the escaping inconsistency, and ok otherwise. Without an explicit expect_escaped contract no escaping verdict is ever emitted.

Source code in packages/axm-edit/src/axm_edit/core/byte_report.py

def decide_verdict(
    encoding_ok: bool,
    mismatch: MismatchDetail | None,
    non_ascii_total: int,
    literal_escapes_total: int,
    expect_escaped: bool | None = None,
) -> Verdict:
    """Pick the verdict under a strict priority.

    Decode error first, then divergence, then the escaping inconsistency, and
    ``ok`` otherwise. Without an explicit ``expect_escaped`` contract no
    escaping verdict is ever emitted.
    """
    if not encoding_ok:
        return "decode_error"
    if mismatch is not None:
        return "mismatch"
    if expect_escaped is None:
        return "ok"
    if expect_escaped and non_ascii_total:
        return "literal_where_escaped_expected"
    if not expect_escaped and literal_escapes_total:
        return "escaped_where_literal_expected"
    return "ok"

scan_literal_escapes(text, limit=MAX_OCCURRENCES)

Locate escape sequences written as plain ASCII text on disk.

Only the numeric forms are reported (\xNN, \uNNNN, \UNNNNNNNN); each sequence is kept verbatim.

Source code in packages/axm-edit/src/axm_edit/core/byte_report.py

def scan_literal_escapes(
    text: str, limit: int = MAX_OCCURRENCES
) -> list[LiteralEscape]:
    """Locate escape sequences written as plain ASCII text on disk.

    Only the numeric forms are reported (``\\xNN``, ``\\uNNNN``,
    ``\\UNNNNNNNN``); each sequence is kept verbatim.
    """
    escapes, _ = _bounded(_iter_literal_escapes(text), limit)
    return escapes

scan_non_ascii(text, limit=MAX_OCCURRENCES)

Locate non-ASCII characters, 1-based line/col, UTF-8 byte offset.

At most limit occurrences are returned; the offset counts UTF-8 bytes from the start of the text, not characters.

Source code in packages/axm-edit/src/axm_edit/core/byte_report.py

def scan_non_ascii(text: str, limit: int = MAX_OCCURRENCES) -> list[NonAsciiOccurrence]:
    """Locate non-ASCII characters, 1-based line/col, UTF-8 byte offset.

    At most ``limit`` occurrences are returned; the offset counts UTF-8 bytes
    from the start of the text, not characters.
    """
    occurrences, _ = _bounded(_iter_non_ascii(text), limit)
    return occurrences