Source code for iiisight.diagnostics

"""Structured diagnostics emitted while normalizing a IIIF document.

Tolerance is the core invariant: the normalizer never raises on a spec-imperfect
document. Instead it repairs what it can and records each repair as a
:class:`Diagnostic`. Severity encodes how lossy the repair was; even ``ERROR``
never raises.
"""

import enum
from dataclasses import dataclass




class Severity(enum.Enum):
    """How lossy a normalization repair was.

    Attributes:
        INFO: Spec-sanctioned normalization (e.g. a default the spec allows).
        WARNING: A deviation that was repaired (missing recommended field,
            coerced type) without losing information.
        ERROR: Something that could not be represented and had to be dropped or
            skipped; the model is lossy at ``path`` but still usable, and no
            exception was raised.
    """

    INFO = "info"
    WARNING = "warning"
    ERROR = "error"





@dataclass(frozen=True)
class Diagnostic:
    """A single repair the normalizer made to a document.

    Attributes:
        code: Stable machine-readable code, e.g. ``"coerced-language-map"``.
        severity: How lossy the repair was.
        path: JSON pointer to the offending node (``""`` for the root).
        message: Human-readable description of what was wrong.
        recovered: What was assumed, coerced, or skipped to recover, if anything.
    """

    code: str
    severity: Severity
    path: str
    message: str
    recovered: str | None = None