knobly 1.1.0__py3-none-any.whl

knobly/__init__.py

@@ -0,0 +1,82 @@
+"""knobly: a configuration language defined by one grammar (grammar/Knobly.g4). One namespace per layer:
+this package root holds the shared and io names (positions, places, origins, diagnostics,
+the error tree, config text, the document source and writer ports and the in-memory adapters);
+``knobly.syntax`` the lossless syntax tree (``parse``); ``knobly.written`` the config as written (the low
+level: ``Processor.load`` returns a ``DocumentGraph`` of editable documents, read further with ``graph.read()`` and
+saved back with ``graph.save(writer)``); ``knobly.rendered`` the rendered tree (``render(graph)``: variables,
+snippets and included files expanded into directives a program reads). The core does no I/O: ``knobly.files``
+gives a filesystem source and writer, ``knobly.include`` the include extension."""
+
+# Every public signature is generated from spec/schema/api.json (knobly._api); each module's __all__ equals the
+# generated PUBLIC_NAMES for it (tests/test_api_names.py).
+
+from knobly import _docs
+from knobly._api.codes import DiagnosticCode
+from knobly._api.errors import (
+    BadTextError,
+    DetachedError,
+    DiagnosticError,
+    KnoblyError,
+    LostUpdateError,
+    ReadError,
+    SaveError,
+)
+from knobly._api.io import DocumentSource, DocumentWriter, FileWrite, LoadContext
+from knobly._api.kinds import PlaceKind, Severity, StepKind
+from knobly._api.limits import PROGRAM_CODE
+from knobly._api.shared import (
+    Block,
+    ConfigText,
+    DirectiveOrigin,
+    Locatable,
+    Origin,
+    ProgramCode,
+    SourcePosition,
+    SourceSpan,
+)
+from knobly._diagnostics import Diagnostic
+from knobly._origin import Override, Place, Step
+from knobly._report import Collecting, Diagnostics, LocatedDiagnostic
+from knobly._source import check_lost_updates, memory_source, memory_writer
+from knobly._text import quote, text
+
+__all__ = [
+    "PROGRAM_CODE",
+    "BadTextError",
+    "Block",
+    "Collecting",
+    "ConfigText",
+    "DetachedError",
+    "Diagnostic",
+    "DiagnosticCode",
+    "DiagnosticError",
+    "Diagnostics",
+    "DirectiveOrigin",
+    "DocumentSource",
+    "DocumentWriter",
+    "FileWrite",
+    "KnoblyError",
+    "LoadContext",
+    "Locatable",
+    "LocatedDiagnostic",
+    "LostUpdateError",
+    "Origin",
+    "Override",
+    "Place",
+    "PlaceKind",
+    "ProgramCode",
+    "ReadError",
+    "SaveError",
+    "Severity",
+    "SourcePosition",
+    "SourceSpan",
+    "Step",
+    "StepKind",
+    "check_lost_updates",
+    "memory_source",
+    "memory_writer",
+    "quote",
+    "text",
+]
+
+_docs.document(__name__)

knobly/_anatomy.py

@@ -0,0 +1,65 @@
+"""Directive anatomy (kno-g7n.1.3): which tokens of a ``directive`` node are its name, its values and its block.
+Private to the load layer; a port of ts/src/ast/anatomy.ts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from knobly._api.kinds import NodeKind, TokenKind
+from knobly._api.syntax import Node, Token
+from knobly.syntax._cst import ValueRef
+
+_VALUE_TOKENS = frozenset(
+    {TokenKind.WORD, TokenKind.AT_WORD, TokenKind.INTEGER, TokenKind.DIGIT_WORD, TokenKind.STRING, TokenKind.VARIABLE}
+)
+_VALUE_NODES = frozenset({NodeKind.SLICE, NodeKind.LIST})
+
+
+@dataclass(frozen=True, slots=True)
+class Anatomy:
+    name: int
+    """Index of the head token (``node.start``): a WORD names a directive, an AT_WORD a language or extension
+    statement."""
+    args: tuple[ValueRef, ...]
+    """In source order: each WORD, AT_WORD, INTEGER, DIGIT_WORD, STRING or VARIABLE token directly in the node's
+    range, and each slice or list child."""
+    block: Node | None
+
+
+def anatomy_of(tokens: tuple[Token, ...], node: Node) -> Anatomy:
+    """Split a directive node. Spaces, comments, separators, punctuation and error children are never values."""
+    values, block = _split(tokens, node)
+    return Anatomy(node.start, values, block)
+
+
+def items_of(tokens: tuple[Token, ...], node: Node) -> tuple[ValueRef, ...]:
+    """A ``list`` node's items in source order, by the same rule as a directive's values (the bracket comes first)."""
+    return _split(tokens, node)[0]
+
+
+def values_of(tokens: tuple[Token, ...], node: Node) -> tuple[ValueRef, ...]:
+    """The values of an entry rule's text (``parse_entry``'s root), by the same rule, from its first token."""
+    return _split(tokens, node, node.start)[0]
+
+
+def _split(tokens: tuple[Token, ...], node: Node, first: int | None = None) -> tuple[tuple[ValueRef, ...], Node | None]:
+    """The values and the block of ``node``, from token ``first`` (default: after its name or opening bracket)."""
+    values: list[ValueRef] = []
+    block: Node | None = None
+    children = node.children
+    following = 0
+    i = node.start + 1 if first is None else first
+    while i < node.end:
+        child = children[following] if following < len(children) else None
+        if child is not None and child.start == i:
+            if child.kind in _VALUE_NODES:
+                values.append(child)
+            elif child.kind is NodeKind.BLOCK:
+                block = child
+            following += 1
+            i = max(child.end, i + 1)
+            continue
+        if tokens[i].kind in _VALUE_TOKENS:
+            values.append(i)
+        i += 1
+    return tuple(values), block

knobly/_api/.gitignore

@@ -0,0 +1,2 @@
+# Generated by tools/gen-api.py from spec/schema/; do not edit, and never commit.
+*

knobly/_api/__init__.py

@@ -0,0 +1 @@
+"""Generated by tools/gen-api.py from spec/schema/; do not edit, and never commit."""

knobly/_api/codes.py

@@ -0,0 +1,294 @@
+"""Generated by tools/gen-api.py from spec/schema/; do not edit, and never commit.
+
+Source: spec/schema/diagnostics.json."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from types import MappingProxyType
+from typing import Final
+
+from knobly._api.kinds import Severity, UnreadableReason
+from knobly._api.limits import MAX_EXPANDED_NESTING, MAX_NESTING
+
+
+class DiagnosticCode(StrEnum):
+    """knobly's diagnostic codes, by name."""
+
+    UNTERMINATED_STRING = "E1001"
+    """A string reaches the end of its line or of the text without its closing quote."""
+    UNEXPECTED_CHARACTER = "E1003"
+    """A character no token may start with, or a byte-order mark after the first character."""
+    LONE_DOLLAR = "E1004"
+    """A $ not followed by a variable name."""
+    BAD_ESCAPE = "E1005"
+    """A closed double-quoted string holding a backslash escape other than the six (the BAD_ESCAPE error token),
+    placed on the string. A single-quoted string is raw: it has no escapes.
+    """
+    UNEXPECTED_TOKEN = "E2001"
+    """A token the grammar does not allow here, when no more specific code applies: among them the end of the text at
+    the top level, or a }, where a directive's ; or block is due (3.2). Also an edit's bad text error, from its
+    entry rule (2.8): at the first token the entry rule does not allow, or at the end of the text.
+    """
+    EXPECTED_CLOSING_BRACE = "E2003"
+    """The text ends inside a block: reported once, at the end of the text, however many blocks are open; not after a
+    statement whose error runs to the end of the text, and not inside an open [ (E2004) (3.2).
+    """
+    EXPECTED_CLOSING_BRACKET = "E2004"
+    """A stray ], or a [ list with no matching ]."""
+    BAD_SLICE = "E2007"
+    """A malformed slice after a slice name (a word or a $name): a[~], a[1~b c], an unclosed slice, or a literal
+    bound that is not an integer (a[i], a[1.5], a[1:3], whose 1:3 is one word).
+    """
+    VALUES_TOUCH = "E2009"
+    """Two values with nothing between them, such as a"b"."""
+    NESTING_TOO_DEEP = "E2010"
+    """Blocks and lists nested deeper than 100 levels. Also an edit's bad text error when the document after the edit
+    would nest past it (2.8).
+    """
+    INCLUDE_NOT_FOUND = "E3001"
+    """An extension's spec that is no glob matched no file. A glob that matches none is the warning W3005."""
+    INCLUDE_RESOLVER_FAILED = "E3004"
+    """The document source rejected while resolving or reading a file. For the root file, load fails instead (6.2)."""
+    INCLUDE_BAD_PATH = "E3005"
+    """An include whose values are not exactly one quoted path."""
+    INCLUDE_MATCHED_NOTHING = "W3005"
+    """A warning: an extension's spec that is a glob (the glob rule of 4.1) matched no file. The line splices nothing
+    for it and is not stopped. A spec that is no glob and matches no file is E3001.
+    """
+    EXTENSION_FAILED = "E3006"
+    """An extension threw something other than a diagnostic error, threw a diagnostic error whose code is a warning
+    (a warning is never thrown, 2.3; 5) or is neither knobly's nor a program code, or returned something other
+    than a list of texts.
+    """
+    UNREAD_COPY = "E3007"
+    """An extension line's copy whose specs are not resolved or whose files are not read yet (it is in unread ());
+    read () reads them. Placed on the extension line's name.
+    """
+    UNKNOWN_EXTENSION = "E3008"
+    """A statement written @name where name is no language statement (set, snippet, use) and no registered
+    extension's name. Placed on the @name; the statement is an unreadable line.
+    """
+    NON_INTEGER_BOUND = "E4001"
+    """A slice or index bound reached through a variable that is not one integer word, or a literal integer beyond
+    the integer range. A literal bound that is not an integer is E2007, found by parse.
+    """
+    WRONG_VALUE_KIND = "E4002"
+    """A reader asked for a kind the value is not."""
+    NOT_A_NUMBER = "E4004"
+    """A word read as a number that is not a JSON number, or one beyond the double range (1e400; contract 2)."""
+    NOT_AN_INTEGER = "E4005"
+    """A word read as an integer that is not one, or one beyond plus or minus 2^53-1."""
+    NOT_A_BOOLEAN = "E4006"
+    """A word other than true or false, read as a boolean."""
+    BAD_SLICE_NAME = "E4007"
+    """A slice or index whose name is a $name that does not hold exactly one WORD or AT_WORD, the words the grammar's
+    sliceName takes ($src[0~3] with $src a string, a list, two values, or a number-like word such as 5, 1.5, - or
+    07:30); placed as E4001 is.
+    """
+    UNKNOWN_VARIABLE = "E5001"
+    """A $name with no set visible and no override."""
+    VARIABLE_SET_TWICE = "E5002"
+    """Two set lines for one name in one block."""
+    UNKNOWN_SNIPPET = "E5003"
+    """A use naming no visible snippet."""
+    SNIPPET_ARITY = "E5004"
+    """A use with a different number of values than its snippet's parameters."""
+    SNIPPET_DEFINED_TWICE = "E5005"
+    """Two snippet lines for one name in one block."""
+    EXPANSION_CYCLE = "E5006"
+    """A use or extension line that reaches itself again."""
+    EXPANSION_TOO_DEEP = "E5007"
+    """Use and extension lines nested deeper than 16."""
+    TOO_MANY_DIRECTIVES = "E5008"
+    """More than 100,000 directives after expansion."""
+    BAD_SET = "E5009"
+    """A set line that is not @set $name value...;."""
+    BAD_SNIPPET = "E5010"
+    """A malformed snippet line (@snippet name $p... { ... }), or one naming a parameter twice."""
+    BAD_USE = "E5011"
+    """A use line that is not @use name value...;."""
+    EXTENSION_BLOCK_NOT_SET = "E5012"
+    """An extension line whose block holds a line other than @set."""
+    EXPANDED_NESTING_TOO_DEEP = "E5013"
+    """Blocks and lists nested deeper than 256 levels after expansion (2.5): a directive whose block or values, or a
+    set, use or extension line whose values, would sit deeper. The statement is unreadable there and its block is
+    not walked.
+    """
+
+
+MESSAGES: Final[Mapping[DiagnosticCode, str]] = MappingProxyType(
+    {
+        DiagnosticCode.UNTERMINATED_STRING: "unterminated string",
+        DiagnosticCode.UNEXPECTED_CHARACTER: "unexpected character",
+        DiagnosticCode.LONE_DOLLAR: "'$' must be followed by a variable name",
+        DiagnosticCode.BAD_ESCAPE: "unknown escape",
+        DiagnosticCode.UNEXPECTED_TOKEN: "unexpected token",
+        DiagnosticCode.EXPECTED_CLOSING_BRACE: "expected '}' to close the block",
+        DiagnosticCode.EXPECTED_CLOSING_BRACKET: "unmatched bracket",
+        DiagnosticCode.BAD_SLICE: "malformed slice",
+        DiagnosticCode.VALUES_TOUCH: "values must be separated by a space or comment",
+        DiagnosticCode.NESTING_TOO_DEEP: f"blocks and lists nest deeper than {MAX_NESTING} levels",
+        DiagnosticCode.INCLUDE_NOT_FOUND: "include not found",
+        DiagnosticCode.INCLUDE_RESOLVER_FAILED: "include resolver failed",
+        DiagnosticCode.INCLUDE_BAD_PATH: "include takes one quoted path",
+        DiagnosticCode.INCLUDE_MATCHED_NOTHING: "include matched nothing",
+        DiagnosticCode.EXTENSION_FAILED: "extension failed",
+        DiagnosticCode.UNREAD_COPY: "extension copy not read yet",
+        DiagnosticCode.UNKNOWN_EXTENSION: "no extension for this @name",
+        DiagnosticCode.NON_INTEGER_BOUND: "bound is not an integer",
+        DiagnosticCode.WRONG_VALUE_KIND: "wrong kind of value",
+        DiagnosticCode.NOT_A_NUMBER: "not a number",
+        DiagnosticCode.NOT_AN_INTEGER: "not an integer",
+        DiagnosticCode.NOT_A_BOOLEAN: "not true or false",
+        DiagnosticCode.BAD_SLICE_NAME: "slice name is not one word",
+        DiagnosticCode.UNKNOWN_VARIABLE: "unknown variable",
+        DiagnosticCode.VARIABLE_SET_TWICE: "variable set twice in one block",
+        DiagnosticCode.UNKNOWN_SNIPPET: "unknown snippet",
+        DiagnosticCode.SNIPPET_ARITY: "wrong number of values for the snippet",
+        DiagnosticCode.SNIPPET_DEFINED_TWICE: "snippet defined twice in one block",
+        DiagnosticCode.EXPANSION_CYCLE: "expansion reaches itself",
+        DiagnosticCode.EXPANSION_TOO_DEEP: "expansion nests too deep",
+        DiagnosticCode.TOO_MANY_DIRECTIVES: "too many directives after expansion",
+        DiagnosticCode.BAD_SET: "write @set $name value...;",
+        DiagnosticCode.BAD_SNIPPET: "write @snippet name $param... { ... }",
+        DiagnosticCode.BAD_USE: "write @use name value...;",
+        DiagnosticCode.EXTENSION_BLOCK_NOT_SET: "an extension's block holds only @set lines",
+        DiagnosticCode.EXPANDED_NESTING_TOO_DEEP: f"expanded blocks and lists nest deeper than {MAX_EXPANDED_NESTING}",
+    }
+)
+"""The base message of each code (for people, not part of the contract)."""
+
+
+@dataclass(frozen=True, slots=True)
+class CodeFacts:
+    """What the registry says of one code: its spec name, owning layer, who finds it, the reason it gives, and its
+    severity (its letter's: spec 2.3)."""
+
+    name: str
+    layer: str
+    found_by: tuple[str, ...]
+    reason: UnreadableReason | None
+    severity: Severity
+
+
+CODE_FACTS: Final[Mapping[DiagnosticCode, CodeFacts]] = MappingProxyType(
+    {
+        DiagnosticCode.UNTERMINATED_STRING: CodeFacts(
+            "unterminated string", "syntax", ("parse",), UnreadableReason.SYNTAX, Severity.ERROR
+        ),
+        DiagnosticCode.UNEXPECTED_CHARACTER: CodeFacts(
+            "unexpected character", "syntax", ("parse",), UnreadableReason.SYNTAX, Severity.ERROR
+        ),
+        DiagnosticCode.LONE_DOLLAR: CodeFacts(
+            "lone dollar", "syntax", ("parse",), UnreadableReason.SYNTAX, Severity.ERROR
+        ),
+        DiagnosticCode.BAD_ESCAPE: CodeFacts(
+            "bad escape", "syntax", ("parse",), UnreadableReason.SYNTAX, Severity.ERROR
+        ),
+        DiagnosticCode.UNEXPECTED_TOKEN: CodeFacts(
+            "unexpected token", "syntax", ("parse",), UnreadableReason.SYNTAX, Severity.ERROR
+        ),
+        DiagnosticCode.EXPECTED_CLOSING_BRACE: CodeFacts(
+            "expected closing brace", "syntax", ("parse",), UnreadableReason.SYNTAX, Severity.ERROR
+        ),
+        DiagnosticCode.EXPECTED_CLOSING_BRACKET: CodeFacts(
+            "expected closing bracket", "syntax", ("parse",), UnreadableReason.SYNTAX, Severity.ERROR
+        ),
+        DiagnosticCode.BAD_SLICE: CodeFacts("bad slice", "syntax", ("parse",), UnreadableReason.SYNTAX, Severity.ERROR),
+        DiagnosticCode.VALUES_TOUCH: CodeFacts(
+            "values touch", "syntax", ("parse",), UnreadableReason.SYNTAX, Severity.ERROR
+        ),
+        DiagnosticCode.NESTING_TOO_DEEP: CodeFacts(
+            "nesting too deep", "syntax", ("parse", "edit"), UnreadableReason.SYNTAX, Severity.ERROR
+        ),
+        DiagnosticCode.INCLUDE_NOT_FOUND: CodeFacts(
+            "include not found", "written", ("load and read",), UnreadableReason.EXTENSION, Severity.ERROR
+        ),
+        DiagnosticCode.INCLUDE_RESOLVER_FAILED: CodeFacts(
+            "include resolver failed", "written", ("load and read",), UnreadableReason.EXTENSION, Severity.ERROR
+        ),
+        DiagnosticCode.INCLUDE_BAD_PATH: CodeFacts(
+            "include bad path", "include", ("include extension",), UnreadableReason.EXTENSION, Severity.ERROR
+        ),
+        DiagnosticCode.INCLUDE_MATCHED_NOTHING: CodeFacts(
+            "include matched nothing", "written", ("load and read",), None, Severity.WARNING
+        ),
+        DiagnosticCode.EXTENSION_FAILED: CodeFacts(
+            "extension failed", "written", ("load and read",), UnreadableReason.EXTENSION, Severity.ERROR
+        ),
+        DiagnosticCode.UNREAD_COPY: CodeFacts(
+            "unread copy", "written", ("low level",), UnreadableReason.UNREAD, Severity.ERROR
+        ),
+        DiagnosticCode.UNKNOWN_EXTENSION: CodeFacts(
+            "unknown extension", "written", ("low level",), UnreadableReason.EXTENSION, Severity.ERROR
+        ),
+        DiagnosticCode.NON_INTEGER_BOUND: CodeFacts(
+            "non-integer bound", "written", ("low level",), UnreadableReason.VALUE, Severity.ERROR
+        ),
+        DiagnosticCode.WRONG_VALUE_KIND: CodeFacts("wrong value kind", "written", ("readers",), None, Severity.ERROR),
+        DiagnosticCode.NOT_A_NUMBER: CodeFacts("not a number", "written", ("readers",), None, Severity.ERROR),
+        DiagnosticCode.NOT_AN_INTEGER: CodeFacts("not an integer", "written", ("readers",), None, Severity.ERROR),
+        DiagnosticCode.NOT_A_BOOLEAN: CodeFacts("not a boolean", "written", ("readers",), None, Severity.ERROR),
+        DiagnosticCode.BAD_SLICE_NAME: CodeFacts(
+            "bad slice name", "written", ("low level",), UnreadableReason.VALUE, Severity.ERROR
+        ),
+        DiagnosticCode.UNKNOWN_VARIABLE: CodeFacts(
+            "unknown variable", "written", ("low level",), UnreadableReason.EXPANSION, Severity.ERROR
+        ),
+        DiagnosticCode.VARIABLE_SET_TWICE: CodeFacts(
+            "variable set twice", "written", ("low level", "edit"), UnreadableReason.EXPANSION, Severity.ERROR
+        ),
+        DiagnosticCode.UNKNOWN_SNIPPET: CodeFacts(
+            "unknown snippet", "written", ("low level",), UnreadableReason.EXPANSION, Severity.ERROR
+        ),
+        DiagnosticCode.SNIPPET_ARITY: CodeFacts(
+            "snippet arity", "written", ("low level",), UnreadableReason.EXPANSION, Severity.ERROR
+        ),
+        DiagnosticCode.SNIPPET_DEFINED_TWICE: CodeFacts(
+            "snippet defined twice", "written", ("low level", "edit"), UnreadableReason.EXPANSION, Severity.ERROR
+        ),
+        DiagnosticCode.EXPANSION_CYCLE: CodeFacts(
+            "expansion cycle", "written", ("low level",), UnreadableReason.EXPANSION, Severity.ERROR
+        ),
+        DiagnosticCode.EXPANSION_TOO_DEEP: CodeFacts(
+            "expansion too deep", "written", ("low level",), UnreadableReason.EXPANSION, Severity.ERROR
+        ),
+        DiagnosticCode.TOO_MANY_DIRECTIVES: CodeFacts(
+            "too many directives", "written", ("low level",), UnreadableReason.EXPANSION, Severity.ERROR
+        ),
+        DiagnosticCode.BAD_SET: CodeFacts(
+            "bad set", "written", ("low level", "edit"), UnreadableReason.EXPANSION, Severity.ERROR
+        ),
+        DiagnosticCode.BAD_SNIPPET: CodeFacts(
+            "bad snippet", "written", ("low level", "edit"), UnreadableReason.EXPANSION, Severity.ERROR
+        ),
+        DiagnosticCode.BAD_USE: CodeFacts(
+            "bad use", "written", ("low level", "edit"), UnreadableReason.EXPANSION, Severity.ERROR
+        ),
+        DiagnosticCode.EXTENSION_BLOCK_NOT_SET: CodeFacts(
+            "extension block not set", "written", ("low level",), UnreadableReason.EXTENSION, Severity.ERROR
+        ),
+        DiagnosticCode.EXPANDED_NESTING_TOO_DEEP: CodeFacts(
+            "expanded nesting too deep", "written", ("low level",), UnreadableReason.EXPANSION, Severity.ERROR
+        ),
+    }
+)
+"""Each code's facts."""
+
+
+@dataclass(frozen=True, slots=True)
+class Described:
+    """One diagnostic's code, message and reason, built from the registry."""
+
+    code: DiagnosticCode
+    message: str
+    reason: UnreadableReason | None
+
+
+def describe(code: DiagnosticCode, detail: str | None = None, /) -> Described:
+    """The typed diagnostic constructor (spec/codegen.md section 4): a raise site names the code and its detail, and
+    the message and reason come from the registry, so they cannot disagree with it. ``detail`` follows ': '."""
+    base = MESSAGES[code]
+    message = base if detail is None else f"{base}: {detail}"
+    return Described(code, message, CODE_FACTS[code].reason)

knobly/_api/docs.py

@@ -0,0 +1,29 @@
+"""Generated by tools/gen-api.py from spec/schema/; do not edit, and never commit.
+
+Source: spec/schema/api.json "free functions": the docs of the public functions and constructors."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Final
+
+FUNCTIONS: Final[Mapping[str, tuple[str, ...]]] = MappingProxyType(
+    {
+        "knobly": ("knobly._api.io.IoFunctions", "knobly._api.shared.SharedFunctions"),
+        "knobly.files": ("knobly._api.io.FilesFunctions",),
+        "knobly.include": ("knobly._api.written.IncludeFunctions",),
+        "knobly.rendered": ("knobly._api.rendered.RenderedFunctions",),
+        "knobly.syntax": ("knobly._api.syntax.SyntaxFunctions",),
+        "knobly.written": ("knobly._api.written.WrittenFunctions",),
+    }
+)
+"""Each public module's <Module>Functions Protocols: each of its functions takes its doc from one."""
+
+CONSTRUCTORS: Final[Mapping[str, str]] = MappingProxyType(
+    {
+        "knobly.Diagnostics": "knobly._api.shared.DiagnosticsConstructor",
+        "knobly.written.Processor": "knobly._api.written.ProcessorConstructor",
+    }
+)
+"""Each constructed class's <Class>Constructor Protocol: its __init__ takes the doc of __call__."""

knobly/_api/errors.py

@@ -0,0 +1,88 @@
+"""Generated by tools/gen-api.py from spec/schema/; do not edit, and never commit.
+
+Source: spec/schema/api.json "error groups"."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    import knobly
+
+
+class KnoblyError(Exception):
+    """Never by itself: the base class of every expected-outcome class, so one except or catch clause catches every
+    outcome the input or the outside world decides, and no program bug.
+    """
+
+
+class DiagnosticError(KnoblyError):
+    """Raised when a reader is given a value of the wrong kind or spelling, or a program's error(...); carries one
+    located diagnostic as 'diagnostic'. An expected outcome.
+    """
+
+    diagnostic: knobly.LocatedDiagnostic
+
+    def __init__(self, diagnostic: knobly.LocatedDiagnostic) -> None:
+        super().__init__(f"{diagnostic.message}")
+        self.diagnostic = diagnostic
+
+
+class ReadError(KnoblyError):
+    """Raised when load cannot resolve the root path to exactly one file, or cannot read it. No diagnostic and no
+    code. An expected outcome.
+    """
+
+    paths: tuple[str, ...]
+
+    def __init__(self, message: str, paths: Sequence[str]) -> None:
+        super().__init__(message)
+        self.paths = tuple(paths)
+
+
+class BadTextError(KnoblyError):
+    """Raised when the text given to an edit, or an override's text, is not what that place takes, or the document
+    after the edit would nest deeper than MAX_NESTING; 'diagnostics' are located in that text, in the binding's
+    string unit, and its message is built from them. An expected outcome.
+    """
+
+    diagnostics: tuple[knobly.Diagnostic, ...]
+
+    def __init__(self, diagnostics: Sequence[knobly.Diagnostic]) -> None:
+        super().__init__(f"bad text: {'; '.join(str(d) for d in diagnostics)}")
+        self.diagnostics = tuple(diagnostics)
+
+
+class SaveError(KnoblyError):
+    """Raised when the writer failed. An expected outcome."""
+
+    paths: tuple[str, ...]
+
+    def __init__(self, message: str, paths: Sequence[str]) -> None:
+        super().__init__(message)
+        self.paths = tuple(paths)
+
+
+class LostUpdateError(SaveError):
+    """Raised when a file the save would write changed since it was read or last saved: its current text differs from
+    its saved text. Check lost updates raises it inside every writer, and save passes it on unchanged. An expected
+    outcome. Paths are only the conflicting files, in batch order.
+    """
+
+    def __init__(self, paths: Sequence[str]) -> None:
+        super().__init__(f"lost update: changed since read: {', '.join(paths)}", paths)
+
+
+class DetachedError(ReferenceError):
+    """Raised when any member but kind of a detached handle is used. A program bug."""
+
+
+def argument_type_message(member: str, parameter: str, got: str, /) -> str:
+    """The argument type error's message: the one helper every member that takes text calls."""
+    return (
+        f"{member}() argument '{parameter}' must be str, not {got}; knobly edits take config text: "
+        "quote() a program string, text() one already written as knobly text, str() a number "
+        "first"
+    )