Source code for scenet.frontends.common

"""Shared between the frontends.

Both syntaxes -- YAML documents and comic scripts -- produce the same
[`PanelIR`][scenet.ir.PanelIR], and both need the same two things on the way: a rewrite
of the surface conveniences into the IR's canonical shape, and a way to turn pydantic's
error list into a diagnostic a person can act on.

These lived in `yaml_front` and were imported into `script_front` through their private
names, which put a module's internals on another module's import line. Whichever
frontend came first would have owned them by accident. They belong here, where neither
does.
"""

import difflib
import re
from typing import Any

from pydantic import ValidationError
from pydantic_core import ErrorDetails

from scenet.errors import PanelSyntaxError, RuleViolationError
from scenet.ir import PUPPET_KEYS, Predicate, Relation
from scenet.places import PLACES, Place

__all__ = [
    "LANGUAGE_REFERENCE",
    "LAYOUT_KEYS",
    "SITE",
    "errors_of",
    "expand_place",
    "normalise",
    "normalise_layout",
    "parse_relation",
    "summarise",
]

#: Where the documentation is published: the root, which serves the latest release. A message
#: read in a terminal or an editor has no folder of documentation beside it, so a path in the
#: repository would lead nowhere; a finding's help names a page of the site instead.
SITE = "https://creatoan.github.io/scenet/"

#: Where the language reference is published, which a finding's help names.
LANGUAGE_REFERENCE = f"{SITE}reference/language/"

# `alice left_of bob` -- subject, predicate, object, separated by whitespace.
RELATION_RE = re.compile(r"^\s*(\S+)\s+(\S+)\s+(\S+)\s*$")

# Verbs a script entry may be tagged with. Single-key mappings rather than a
# discriminator field, so a new verb costs the author nothing to adopt and costs this
# table one line.
KNOWN_VERBS = frozenset({"say", "caption", "sfx"})


[docs] def parse_relation(text: str) -> Relation: """Parse `subject predicate object` into a relation. Written as a sentence rather than a mapping because staging is read far more often than it is written, and `alice left_of bob` is legible at a glance in a way that a three-key mapping is not. Args: text: One staging entry. Returns: The validated relation. Raises: PanelSyntaxError: The entry is not three whitespace-separated words, names an unknown predicate, or relates an actor to itself -- the last under rule `reflexive-relation`. Example: >>> from scenet.frontends.common import parse_relation >>> relation = parse_relation("alice left_of bob") >>> relation.subject, relation.predicate.value, relation.object ('alice', 'left_of', 'bob') """ match = RELATION_RE.match(text) if not match: raise PanelSyntaxError( f"staging entry {text!r} is not of the form 'subject predicate object'" ) subject, predicate_text, obj = match.groups() try: predicate = Predicate(predicate_text) except ValueError as exc: known = ", ".join(sorted(member.value for member in Predicate)) raise PanelSyntaxError( f"in staging entry {text!r}: unknown predicate {predicate_text!r}; " f"known predicates are {known}" ) from exc try: return Relation(subject=subject, predicate=predicate, object=obj) except ValidationError as exc: # A check that knows its rule -- an actor related to itself -- keeps it, so the # finding is filed under `reflexive-relation` rather than a generic bad field. for error in exc.errors(): broken = (error.get("ctx") or {}).get("error") if isinstance(broken, RuleViolationError): raise PanelSyntaxError( f"in staging entry {text!r}: {broken}", rule=broken.rule ) from exc raise PanelSyntaxError(f"in staging entry {text!r}: {summarise(exc)}") from exc
[docs] def expand_place(setting: object) -> object: """Rewrite `place:` into the mass list it stands for. A preset is a library for convenience, never a second format -- so it is expanded here, in the frontend, exactly as a staging sentence is. Everything downstream sees one representation of a backdrop. Args: setting: The value of the `setting` key, exactly as the YAML parser produced it -- which is why this is `object` and not a mapping: rejecting a setting written as prose is half of what this function is for. Returns: The same mapping with `place` replaced by `masses`, or unchanged when no place was named. The input is not modified. Raises: PanelSyntaxError: `setting` is not a mapping (prose is not accepted), the place is not one the library has, `place` was given alongside `masses`, or an `image` beside a place, masses or a horizon. Example: >>> from scenet.frontends.common import expand_place >>> [mass.kind.value for mass in expand_place({"place": "shore"})["masses"]] ['sky', 'water', 'ground'] """ if not isinstance(setting, dict): raise PanelSyntaxError( "'setting' must be a mapping of horizon, masses, time, weather and image. A " "description in prose is not accepted: interpreting one needs language " "understanding, and guessing produces panels that are confidently wrong. " f"Name a place instead -- known places are {_known_places()}. To say in words " "what the panel shows, for a reader who cannot see it, write `description:`", rule="invalid-field", loc=("setting",), ) _image_stands_alone(setting) if "place" not in setting: return setting if "masses" in setting: raise PanelSyntaxError( "'setting' names a place and lists masses; a place *is* a mass list, so " "this asks two questions at once. Write one or the other -- " f"{LANGUAGE_REFERENCE}setting.html#settingplace prints what each place expands into", rule="conflicting-setting", loc=("setting", "place"), ) try: place = Place(setting["place"]) except ValueError as exc: raise PanelSyntaxError( f"unknown place {setting['place']!r}; known places are {_known_places()}", rule="unknown-place", loc=("setting", "place"), ) from exc # The `Mass` objects go in directly rather than as dicts, exactly as `parse_relation` # puts `Relation` objects into `staging`: pydantic accepts a model where its own type # is expected, and round-tripping through dicts would only invite the two to drift. expanded = {key: value for key, value in setting.items() if key != "place"} expanded["masses"] = list(PLACES[place]) return expanded
#: What a picture cannot be written beside, and why, in the order they are reported. A #: horizon is here because it places masses, and a picture brings none to place. _BESIDE_AN_IMAGE = { "place": ( "names a place and an image; the picture is the whole backdrop, and so is the " "place. On a panel that inherits the place, write `place: null` beside the image" ), "masses": ( "lists masses and names an image; the picture is the whole backdrop, so write one " "or the other. On a panel that inherits the masses, write `masses: null`" ), "horizon": ( "gives a horizon and names an image; a horizon says where masses meet the ground, " "and a picture has its own. On a panel that inherits it, write `horizon: null`" ), } def _image_stands_alone(setting: dict[Any, Any]) -> None: """Refuse a picture written beside a place, masses or a horizon. Reported at the other key, as a place beside masses is reported at the place: on a panel that inherits one of the two, that is the one a scene's default wrote, and the finding then points at it once rather than at every panel. """ if setting.get("image") is None: return for key, why in _BESIDE_AN_IMAGE.items(): if setting.get(key) is not None: raise PanelSyntaxError( f"'setting' {why}", rule="conflicting-setting", loc=("setting", key) ) def _figures_stand_alone(document: dict[str, Any]) -> None: """Refuse what a figure a picture draws cannot have: a puppet's keys, and a camera. Checked here, as a horizon beside a picture is, because in the IR a key written with its default value and a key not written look the same, and `facing: right` beside a figure is as much a slip as `facing: left`. Each is reported at the key that does not apply -- on a member inherited from a scene's defaults, that is where it was written. """ cast = document.get("cast") if not isinstance(cast, dict): return members = [(actor, member) for actor, member in cast.items() if isinstance(member, dict)] for actor, member in members: if member.get("figure") is None: continue for key in ("reference", *PUPPET_KEYS): if member.get(key) is not None: why = ( "names a puppet and a figure the picture draws; it is one or the other" if key == "reference" else f"is a figure the picture draws, which nobody poses or places, so " f"{key!r} does not apply to it" ) raise PanelSyntaxError( f"cast member {actor!r} {why}. Over an inherited member, write `{key}: null`", rule="conflicting-cast", loc=("cast", str(actor), key), ) if not members or len(members) != len(cast): return if any(member.get("figure") is None for _, member in members): return camera = document.get("camera") if camera is None or camera == {}: return written = next(iter(camera), None) if isinstance(camera, dict) else None raise PanelSyntaxError( "'camera' frames a cast that a picture draws, and the artist already framed it: " "the shot is whatever the picture shows. Remove it; on a panel that inherits one, " "write `camera: null`", rule="figure-staging", loc=("camera",) if written is None else ("camera", str(written)), ) def _known_places() -> str: return ", ".join(sorted(place.value for place in Place))
[docs] def normalise(data: dict[str, Any]) -> dict[str, Any]: """Rewrite surface conveniences into the IR's canonical shape. Three shapes differ between the surface syntax and the IR. Staging is written as sentences. Script entries are written as single-key mappings tagged by verb (`- say: {...}`, `- caption: {...}`) so that a new verb can be added without a discriminator field the author has to type; the tag is moved into the payload as `verb`, which is where the IR's event models expect to find it. And a setting may name a place, which stands for a list of masses. Args: data: A parsed top-level panel mapping, in surface form. Returns: A new mapping in the shape `PanelIR` validates. The input is not modified. Raises: PanelSyntaxError: `staging` or `script` is not a list, a script entry is not a single-key mapping, it names a verb that does not exist, or `setting` names a place that does not exist or lists masses alongside one. """ result = dict(data) _rewrite_blocks(result) _figures_stand_alone(result) # Every fault below carries `loc`, the entry it is about. Pydantic has not seen the # document yet, so there is no other path to report -- and without one an editor # can only underline the whole document. if "staging" in result: raw = result["staging"] if not isinstance(raw, list): raise PanelSyntaxError( "'staging' must be a list of relation sentences", loc=("staging",) ) relations: list[Any] = [] for index, entry in enumerate(raw): if not isinstance(entry, str): relations.append(entry) continue try: relations.append(parse_relation(entry)) except PanelSyntaxError as exc: raise PanelSyntaxError(str(exc), rule=exc.rule, loc=("staging", index)) from exc result["staging"] = relations if "script" in result: raw = result["script"] if not isinstance(raw, list): raise PanelSyntaxError("'script' must be a list of narrative events", loc=("script",)) events: list[Any] = [] for index, entry in enumerate(raw): if not isinstance(entry, dict) or len(entry) != 1: raise PanelSyntaxError( f"script entry {index} must be a single-key mapping such as " f"'- say: {{by: alice, text: ...}}'", loc=("script", index), ) verb, payload = next(iter(entry.items())) if verb not in KNOWN_VERBS: known = ", ".join(sorted(KNOWN_VERBS)) raise PanelSyntaxError( f"script entry {index}: unknown verb {verb!r}; known verbs are {known}", loc=("script", index), ) if not isinstance(payload, dict): raise PanelSyntaxError( f"script entry {index}: {verb!r} expects a mapping", loc=("script", index) ) # The tag is injected rather than dropped. Now that a script holds more than # one sort of event, discarding it would leave the union to be resolved by # which model happens to accept the keys -- guesswork, on documents whose # whole point is being unambiguous. events.append({**payload, "verb": verb}) result["script"] = events return result
def _rewrite_blocks(document: dict[str, Any]) -> None: """Expand the conveniences inside whole blocks, in place on a copy of the document. A place stands for its masses, and one font file for a whole family. """ for key, rewrite in (("setting", expand_place), ("lettering", _one_font_file)): if key in document: document[key] = rewrite(document[key]) def _one_font_file(lettering: object) -> object: """Rewrite `font: path` as `font: {regular: path}`, the whole family from one face. Anything not shaped as expected is passed through, for validation to judge. """ if isinstance(lettering, dict) and isinstance(lettering.get("font"), str): return {**lettering, "font": {"regular": lettering["font"]}} return lettering
[docs] def errors_of(exc: ValidationError) -> list[ErrorDetails]: """Pydantic's error list, without the echoes of a fault already reported. Two echoes are dropped: - When an item of a `tuple[X, ...]` field with a minimum length fails, pydantic also reports the tuple as too short, counting only the items that passed: a tier with a bad height says "Tuple should have at least 1 item after validation, not 0" beside the real fault. A `list` does not do this. The echo names no fault of its own, so it is dropped whenever a deeper error explains it. - A misspelled required key is one mistake that pydantic reports twice: the unknown key, and the required key it should have been. When an unknown key closely matches a required one missing from the same mapping, the two become one finding about the unknown key, which says what it was meant to be. Args: exc: The validation error pydantic raised. Returns: Its errors, in pydantic's order, less the echoes. """ errors = exc.errors() errors = [ error for error in errors if error["type"] != "too_short" or not any( len(other["loc"]) > len(error["loc"]) and other["loc"][: len(error["loc"])] == error["loc"] for other in errors ) ] return _merge_misspellings(errors)
def _merge_misspellings(errors: list[ErrorDetails]) -> list[ErrorDetails]: """Fold each missing key into the unknown key in the same mapping that misspells it.""" missing = { index: error for index, error in enumerate(errors) if error["type"] == "missing" and error["loc"] and isinstance(error["loc"][-1], str) } dropped: set[int] = set() merged: list[ErrorDetails] = [] for error in errors: key = error["loc"][-1] if error["loc"] else None if error["type"] == "extra_forbidden" and isinstance(key, str): candidates = { str(other["loc"][-1]): index for index, other in missing.items() if index not in dropped and other["loc"][:-1] == error["loc"][:-1] } meant = difflib.get_close_matches(key, list(candidates), n=1, cutoff=0.75) if meant: dropped.add(candidates[meant[0]]) renamed = error.copy() renamed["msg"] = f"{error['msg']}; did you mean '{meant[0]}'?" merged.append(renamed) continue merged.append(error) return [error for index, error in enumerate(merged) if index not in dropped] #: pydantic error types that deserve their own rule. Everything else that pydantic #: raises at field level is reported as `invalid-field`, which is honest: the catalogue #: should not grow a rule per validator in a library this project does not own. PYDANTIC_RULES = { "missing": "missing-field", "extra_forbidden": "unknown-key", } def rule_for_pydantic(error: ErrorDetails) -> tuple[str, tuple[str | int, ...]]: """Decide which rule a pydantic error belongs to, and where it points. A `RuleViolationError` raised inside a validator survives in `ctx["error"]`, carrying the rule it broke and the path it knew about -- which is the only way a model-level validator can report anything more precise than "the document". Here rather than in `diagnostics`, which imports the frontends: the comic-script frontend needs the same answer to say which rule a panel broke, and where. `diagnostics` adds its own check that the catalogue has the rule. Example: >>> from scenet.frontends.common import rule_for_pydantic >>> rule_for_pydantic({"type": "missing", "loc": ("cast",), "msg": "", "input": None}) ('missing-field', ('cast',)) """ original = (error.get("ctx") or {}).get("error") if isinstance(original, RuleViolationError): return original.rule, original.loc or tuple(error["loc"]) return PYDANTIC_RULES.get(str(error["type"]), "invalid-field"), tuple(error["loc"]) def first_fault(exc: ValidationError) -> tuple[str | None, tuple[str | int, ...]]: """The rule and place of the first fault pydantic found, as `scenet check` orders them. A :exc:`PanelSyntaxError <scenet.errors.PanelSyntaxError>` lists every fault in its message, and carries one as data: this one, so a caller can match it by rule and point at its value, as a comic script's error already could. Example: >>> from pydantic import ValidationError >>> from scenet import PanelIR >>> from scenet.frontends.common import first_fault >>> try: ... PanelIR.model_validate({"cast": {"a": {"reference": "alice", "at": "x"}}}) ... except ValidationError as exc: ... print(first_fault(exc)) ('invalid-field', ('cast', 'a', 'at')) """ errors = errors_of(exc) if not errors: # pragma: no cover -- pydantic raises with at least one error return None, () return rule_for_pydantic(errors[0])
[docs] def summarise(exc: ValidationError, *, what: str = "panel") -> str: """Flatten pydantic's error list into something a human can act on. pydantic's default rendering is accurate but verbose; for a language error the useful part is the location and the reason, one line each. Args: exc: The validation error pydantic raised. what: What failed to validate, for the first line: `panel`, or `Panel Core`. Returns: A multi-line diagnostic, one line per problem, each naming where it is. """ lines: list[str] = [] for error in errors_of(exc): # A model-level validator reports `loc=()` -- the whole document -- because # pydantic gives it no way to say which field it was unhappy about. The two # checks that matter most here knew the exact path all along, and a # `RuleViolationError` carries it through validation in `ctx["error"]`. Without this # every unresolved actor id and every ordering cycle reported `at <root>`. original = (error.get("ctx") or {}).get("error") loc = ( original.loc if isinstance(original, RuleViolationError) and original.loc else error["loc"] ) location = ".".join(str(part) for part in loc) or "<root>" # pydantic prefixes messages raised by custom validators with "Value error, ", # which is noise to somebody reading a language diagnostic. message = error["msg"].removeprefix("Value error, ") lines.append(f" at {location}: {message}") return f"invalid {what}:\n" + "\n".join(lines)
#: Keys a scene may carry beside `panels:` that lay its panels out rather than being a #: default every panel inherits. LAYOUT_KEYS = ("page", "pages") def panel_name_problem(name: object) -> str | None: """Say what is wrong with a key of `panels:`, if anything. A panel's name is text, as a cast member's id is: it names the panel's files, and a page's `use:` takes text. YAML reads an unquoted `1:` as a number and `null:` as nothing, and a scene mixing one with a named panel could not even sort its names. Args: name: A key of the `panels:` mapping, as YAML read it. Returns: The message to report, or `None` for a name that is text. Example: >>> from scenet.frontends.common import panel_name_problem >>> panel_name_problem("establishing") is None True >>> panel_name_problem(1) "panel name 1 is a number, not text; quote it to use it as a name: '1'" """ if isinstance(name, str): return None # Spelled as YAML spells it, which is what the author will search the file for. if name is None: written, kind = "null", "nothing" elif isinstance(name, bool): written, kind = str(name).lower(), "a yes-or-no value" elif isinstance(name, int | float): written, kind = str(name), "a number" else: written, kind = str(name), f"a {type(name).__name__}" return f"panel name {written} is {kind}, not text; quote it to use it as a name: '{written}'"
[docs] def normalise_layout(data: dict[str, Any]) -> dict[str, Any]: """Rewrite the surface form of `page:` and `pages:` into what `PageLayout` validates. One convenience: a panel in a tier or a column may be written as its name alone, which stands for `{use: name}`. Anything not shaped as expected is passed through untouched, so the model's validation reports it with its location rather than this guessing. Args: data: The whole scene document. Returns: A mapping holding only the layout keys, in canonical form. """ layout = {key: data[key] for key in LAYOUT_KEYS if key in data} pages = layout.get("pages") if not isinstance(pages, list): return layout normalised: list[Any] = [] for page in pages: tiers = page.get("tiers") if isinstance(page, dict) else None if not isinstance(tiers, list): normalised.append(page) continue rewritten: list[Any] = [] for tier in tiers: if isinstance(tier, dict): tier = _with_named_panels(tier) # noqa: PLW2901 -- a copy, never the caller's columns = tier.get("columns") if isinstance(columns, list): tier["columns"] = [ _with_named_panels(column) if isinstance(column, dict) else column for column in columns ] rewritten.append(tier) normalised.append({**page, "tiers": rewritten}) layout["pages"] = normalised return layout
def _with_named_panels(holder: dict[str, Any]) -> dict[str, Any]: """A copy of a tier or column, each bare name under its `panels:` made `{use: name}`.""" panels = holder.get("panels") if not isinstance(panels, list): return {**holder} return { **holder, "panels": [{"use": entry} if isinstance(entry, str) else entry for entry in panels], }