claims-cli 0.6.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. claims/__init__.py +132 -0
  2. claims/__main__.py +5 -0
  3. claims/adapters/__init__.py +6 -0
  4. claims/adapters/array.py +212 -0
  5. claims/adapters/base.py +75 -0
  6. claims/adapters/cells.py +94 -0
  7. claims/adapters/columnar.py +188 -0
  8. claims/adapters/prose.py +261 -0
  9. claims/adapters/reads.py +47 -0
  10. claims/adapters/rows.py +116 -0
  11. claims/adapters/sheet.py +149 -0
  12. claims/adapters/sqlite.py +73 -0
  13. claims/adapters/table.py +135 -0
  14. claims/adapters/tree.py +163 -0
  15. claims/checks.py +511 -0
  16. claims/cli.py +1103 -0
  17. claims/core/__init__.py +9 -0
  18. claims/core/artifacts.py +121 -0
  19. claims/core/checks.py +132 -0
  20. claims/core/claims.py +100 -0
  21. claims/core/evidence.py +708 -0
  22. claims/core/manifest.py +349 -0
  23. claims/core/numbers.py +146 -0
  24. claims/core/outcomes.py +410 -0
  25. claims/core/report.py +503 -0
  26. claims/corpus.py +344 -0
  27. claims/exceptions.py +106 -0
  28. claims/export/__init__.py +23 -0
  29. claims/export/rocrate.py +787 -0
  30. claims/export/sarif.py +401 -0
  31. claims/manifest.py +59 -0
  32. claims/models.py +222 -0
  33. claims/numbers.py +453 -0
  34. claims/origins.py +303 -0
  35. claims/policy.py +369 -0
  36. claims/provenance.py +42 -0
  37. claims/record.py +1099 -0
  38. claims/regression.py +171 -0
  39. claims/renderers/__init__.py +10 -0
  40. claims/renderers/sarif.py +294 -0
  41. claims/reruns.py +111 -0
  42. claims/resolve.py +116 -0
  43. claims/stale.py +333 -0
  44. claims/starter.py +432 -0
  45. claims/toolchain.py +120 -0
  46. claims/verify.py +1371 -0
  47. claims/why.py +398 -0
  48. claims_cli-0.6.0.dist-info/METADATA +139 -0
  49. claims_cli-0.6.0.dist-info/RECORD +51 -0
  50. claims_cli-0.6.0.dist-info/WHEEL +4 -0
  51. claims_cli-0.6.0.dist-info/entry_points.txt +2 -0
claims/starter.py ADDED
@@ -0,0 +1,432 @@
1
+ """Writing a first manifest for a project that has none.
2
+
3
+ `repro manifest init` pins files by content and writes a `repro.yaml` that verifies as written,
4
+ so the first thing an author edits is a working file rather than an empty one. The files are
5
+ the ones named, or, with none named, the ones `discover` finds, which is a guess and is
6
+ reported as one.
7
+
8
+ The example claims are real where that is cheap: a number read out of a pinned JSON or YAML
9
+ file, and a line read out of a pinned text source. Each is run through the engine before it is
10
+ written and kept only if every assertion verifies. An example that cannot be made real is
11
+ written as a YAML comment, so a starter never declares a claim that fails on its first run.
12
+
13
+ Nothing here prints. `repro.cli` renders the `Starter` this returns.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import collections
19
+ import decimal
20
+ import itertools
21
+ import math
22
+ import mimetypes
23
+ import pathlib
24
+ import re
25
+ from collections.abc import Iterator
26
+
27
+ import yaml
28
+ from provenance_core.gitref import try_run
29
+ from pydantic import BaseModel, ConfigDict
30
+
31
+ from claims.adapters.array import _ARRAY_SUFFIXES
32
+ from claims.adapters.columnar import COLUMNAR_SUFFIXES
33
+ from claims.adapters.sheet import WORKBOOK_SUFFIXES
34
+ from claims.adapters.sqlite import _SQLITE_SUFFIXES
35
+ from claims.adapters.table import _DELIMITERS
36
+ from claims.adapters.tree import _TREE_SUFFIXES, Written, _load_tree
37
+ from claims.exceptions import ArtifactRefusedError, ArtifactUnreadableError, ManifestExistsError
38
+ from claims.manifest import DEFAULT_NAME
39
+ from claims.models import SCHEMA_VERSION, ArtifactRef, Digest, Manifest, Outcome
40
+ from claims.provenance import of_tree
41
+ from claims.verify import verify
42
+
43
+ #: Where discovery looks for result files, relative to the project top.
44
+ CONVENTIONAL = ("results", "paper/artifacts", "outputs", "data")
45
+
46
+ #: Every suffix a format adapter reads, taken from the adapters. `.txt` is left out although the
47
+ #: table adapter accepts it: under `results/` it is as often a log as a table.
48
+ DATA_SUFFIXES = (
49
+ set(_TREE_SUFFIXES)
50
+ | set(_DELIMITERS)
51
+ | COLUMNAR_SUFFIXES
52
+ | WORKBOOK_SUFFIXES
53
+ | _SQLITE_SUFFIXES
54
+ | _ARRAY_SUFFIXES
55
+ )
56
+
57
+ #: A manuscript is pinned unasked only under one of these names, at the top of the project or
58
+ #: in one of these directories, and only when exactly one such file exists.
59
+ MANUSCRIPT_DIRECTORIES = ("", "paper", "manuscript")
60
+ MANUSCRIPT_STEMS = ("paper", "manuscript", "main")
61
+ TEXT_SUFFIXES = (".tex", ".md", ".txt")
62
+
63
+ MAX_DISCOVERED = 20
64
+ MAX_DEPTH = 3
65
+ MAX_ENTRIES = 1000
66
+ """A directory holding more entries than this is a large tree, and is not searched."""
67
+ MAX_BYTES = 50 * 1024 * 1024
68
+ MAX_QUOTE_TRIES = 5
69
+
70
+ _NOT_SEARCHED = {"node_modules", "__pycache__", "venv", "env", "site-packages"}
71
+
72
+ #: The standard library's own table, never the host's `mime.types`, so one file gets one media
73
+ #: type on every machine. The overrides are suffixes that table lacks in some supported Python:
74
+ #: `.md` is in it only from 3.12. `media_type` is recorded and not verified.
75
+ _MEDIA_TYPES = mimetypes.MimeTypes()
76
+ _MEDIA_TYPE_OVERRIDES = {
77
+ ".yaml": "application/yaml",
78
+ ".yml": "application/yaml",
79
+ ".md": "text/markdown",
80
+ }
81
+
82
+ HEADER = """\
83
+ # The evidence manifest for {project}, read by `{program} verify`.
84
+ #
85
+ # `artifacts` pins files by sha256. An edited file is reported as a broken pin until the
86
+ # digest recorded here is replaced with the output of `shasum -a 256 <path>`.
87
+ #
88
+ # `claims` says what the manuscript states and where a pinned artifact holds it. To add a
89
+ # claim, copy an entry under `claims`, give it a new id, and point its evidence at the id of
90
+ # an artifact. Claims whose id begins `example-` were written by `{program} manifest init` to show
91
+ # the shape, and are there to be edited or removed.
92
+ #
93
+ # The kinds of evidence. `reported` is the number as the manuscript prints it, in quotes.
94
+ #
95
+ # metric a number at an RFC 6901 JSON Pointer in a JSON or YAML file
96
+ # {{kind: metric, artifact: ID, name: p, reported: '0.031', pointer: /primary/p}}
97
+ # table a cell of a CSV, TSV, Parquet, Stata, SPSS or .rds table: `where` or `row`
98
+ # {{kind: table, artifact: ID, name: acc, reported: '0.648', column: accuracy,
99
+ # where: {{model: lasso}}}}
100
+ # value a number at a locator, for every format `repro` reads
101
+ # {{kind: value, artifact: ID, name: n, reported: '480', locator: {{...}}}}
102
+ # quote a passage that occurs in a PDF, LaTeX or text source; it reads no number
103
+ # {{kind: quote, artifact: ID, text: 'A passage copied from the source.'}}
104
+ # correspondence two artifacts hold the same number, and neither is written here
105
+ # {{kind: correspondence, name: n, sides: [
106
+ # {{name: stated, artifact: ID, locator: {{...}}}},
107
+ # {{name: measured, artifact: ID, locator: {{...}}}}]}}
108
+ # aggregate a mean, median, min, max, sum or count over every member listed
109
+ # {{kind: aggregate, members: [{{artifact: ID, locator: {{...}}}},
110
+ # {{artifact: ID, locator: {{...}}}}], count: 2, statistic: mean,
111
+ # name: acc, reported: '0.914'}}
112
+ #
113
+ # The locators a `value`, a side or a member takes:
114
+ #
115
+ # JSON, YAML {{kind: tree, pointer: /primary/n}}
116
+ # CSV, TSV, PSV, Parquet, Feather,
117
+ # Arrow, Stata, SPSS, .rds {{kind: table, column: accuracy, where: {{model: lasso}}}}
118
+ # the same, by row from 0 {{kind: table_position, column: accuracy, row: 0}}
119
+ # Excel {{kind: sheet, sheet: Table 2, column: auc, where: {{model: lasso}}}}
120
+ # SQLite {{kind: sqlite, table: runs, column: loss, where: {{seed: 3}}}}
121
+ # .npy, .npz, HDF5, NetCDF {{kind: array, array: accuracy, index: [1, 1]}}
122
+ # PDF, LaTeX, text, HTML source {{kind: prose, before: 'split was', after: '%'}}
123
+ #
124
+ # `prose` reads the number between two literal anchors, for a sentence or a printed table.
125
+ # Anchors are written with single spaces, whatever the padding or line breaks in the file, and
126
+ # `after` names what touches the number. The Slope cell of the row `| 7| 0.318| 0.107|`:
127
+ #
128
+ # {{kind: prose, before: '| 7|', after: '|'}}
129
+ #
130
+ # `conversion: percent` on a number says the file stores the fraction of the percentage the
131
+ # manuscript prints, 0.042 for 4.2, and `conversion: fraction` the reverse. `places: 2` says
132
+ # the manuscript reports the number to two decimal places, and `reported` must be written so.
133
+ #
134
+ # `mode: absolute` or `relative` with `tolerance: '0.01'` replaces comparison at the precision
135
+ # `reported` prints. `where` must match exactly one row.
136
+ #
137
+ # Check it:
138
+ #
139
+ # {program} verify
140
+ #
141
+ """
142
+
143
+ COMMENTED_METRIC = """\
144
+ # - id: example-number
145
+ # text: The sentence in the manuscript that reports the number.
146
+ # evidence:
147
+ # - kind: metric
148
+ # artifact: results # the id of an artifact above
149
+ # name: accuracy
150
+ # reported: '0.93' # as the manuscript prints it, in quotes
151
+ # pointer: /metrics/accuracy # RFC 6901 JSON Pointer into the file
152
+ """
153
+
154
+ COMMENTED_QUOTE = """\
155
+ # - id: example-quote
156
+ # text: What the manuscript says the source states.
157
+ # evidence:
158
+ # - kind: quote
159
+ # artifact: paper # the id of an artifact above
160
+ # text: A passage copied from the source, forty characters or more.
161
+ """
162
+
163
+
164
+ class Starter(BaseModel):
165
+ """What `write` wrote."""
166
+
167
+ model_config = ConfigDict(frozen=True, extra="forbid")
168
+
169
+ path: pathlib.Path
170
+ artifacts: tuple[ArtifactRef, ...]
171
+ discovered: bool
172
+ """The artifacts were found by `discover` and not named by the caller."""
173
+ capped: bool = False
174
+ """Discovery found more than `MAX_DISCOVERED` files and pinned the first of them."""
175
+ notes: tuple[str, ...] = ()
176
+ """What discovery passed over, and why."""
177
+ written: tuple[str, ...] = ()
178
+ """Ids of the example claims declared in the manifest. Each verifies."""
179
+ commented: tuple[str, ...] = ()
180
+ """Ids of the example claims written as comments."""
181
+
182
+
183
+ def project_root(start: pathlib.Path) -> pathlib.Path:
184
+ """The top of the project holding `start`: its git root, or `start` outside a repository."""
185
+ top = try_run("rev-parse", "--show-toplevel", cwd=start)
186
+ return pathlib.Path(top.strip() if top else start).resolve()
187
+
188
+
189
+ def _shallowest(directory: pathlib.Path, notes: list[str]) -> list[pathlib.Path]:
190
+ """The data files at the shallowest level of `directory` that holds any.
191
+
192
+ A results directory keeps its summaries at the top and per-run output below them, so the
193
+ first level with a readable file is taken and nothing beneath it is searched.
194
+ """
195
+ level = [directory]
196
+ for _ in range(MAX_DEPTH):
197
+ files: list[pathlib.Path] = []
198
+ below: list[pathlib.Path] = []
199
+ for parent in level:
200
+ entries = list(itertools.islice(parent.iterdir(), MAX_ENTRIES + 1))
201
+ if len(entries) > MAX_ENTRIES:
202
+ notes.append(f"{parent.name}/ holds more than {MAX_ENTRIES} entries")
203
+ continue
204
+ for entry in sorted(entries):
205
+ if entry.name.startswith(".") or entry.is_symlink():
206
+ continue
207
+ if entry.is_dir():
208
+ if entry.name not in _NOT_SEARCHED:
209
+ below.append(entry)
210
+ elif entry.suffix.lower() in DATA_SUFFIXES:
211
+ if entry.stat().st_size > MAX_BYTES:
212
+ notes.append(f"{entry.name} is over {MAX_BYTES // 2**20} MB")
213
+ else:
214
+ files.append(entry)
215
+ if files:
216
+ return files
217
+ level = below
218
+ return []
219
+
220
+
221
+ def discover(root: pathlib.Path) -> tuple[list[pathlib.Path], bool, list[str]]:
222
+ """Files worth pinning under `root`, whether the cap was hit, and what was passed over."""
223
+ notes: list[str] = []
224
+ found = [
225
+ path
226
+ for name in CONVENTIONAL
227
+ if (root / name).is_dir()
228
+ for path in _shallowest(root / name, notes)
229
+ ]
230
+ capped = len(found) > MAX_DISCOVERED
231
+ found = found[:MAX_DISCOVERED]
232
+
233
+ manuscripts = [
234
+ path
235
+ for directory in MANUSCRIPT_DIRECTORIES
236
+ for stem in MANUSCRIPT_STEMS
237
+ for suffix in TEXT_SUFFIXES
238
+ if (path := root / directory / f"{stem}{suffix}").is_file()
239
+ ]
240
+ if len(manuscripts) == 1:
241
+ found.append(manuscripts[0])
242
+ elif manuscripts:
243
+ names = ", ".join(m.relative_to(root).as_posix() for m in manuscripts)
244
+ notes.append(f"{names} could each be the manuscript, so none was pinned")
245
+ return found, capped, notes
246
+
247
+
248
+ def _named(names: list[str], cwd: pathlib.Path, root: pathlib.Path) -> list[pathlib.Path]:
249
+ """The files a caller named, or `ArtifactRefusedError` for the first that cannot be pinned."""
250
+ paths = []
251
+ for name in names:
252
+ path = (cwd / name).resolve()
253
+ if not path.exists():
254
+ raise ArtifactRefusedError(path, "does not exist")
255
+ if not path.is_file():
256
+ raise ArtifactRefusedError(path, "is not a file")
257
+ if not path.is_relative_to(root):
258
+ raise ArtifactRefusedError(path, f"is outside the project at {root}")
259
+ paths.append(path)
260
+ return list(dict.fromkeys(paths))
261
+
262
+
263
+ def _slug(text: str) -> str:
264
+ return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-") or "artifact"
265
+
266
+
267
+ def _pins(paths: list[pathlib.Path], root: pathlib.Path) -> list[dict]:
268
+ """One artifact entry per file. The id is the file's stem, or its whole path where two
269
+ files share a stem."""
270
+ relative = [path.relative_to(root) for path in paths]
271
+ stems = collections.Counter(_slug(r.stem) for r in relative)
272
+ pins: list[dict] = []
273
+ used: set[str] = set()
274
+ for path, rel in zip(paths, relative, strict=True):
275
+ identifier = _slug(rel.stem) if stems[_slug(rel.stem)] == 1 else _slug(rel.as_posix())
276
+ while identifier in used:
277
+ identifier += "-2"
278
+ used.add(identifier)
279
+ suffix = path.suffix.lower()
280
+ pins.append(
281
+ {
282
+ "id": identifier,
283
+ "path": rel.as_posix(),
284
+ "media_type": _MEDIA_TYPE_OVERRIDES.get(suffix)
285
+ or _MEDIA_TYPES.guess_type(path.name)[0]
286
+ or "application/octet-stream",
287
+ "digest": {"algorithm": "sha256", "value": Digest.of_file(path).value},
288
+ }
289
+ )
290
+ return pins
291
+
292
+
293
+ def _numbers(node: object, pointer: str = "") -> Iterator[tuple[str, str]]:
294
+ """Every finite number reachable through mappings, in document order, with its pointer."""
295
+ if isinstance(node, dict):
296
+ for key, value in node.items():
297
+ if isinstance(key, str):
298
+ token = key.replace("~", "~0").replace("/", "~1")
299
+ yield from _numbers(value, f"{pointer}/{token}")
300
+ elif isinstance(node, Written):
301
+ # A number with a fraction or an exponent arrives as the text the file wrote.
302
+ if decimal.Decimal(node).is_finite():
303
+ yield pointer, str(node)
304
+ elif isinstance(node, (int, float)) and not isinstance(node, bool) and math.isfinite(node):
305
+ yield pointer, str(node)
306
+
307
+
308
+ def _metric_examples(pins: list[dict], root: pathlib.Path) -> Iterator[tuple[dict, dict]]:
309
+ """A candidate `metric` claim per pinned tree file: the first number the file holds."""
310
+ for pin in pins:
311
+ path = root / pin["path"]
312
+ if path.suffix.lower() not in _TREE_SUFFIXES:
313
+ continue
314
+ try:
315
+ first = next(_numbers(_load_tree(path)), None)
316
+ except ArtifactUnreadableError:
317
+ continue
318
+ if first is None:
319
+ continue
320
+ pointer, value = first
321
+ yield (
322
+ pin,
323
+ {
324
+ "id": "example-number",
325
+ "text": f"Example to edit: {pin['path']} holds {value} at {pointer or 'its root'}.",
326
+ "evidence": [
327
+ {
328
+ "kind": "metric",
329
+ "artifact": pin["id"],
330
+ "name": pointer.rpartition("/")[2] or pin["id"],
331
+ "reported": value,
332
+ "pointer": pointer,
333
+ }
334
+ ],
335
+ },
336
+ )
337
+
338
+
339
+ def _quote_examples(pins: list[dict], root: pathlib.Path) -> Iterator[tuple[dict, dict]]:
340
+ """Candidate `quote` claims: lines of prose from the pinned text sources."""
341
+ for pin in pins:
342
+ path = root / pin["path"]
343
+ if path.suffix.lower() not in TEXT_SUFFIXES:
344
+ continue
345
+ for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
346
+ line = line.strip()
347
+ # Forty characters is where `citations` stops warning that a quotation is short,
348
+ # and a line opening on markup is a heading, a table row or a macro.
349
+ if 40 <= len(line) <= 200 and line[0].isalnum():
350
+ yield (
351
+ pin,
352
+ {
353
+ "id": "example-quote",
354
+ "text": f"Example to edit: {pin['path']} contains this passage.",
355
+ "evidence": [{"kind": "quote", "artifact": pin["id"], "text": line}],
356
+ },
357
+ )
358
+
359
+
360
+ def _first_verified(
361
+ candidates: Iterator[tuple[dict, dict]], target: pathlib.Path, tries: int
362
+ ) -> dict | None:
363
+ """The first candidate claim whose every assertion verifies, or None.
364
+
365
+ The check is the engine's own, so what is written is what `repro verify` will report. The
366
+ trial manifest holds the one artifact the claim reads, which keeps a candidate to one file.
367
+ """
368
+ for pin, claim in itertools.islice(candidates, tries):
369
+ trial = Manifest.model_validate({"artifacts": [pin], "claims": [claim], "path": target})
370
+ decisions = verify(trial).decisions
371
+ if decisions and all(d.outcome is Outcome.VERIFIED for d in decisions):
372
+ return claim
373
+ return None
374
+
375
+
376
+ def write(
377
+ root: pathlib.Path, names: list[str], cwd: pathlib.Path, program: str = "repro"
378
+ ) -> Starter:
379
+ """Write a starter manifest at `root`, pinning `names` as given relative to `cwd`.
380
+
381
+ Raises `ManifestExistsError` rather than overwrite one, and `ArtifactRefusedError` for a
382
+ named file that is missing or outside the project. Nothing is written in either case.
383
+ """
384
+ target = root / DEFAULT_NAME
385
+ if target.exists():
386
+ raise ManifestExistsError(target)
387
+
388
+ if names:
389
+ paths, capped, notes = _named(names, cwd, root), False, []
390
+ else:
391
+ paths, capped, notes = discover(root)
392
+ pins = _pins(paths, root)
393
+
394
+ metric = _first_verified(_metric_examples(pins, root), target, len(pins))
395
+ quote = _first_verified(_quote_examples(pins, root), target, MAX_QUOTE_TRIES)
396
+ claims = [claim for claim in (metric, quote) if claim is not None]
397
+
398
+ document: dict = {"schema_version": SCHEMA_VERSION, "project": root.name}
399
+ provenance = of_tree(root, generated_by=f"{program} manifest init")
400
+ if provenance.commit:
401
+ document["provenance"] = provenance.model_dump()
402
+ document["artifacts"] = pins
403
+ if claims:
404
+ document["claims"] = claims
405
+ manifest = Manifest.model_validate({**document, "path": target})
406
+
407
+ # Comments are written around the dumped document, because `safe_dump` carries none.
408
+ # `claims` is the last key, so a commented entry sits where uncommenting it declares it.
409
+ text = HEADER.format(project=root.name, program=program) + yaml.safe_dump(
410
+ document, sort_keys=False, width=100
411
+ )
412
+ commented = (COMMENTED_METRIC if metric is None else "") + (
413
+ COMMENTED_QUOTE if quote is None else ""
414
+ )
415
+ if commented:
416
+ text += "\n# An example with nothing in this project to point at. Uncomment and edit:\n#\n"
417
+ text += ("" if claims else "# claims:\n") + commented
418
+ target.write_text(text, encoding="utf-8")
419
+
420
+ return Starter(
421
+ path=target,
422
+ artifacts=manifest.artifacts,
423
+ discovered=not names,
424
+ capped=capped,
425
+ notes=tuple(notes),
426
+ written=tuple(claim["id"] for claim in claims),
427
+ commented=tuple(
428
+ name
429
+ for name, claim in (("example-number", metric), ("example-quote", quote))
430
+ if claim is None
431
+ ),
432
+ )
claims/toolchain.py ADDED
@@ -0,0 +1,120 @@
1
+ """Which program read the artifact, and what it produced.
2
+
3
+ `Backend.version` is a protocol version: a hand-written string naming the interface a backend
4
+ implements. It is not a version of anything that reads a file, and what a decision says
5
+ depends on the program that turns bytes into text or values. A `pdftotext` upgrade that
6
+ resolves a ligature differently changes an extracted passage while every digest in the
7
+ manifest stays where it was, so a report carrying only the protocol version records the same
8
+ provenance before and after.
9
+
10
+ Two ways a tool is identified:
11
+
12
+ * a **binary**, by the version string it prints, kept as printed. Parsing it into fields
13
+ discards the build metadata distributions attach, which is the part that separates two
14
+ installations reporting the same upstream release.
15
+ * an **installed distribution**, by `importlib.metadata`.
16
+
17
+ A version that cannot be obtained is `UNKNOWN`, never omitted. A field that disappears when a
18
+ tool declines to answer makes an uninterrogated toolchain indistinguishable from an absent
19
+ one, which is the confusion this package exists to prevent, one level down.
20
+
21
+ The executable's own digest is not recorded. `pdftotext` is a driver over `libpoppler`, so
22
+ hashing it addresses the part that does not do the reading while reading as a pin on the part
23
+ that does. `Decision.extraction_digest` covers the same ground without that gap: it hashes
24
+ what the extractor produced, which moves whenever the behaviour does.
25
+
26
+ Each answer is resolved once per process. Interrogating a binary per assertion would run a
27
+ subprocess per quotation.
28
+ """
29
+
30
+ from __future__ import annotations
31
+
32
+ import functools
33
+ import subprocess
34
+ from importlib.metadata import PackageNotFoundError
35
+ from importlib.metadata import version as _installed_version
36
+
37
+ UNKNOWN = "unknown"
38
+ """Recorded where a version or a digest was sought and not obtained. Distinct from an empty
39
+ field, which says nothing was sought."""
40
+
41
+ VERSION_TIMEOUT = 10
42
+ """Seconds to wait for a tool to say what it is. A tool that hangs is not identified, and
43
+ blocking a verification run on it would be worse than recording `UNKNOWN`."""
44
+
45
+
46
+ WRAPPER = "reproducible-science"
47
+ """The distribution that installs this code with the commands that run things. Records have
48
+ always named it as the one that read an artifact."""
49
+
50
+ ALONE = "claims-cli"
51
+ """The distribution this code is, installed by itself."""
52
+
53
+
54
+ def _installed_as() -> str:
55
+ """The distribution to name for this installation: `reproducible-science` where it is
56
+ installed, as every record written by one says, and `claims-cli` where it is not."""
57
+ try:
58
+ _installed_version(WRAPPER)
59
+ except PackageNotFoundError:
60
+ return ALONE
61
+ return WRAPPER
62
+
63
+
64
+ DISTRIBUTION = _installed_as()
65
+ """What a decision names as its tool, and what an install hint for an optional reader names.
66
+ Resolved once, from what is installed. The version recorded beside it is `adapter_version()`,
67
+ which is this code's own whichever name is recorded."""
68
+
69
+
70
+ def adapter_version() -> str:
71
+ """The version of the code that read the artifact: `claims-cli`'s, always.
72
+
73
+ Not `DISTRIBUTION`'s. Beside a `reproducible-science` of another version the name a
74
+ decision records stays the one every record has carried, and the version is that of the
75
+ adapters that ran, which are this distribution's. In a lockstep release the two are one
76
+ number. `UNKNOWN` where nothing installed provides this package.
77
+ """
78
+ return distribution_version(ALONE)
79
+
80
+
81
+ @functools.cache
82
+ def binary_version(name: str, flag: str = "-v") -> str:
83
+ """The version string `name` prints, as it prints it, or `UNKNOWN`.
84
+
85
+ Both streams are read: `pdftotext -v` writes to stderr and other extractors write to
86
+ stdout, so a helper that picked one would record `unknown` for a tool that answered. The
87
+ exit status is ignored for the same reason -- several builds exit non-zero from `-v` and
88
+ print the version anyway.
89
+ """
90
+ try:
91
+ completed = subprocess.run(
92
+ [name, flag], capture_output=True, text=True, timeout=VERSION_TIMEOUT
93
+ )
94
+ except (OSError, subprocess.SubprocessError):
95
+ return UNKNOWN
96
+ for line in (completed.stdout + "\n" + completed.stderr).splitlines():
97
+ if line.strip():
98
+ return line.strip()
99
+ return UNKNOWN
100
+
101
+
102
+ @functools.cache
103
+ def distribution_version(name: str) -> str:
104
+ """The installed version of a distribution, or `UNKNOWN` where nothing provides it."""
105
+ try:
106
+ return _installed_version(name)
107
+ except PackageNotFoundError:
108
+ return UNKNOWN
109
+
110
+
111
+ __all__ = [
112
+ "ALONE",
113
+ "DISTRIBUTION",
114
+ "UNKNOWN",
115
+ "VERSION_TIMEOUT",
116
+ "WRAPPER",
117
+ "adapter_version",
118
+ "binary_version",
119
+ "distribution_version",
120
+ ]