172 lines
5.6 KiB
Python
172 lines
5.6 KiB
Python
"""Review protocols are YAML label sets. ``protocols/*.yaml`` is the source.
|
|
|
|
``prisma-screen.yaml`` carries ``from: lead.review.codes`` instead of a
|
|
label list. :func:`load` expands that marker from the live LEAD codebooks
|
|
so a codebook edit shows up here without a copied list.
|
|
|
|
A ``protocols.py`` module cannot sit next to this directory, so the loader
|
|
lives in the package. ``from focus.protocols import load`` is unchanged.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import re
|
|
from dataclasses import dataclass
|
|
from pathlib import Path
|
|
from typing import Any
|
|
|
|
import yaml
|
|
|
|
_ID = re.compile(r"^[a-z0-9-]+$")
|
|
_KEYS = "1234567890abcdefghijklmnopqrstuvwxyz"
|
|
_FROM = "lead.review.codes"
|
|
|
|
ROOT = Path(__file__).parent
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Label:
|
|
"""One keyboard-selectable label. ``tag`` drives the bib ``hl:`` tag."""
|
|
|
|
id: str
|
|
text: str
|
|
key: str
|
|
tag: str
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Protocol:
|
|
"""A versioned label set. ``version`` is the number stored on an annotation."""
|
|
|
|
name: str
|
|
version: int
|
|
title: str
|
|
scope: str
|
|
labels: tuple[Label, ...]
|
|
|
|
def label(self, label_id: str) -> Label | None:
|
|
"""The label with this id, or ``None``."""
|
|
for item in self.labels:
|
|
if item.id == label_id:
|
|
return item
|
|
return None
|
|
|
|
|
|
def available() -> list[str]:
|
|
"""Protocol names, sorted, from the YAML files next to this module."""
|
|
return sorted(path.stem for path in ROOT.glob("*.yaml"))
|
|
|
|
|
|
def load(name: str) -> Protocol:
|
|
"""Load and validate one protocol. A bad file raises ``ValueError``
|
|
whose message contains the filename."""
|
|
path = ROOT / f"{name}.yaml"
|
|
if not path.is_file():
|
|
raise ValueError(f"{path.name}: no such protocol")
|
|
try:
|
|
data = yaml.safe_load(path.read_text(encoding="utf-8"))
|
|
except yaml.YAMLError as exc:
|
|
raise ValueError(f"{path.name}: invalid YAML: {exc}") from exc
|
|
try:
|
|
return _protocol(name, data)
|
|
except ValueError as exc:
|
|
raise ValueError(f"{path.name}: {exc}") from exc
|
|
|
|
|
|
def _protocol(name: str, data: Any) -> Protocol:
|
|
if not isinstance(data, dict):
|
|
raise ValueError("protocol is not a mapping")
|
|
got = data.get("name")
|
|
if not isinstance(got, str) or not got:
|
|
raise ValueError("name is missing")
|
|
if got != name:
|
|
raise ValueError(f"name {got!r} does not match the file")
|
|
version = data.get("version")
|
|
if type(version) is not int:
|
|
raise ValueError("version must be an int")
|
|
title = _text(data, "title")
|
|
scope = _text(data, "scope")
|
|
marker = data.get("from")
|
|
if marker is not None and "labels" in data:
|
|
raise ValueError("from and labels are both set")
|
|
if marker is not None:
|
|
if marker != _FROM:
|
|
raise ValueError(f"from must be {_FROM}")
|
|
raw_labels = _reason_labels()
|
|
else:
|
|
raw_labels = data.get("labels")
|
|
if not isinstance(raw_labels, list) or not raw_labels:
|
|
raise ValueError("labels must be a non-empty list")
|
|
return Protocol(
|
|
name=name,
|
|
version=version,
|
|
title=title,
|
|
scope=scope,
|
|
labels=_labels(name, raw_labels),
|
|
)
|
|
|
|
|
|
def _text(data: dict, field: str) -> str:
|
|
value = data.get(field)
|
|
if not isinstance(value, str) or not value:
|
|
raise ValueError(f"{field} is missing")
|
|
return value
|
|
|
|
|
|
def _reason_labels() -> list[dict[str, str]]:
|
|
"""Union of ``reason_codes`` across the LEAD projects, codebook order,
|
|
first project's sentence kept when a code repeats. Keys are assigned
|
|
here because the codebook does not carry shortcuts."""
|
|
from lead.review.codes import PROJECTS, reason_choices, reason_codes
|
|
|
|
sentences: dict[str, str] = {}
|
|
ordered: list[str] = []
|
|
seen: set[str] = set()
|
|
for project in PROJECTS:
|
|
for code, sentence in reason_choices(project):
|
|
sentences.setdefault(code, sentence)
|
|
for code in reason_codes(project):
|
|
if code not in seen:
|
|
seen.add(code)
|
|
ordered.append(code)
|
|
if len(ordered) > len(_KEYS):
|
|
raise ValueError("more labels than single-character keys")
|
|
missing = [code for code in ordered if code not in sentences]
|
|
if missing:
|
|
raise ValueError(f"reason code has no sentence: {missing[0]}")
|
|
return [
|
|
{"id": code, "text": sentences[code], "key": _KEYS[i]}
|
|
for i, code in enumerate(ordered)
|
|
]
|
|
|
|
|
|
def _labels(protocol: str, raw: list[Any]) -> tuple[Label, ...]:
|
|
found: list[Label] = []
|
|
ids: set[str] = set()
|
|
keys: set[str] = set()
|
|
for item in raw:
|
|
if not isinstance(item, dict):
|
|
raise ValueError("label is not a mapping")
|
|
label_id = item.get("id")
|
|
text = item.get("text")
|
|
key = item.get("key")
|
|
if not isinstance(label_id, str) or not _ID.fullmatch(label_id):
|
|
raise ValueError(f"id {label_id!r} must match {_ID.pattern}")
|
|
if not isinstance(text, str) or not text:
|
|
raise ValueError(f"label {label_id} is missing text")
|
|
if not isinstance(key, str) or len(key) != 1:
|
|
raise ValueError(f"key for {label_id} must be one character")
|
|
if label_id in ids:
|
|
raise ValueError(f"duplicate label id {label_id!r}")
|
|
if key in keys:
|
|
raise ValueError(f"duplicate key {key!r}")
|
|
ids.add(label_id)
|
|
keys.add(key)
|
|
tag = item.get("tag", None)
|
|
if tag is None:
|
|
tag = f"hl:{protocol}:{label_id}"
|
|
elif not isinstance(tag, str) or not tag:
|
|
raise ValueError(f"tag for {label_id} must be a non-empty string")
|
|
found.append(Label(id=label_id, text=text, key=key, tag=tag))
|
|
return tuple(found)
|