claims-cli 0.6.0__py3-none-any.whl

claims/__init__.py

@@ -0,0 +1,132 @@
+"""One contract for verifying declared evidence assertions against pinned artifacts.
+
+A quotation in a manuscript and a number in a results file are the same kind of object: a
+typed value asserted to be extractable from a pinned artifact. This package verifies that
+assertion -- and nothing beyond it. Whether the evidence *supports* the sentence citing it is
+a question about entailment, addressed elsewhere with model-based methods.
+
+    from claims import load, verify
+    from claims.policy import PUBLICATION
+
+    report = verify(load("repro.yaml"))       # facts
+    verdict = PUBLICATION.assess(report)      # judgment
+
+Facts and judgment are separate calls because a missing optional citation is acceptable in a
+draft and not in a submission, and one project's standard should not be everyone's.
+
+Nothing here prints, exits, or reads global state.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from claims.exceptions import (
+    ArtifactMissingError,
+    ArtifactUnreadableError,
+    BackendUnavailableError,
+    DigestMismatchError,
+    ManifestError,
+    ReproError,
+    UnknownEvidenceKindError,
+)
+from claims.manifest import DEFAULT_NAME, find, load
+from claims.models import (
+    SCHEMA_VERSION,
+    ArtifactRef,
+    ArtifactState,
+    Availability,
+    Claim,
+    ClaimAssessment,
+    ComparisonMode,
+    ComparisonStatus,
+    Decision,
+    Digest,
+    Evidence,
+    ExecutionStatus,
+    ExtractionStatus,
+    Manifest,
+    MetricEvidence,
+    Outcome,
+    QuoteEvidence,
+    Reason,
+    TableCellEvidence,
+    Validity,
+    VerificationReport,
+    Warning_,
+)
+from claims.policy import EXPLORATORY, PROFILES, PUBLICATION, STRICT, Assessment, Policy, Severity
+from claims.renderers import to_sarif
+from claims.resolve import Resolution, read_table, resolve, resolve_pointer, sniff_delimiter
+from claims.toolchain import ALONE
+from claims.verify import (
+    DEFAULT_BACKENDS,
+    Backend,
+    MetricBackend,
+    QuoteBackend,
+    TableBackend,
+    ValueBackend,
+    verify,
+)
+
+# This package's own version, `claims-cli`'s, whatever else is installed: what `claims
+# --version` prints and what a SARIF log names as its driver's version.
+try:
+    __version__ = _version(ALONE)
+except PackageNotFoundError:  # a source tree with nothing installed
+    __version__ = "0+unknown"
+
+__all__ = [
+    "DEFAULT_BACKENDS",
+    "DEFAULT_NAME",
+    "EXPLORATORY",
+    "PROFILES",
+    "PUBLICATION",
+    "SCHEMA_VERSION",
+    "STRICT",
+    "ArtifactMissingError",
+    "ArtifactRef",
+    "ArtifactState",
+    "ArtifactUnreadableError",
+    "Assessment",
+    "Availability",
+    "Backend",
+    "BackendUnavailableError",
+    "Claim",
+    "ClaimAssessment",
+    "ComparisonMode",
+    "ComparisonStatus",
+    "Decision",
+    "Digest",
+    "DigestMismatchError",
+    "Evidence",
+    "ExecutionStatus",
+    "ExtractionStatus",
+    "Manifest",
+    "ManifestError",
+    "MetricBackend",
+    "MetricEvidence",
+    "Outcome",
+    "Policy",
+    "QuoteBackend",
+    "QuoteEvidence",
+    "Reason",
+    "ReproError",
+    "Resolution",
+    "Severity",
+    "TableBackend",
+    "TableCellEvidence",
+    "UnknownEvidenceKindError",
+    "Validity",
+    "ValueBackend",
+    "VerificationReport",
+    "Warning_",
+    "__version__",
+    "find",
+    "load",
+    "read_table",
+    "resolve",
+    "resolve_pointer",
+    "sniff_delimiter",
+    "to_sarif",
+    "verify",
+]

claims/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m claims`, the same as the `claims` command."""
+
+from claims.cli import main
+
+raise SystemExit(main())

claims/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""One module per artifact format.
+
+Each adapter translates a locator into the addressing its format already has, and every
+one returns the same `Found` contract. Adding a format is a new module and a registry
+entry, not an edit to a switchboard.
+"""

claims/adapters/array.py

@@ -0,0 +1,212 @@
+"""Arrays, addressed by array name and index: NumPy `.npy` and `.npz`, HDF5, and NetCDF.
+
+An HDF5 or NetCDF file holds many arrays under paths, as an `.npz` holds them under names, so
+the locator is the same: `array` is the dataset's path and `index` the element. Each reader is
+an optional extra (`reproducible-science[arrays]`, `[hdf5]`, `[netcdf]`), and a missing one is
+`unchecked` with the extra named.
+
+NetCDF is read through `netCDF4` rather than as the HDF5 file a NetCDF-4 file also is. A
+NetCDF variable is often stored packed -- integers with a `scale_factor` and an `add_offset`
+-- and its fill value marks an element that holds nothing. Read as plain HDF5, the packed
+integer would be compared with the manuscript and the fill value would be a number. The value
+of a NetCDF variable is the one a NetCDF reader reports, unpacked, and a filled element is
+absent.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+from claims.adapters.base import Found, Resolution, _no, _ok
+from claims.exceptions import ArtifactUnreadableError, BackendUnavailableError
+from claims.models import (
+    ArrayLocator,
+)
+from claims.toolchain import DISTRIBUTION
+
+try:  # optional: `pip install "reproducible-science[arrays]"`
+    import numpy
+except ImportError:  # pragma: no cover - exercised by the extras matrix, not the suite
+    numpy = None
+
+try:  # optional: `pip install "reproducible-science[hdf5]"`
+    import h5py
+except ImportError:  # pragma: no cover
+    h5py = None
+
+try:  # optional: `pip install "reproducible-science[netcdf]"`
+    import netCDF4
+except ImportError:  # pragma: no cover
+    netCDF4 = None
+
+# ----------------------------------------------------------------------------------- arrays
+
+_NUMPY_SUFFIXES = {".npy", ".npz"}
+_HDF5_SUFFIXES = {".h5", ".hdf5"}
+_NETCDF_SUFFIXES = {".nc"}
+_ARRAY_SUFFIXES = _NUMPY_SUFFIXES | _HDF5_SUFFIXES | _NETCDF_SUFFIXES
+
+
+def _resolve_array(locator: ArrayLocator, path: pathlib.Path) -> Found:
+    suffix = path.suffix.lower()
+    if suffix not in _ARRAY_SUFFIXES:
+        return _no(
+            Resolution.FORMAT_UNSUPPORTED,
+            f"an array locator addresses .npy, .npz, HDF5 or NetCDF; {path.name} is {path.suffix}",
+        )
+    if suffix in _HDF5_SUFFIXES:
+        return _resolve_hdf5(locator, path)
+    if suffix in _NETCDF_SUFFIXES:
+        return _resolve_netcdf(locator, path)
+    if numpy is None:
+        raise BackendUnavailableError(
+            "array", f'numpy is not installed -- pip install "{DISTRIBUTION}[arrays]"'
+        )
+
+    try:
+        loaded = numpy.load(path, allow_pickle=False)
+    except (OSError, ValueError) as e:
+        raise ArtifactUnreadableError(path, str(e)) from e
+
+    if suffix == ".npz":
+        if locator.array is None:
+            return _no(Resolution.SELECTOR_INVALID, f"{path.name} holds several arrays; name one")
+        if locator.array not in loaded.files:
+            return _no(
+                Resolution.SELECTOR_INVALID,
+                f"{path.name} has no array {locator.array!r}; arrays are "
+                f"{', '.join(loaded.files[:8])}",
+            )
+        array = loaded[locator.array]
+    else:
+        array = loaded
+
+    if failure := _index_faults(locator.index, tuple(array.shape)):
+        return failure
+    return _element(array[locator.index], locator.array or path.stem, locator.index)
+
+
+def _index_faults(index: tuple[int, ...], shape: tuple[int, ...]) -> Found | None:
+    """What is wrong with an index for an array of this shape, or None."""
+    if len(index) != len(shape):
+        return _no(
+            Resolution.SELECTOR_INVALID,
+            f"array has {len(shape)} dimensions; index gives {len(index)}",
+        )
+    if any(i < 0 for i in index):
+        # A negative index resolves from the end in Python, so `-1` silently addressed the
+        # last element and `-99` raised out of the adapter as a backend defect. Neither is an
+        # address; the same condition on the upper side is a clean `absent`.
+        return _no(
+            Resolution.SELECTOR_INVALID,
+            f"index {index} is negative; an address is not relative to the end",
+        )
+    if any(i >= n for i, n in zip(index, shape, strict=True)):
+        return _no(Resolution.ABSENT, f"index {index} is outside shape {shape}")
+    return None
+
+
+def _element(value, name: str, index: tuple[int, ...]) -> Found:
+    """One indexed element as a resolution, refusing anything that is not one scalar."""
+    if value.ndim:
+        return _no(Resolution.NOT_SCALAR, f"index resolves to a {value.ndim}-d slice")
+    if value.dtype.kind == "V":
+        # `ndim` does not settle this. The rank guard forces a full index, so every element is
+        # 0-d -- including one of a structured or subarray dtype, which indexes to a
+        # `numpy.void` holding several fields. That stringified as `(0.91, 0.02)` and was
+        # returned as one resolved value, against the invariant this adapter exists to hold.
+        held = ", ".join(value.dtype.names) if value.dtype.names else f"{value.itemsize} bytes"
+        return _no(Resolution.NOT_SCALAR, f"index resolves to a record holding {held}")
+    if value.dtype.kind in "SO":
+        # `str(numpy.bytes_(b"0.91"))` is `b'0.91'`, which is not the text the file holds. HDF5
+        # stores strings as bytes, fixed-length or variable, and these reach here as either.
+        item = value.item()
+        text = item.decode("utf-8", errors="replace") if isinstance(item, bytes) else str(item)
+        return _ok(text, type(item).__name__, f"{name}{list(index)}")
+    return _ok(str(value), str(value.dtype), f"{name}{list(index)}")
+
+
+# ------------------------------------------------------------------------------------- hdf5
+
+
+def _members(group) -> str:
+    return ", ".join(list(group.keys())[:8]) or "nothing"
+
+
+def _resolve_hdf5(locator: ArrayLocator, path: pathlib.Path) -> Found:
+    if h5py is None or numpy is None:
+        raise BackendUnavailableError(
+            "array", f'h5py is not installed -- pip install "{DISTRIBUTION}[hdf5]"'
+        )
+    if locator.array is None:
+        return _no(Resolution.SELECTOR_INVALID, f"{path.name} holds datasets by path; name one")
+    try:
+        handle = h5py.File(path, "r")
+    except OSError as e:
+        raise ArtifactUnreadableError(path, f"not a readable HDF5 file: {e}") from e
+    with handle:
+        # `get` rather than indexing: a dangling soft or external link is a name that leads
+        # nowhere, which for a locator is the same fact as a name that is not there.
+        node = handle.get(locator.array)
+        if node is None:
+            return _no(
+                Resolution.SELECTOR_INVALID,
+                f"{path.name} has no dataset {locator.array!r}; the root holds {_members(handle)}",
+            )
+        if not isinstance(node, h5py.Dataset):
+            return _no(
+                Resolution.SELECTOR_INVALID,
+                f"{locator.array!r} in {path.name} is a group, holding {_members(node)}",
+            )
+        if node.shape is None:
+            return _no(Resolution.ABSENT, f"{locator.array!r} in {path.name} holds no data")
+        if failure := _index_faults(locator.index, tuple(node.shape)):
+            return failure
+        try:
+            # Reads the one element, not the dataset: a results file can be gigabytes.
+            value = node[locator.index]
+        except OSError as e:
+            # A compression filter this build of HDF5 lacks fails here, not on open.
+            raise ArtifactUnreadableError(path, f"{locator.array!r} cannot be read: {e}") from e
+    return _element(numpy.asarray(value), locator.array, locator.index)
+
+
+# ----------------------------------------------------------------------------------- netcdf
+
+
+def _resolve_netcdf(locator: ArrayLocator, path: pathlib.Path) -> Found:
+    if netCDF4 is None or numpy is None:
+        raise BackendUnavailableError(
+            "array", f'netCDF4 is not installed -- pip install "{DISTRIBUTION}[netcdf]"'
+        )
+    if locator.array is None:
+        return _no(Resolution.SELECTOR_INVALID, f"{path.name} holds variables by path; name one")
+    try:
+        dataset = netCDF4.Dataset(path, "r")
+    except OSError as e:
+        raise ArtifactUnreadableError(path, f"not a readable NetCDF file: {e}") from e
+    try:
+        try:
+            node = dataset[locator.array]
+        except IndexError:
+            return _no(
+                Resolution.SELECTOR_INVALID,
+                f"{path.name} has no variable {locator.array!r}; the root holds "
+                f"{', '.join([*dataset.variables, *dataset.groups][:8]) or 'nothing'}",
+            )
+        if not isinstance(node, netCDF4.Variable):
+            return _no(
+                Resolution.SELECTOR_INVALID,
+                f"{locator.array!r} in {path.name} is a group, not a variable",
+            )
+        if failure := _index_faults(locator.index, tuple(node.shape)):
+            return failure
+        value = node[locator.index]
+    finally:
+        dataset.close()
+    if numpy.ma.is_masked(value):
+        return _no(
+            Resolution.ABSENT,
+            f"{locator.array}{list(locator.index)} in {path.name} holds the fill value",
+        )
+    return _element(numpy.asarray(numpy.ma.getdata(value)), locator.array, locator.index)

claims/adapters/base.py

@@ -0,0 +1,75 @@
+"""The contract every format adapter returns.
+
+Split from `claims.resolve` so an adapter can import it without importing the dispatcher
+that imports the adapter. Original module docstring follows.
+
+Resolving a locator to exactly one stored value.
+
+One contract over several formats, rather than one pointer syntax pretending every file is a
+tree. Each adapter translates a locator into the addressing its format already has -- a JSON
+Pointer into JSON, a column and key predicate into a table, a dataset path and index into an
+array -- and every adapter enforces the same invariant:
+
+    0 matches       -> ABSENT
+    1 scalar        -> RESOLVED
+    2 or more       -> AMBIGUOUS
+    a container     -> NOT_SCALAR
+
+No adapter takes the first match, and no adapter falls back to searching a file for the
+printed number. A search would find the number wherever it appears and call that
+verification, which is the failure the whole package exists to prevent. A format with no
+adapter reports `FORMAT_UNSUPPORTED` and stops.
+
+**Values come back as text.** The original representation is preserved rather than parsed to
+a binary float, because converting `0.1` to a float and back reintroduces exactly the
+third-significant-figure disagreements the comparison is meant to measure.
+"""
+
+from __future__ import annotations
+
+import enum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Resolution(enum.StrEnum):
+    """What a locator found."""
+
+    RESOLVED = "resolved"
+    ABSENT = "absent"
+    AMBIGUOUS = "ambiguous"
+    NOT_SCALAR = "not_scalar"
+    COLUMN_ABSENT = "column_absent"
+    """The artifact has no such column or field. The value could be there and is not."""
+    SELECTOR_INVALID = "selector_invalid"
+    """The locator names a column, field or array the artifact does not have. The manifest is
+    wrong, which is a different fact from the artifact lacking the value."""
+    PASSAGE_AMBIGUOUS = "passage_ambiguous"
+    """One pair of anchors selected two different values in one document. A table reports an
+    ambiguous row for the same reason, in the vocabulary a table has."""
+    NUMBER_AS_WORD = "number_as_word"
+    """The locator selected an English cardinal written out. The value is there and is not a
+    decimal, and converting it is a semantic decision the manifest has to ask for."""
+    FORMAT_UNSUPPORTED = "format_unsupported"
+
+
+class ExtractedValue(BaseModel):
+    """One stored value, in the representation the artifact used."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    raw: str
+    native_type: str
+    trace: tuple[str, ...] = ()
+    """How the value was reached, for a reader reconstructing the address by hand."""
+
+
+Found = tuple[Resolution, ExtractedValue | None, str]
+
+
+def _ok(raw: str, native: str, *trace: str) -> Found:
+    return Resolution.RESOLVED, ExtractedValue(raw=raw, native_type=native, trace=tuple(trace)), ""
+
+
+def _no(resolution: Resolution, detail: str) -> Found:
+    return resolution, None, detail

claims/adapters/cells.py

@@ -0,0 +1,94 @@
+"""A typed cell as the text a delimited cell would hold.
+
+A delimited file stores text, so the table adapter compares text and returns text. A workbook,
+a Parquet file or a Stata file stores a typed value, and the row predicate and the comparison
+both need it as text in one convention, or the same table exported two ways would resolve
+differently. The convention is the shortest text that reads back as the stored value:
+
+    float     the shortest decimal that round-trips, `0.1` and never `0.1000000000000000055`
+    integral  `2` rather than `2.0`, so `where: {seed: 2}` selects a row SPSS stored as 2.0
+    boolean   `true` / `false`, which is what `predicate_text` writes for a boolean predicate
+    missing   None, which a value cell reports as absent and a key cell never matches
+
+Nothing here rounds. A stored 0.6478999999999999 comes back as that, and the comparison
+applies the manuscript's printed precision exactly as it does to a cell of a CSV.
+"""
+
+from __future__ import annotations
+
+import datetime
+import decimal
+import math
+import struct
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Container(BaseModel):
+    """A cell holding several values -- a list, a record, a nested frame.
+
+    Not text. Stringifying one produced `[0.91, 0.02]` in the array adapter and compared it as
+    though it were a number, so a container is carried as itself and reported as not a scalar.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    holds: str
+
+
+Cell = str | Container | None
+
+
+def shortest_single(value: float) -> str:
+    """The shortest decimal that reads back as the same 32-bit float.
+
+    Stata stores `float` columns in four bytes, and every reader widens them to a double:
+    0.1 comes back as 0.10000000149011612, which is the double nearest the single, not the
+    number the analyst wrote. A manuscript printing 0.100000 would then be contradicted by
+    digits the file never held.
+    """
+    packed = struct.pack("<f", value)
+    for digits in range(1, 10):
+        text = f"{value:.{digits}g}"
+        if struct.pack("<f", float(text)) == packed:
+            return _integral(text)
+    return _integral(repr(value))  # pragma: no cover - nine digits always round-trip a single
+
+
+def _integral(text: str) -> str:
+    return text[:-2] if text.endswith(".0") else text
+
+
+def render(value: object) -> Cell:
+    """One stored value, as text in the convention above.
+
+    Numpy scalars arrive from some readers, and are recognized by duck typing rather than by
+    importing numpy, which none of the table readers' extras otherwise need here.
+    """
+    if value is None:
+        return None
+    if isinstance(value, Container):
+        return value
+    item = getattr(value, "item", None)
+    if callable(item) and not isinstance(value, (str, bytes, float, int)):
+        kind = getattr(getattr(value, "dtype", None), "kind", "")
+        if kind == "f":
+            # `item()` widens a float32 to a double, which is the defect `shortest_single`
+            # exists to undo. Numpy's own `str` is already the shortest for the value's width.
+            return _integral(str(value))
+        value = item()
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, float):
+        return "nan" if math.isnan(value) else _integral(repr(value))
+    if isinstance(value, int | decimal.Decimal):
+        return str(value)
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace").strip()
+    if isinstance(value, datetime.datetime | datetime.date | datetime.time):
+        return value.isoformat()
+    if isinstance(value, str):
+        return value.strip()
+    if isinstance(value, list | tuple | dict | set):
+        return Container(holds=f"a {type(value).__name__} of {len(value)}")
+    return Container(holds=f"a {type(value).__name__}")