structile 6.0.0__py3-none-any.whl

structile/interpreters.py

@@ -0,0 +1,430 @@
+"""Interpreter registry + selection — markup (XML, HTML included) and any
+other text format alike — see README.md's "Custom formats via an
+interpreter" section and docs/advanced.md's "Interpreter selection" section
+for the full picture.
+
+An interpreter is caller-supplied JS: `interpretXML(xmlDocument)` (optionally
+`serializeXML(value)`) for markup, given a DOM document; or `interpretText(text)`
+(optionally `serializeText(value)`) for any other format, given the raw text
+directly — see interpreters/generic_xml.js / interpreters/html.js for the
+former and interpreters/generic_ini.js for the latter, and their header
+comments for the "fail loudly on the wrong shape" contract this module's
+selection depends on. `xmlDocument` is a REAL browser DOM when open()/
+diff() resolve this client-side (structile.html's own DOMParser);
+when this module runs an interpreter itself (`run_interpreter_source`, used
+by `convert()` and whenever more than one candidate needs disambiguating —
+see `select_interpreter` below), it's a much smaller DOM-lite object built
+from a Python-parsed tree instead (see dom_lite.py/dom_lite.js) — no Node.js,
+no jsdom, just an embedded JS engine (`mini-racer`).
+
+This module is generic across every extension AND across which contract an
+interpreter uses, on purpose: HTML isn't treated as a different *kind* of
+thing from XML anywhere below, only as a different DOMParser *mode*
+(`MARKUP_FORMATS`, the one place that distinction exists at all) — the
+registry, candidate-list resolution, and try-in-order selection never
+branch on "is this XML or HTML", let alone "is this markup at all". Which
+of the two JS contracts actually applies is decided client-side
+(structile.html's `tryInterpreterCandidates`/`structuredFormat`),
+never here.
+"""
+from __future__ import annotations
+
+import json
+import pathlib
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from ._dom_lite import build_document_payload
+from ._log import logger
+from ._paths import InterpreterSource, read_interpreter
+
+# A single candidate: a path, a bare str (a path if it names an existing
+# file, else literal JS source text — see read_interpreter), or an explicit
+# InterpreterSource (source text supplied directly, e.g. from an installed
+# plugin package — see _paths.py's InterpreterSource docstring).
+InterpreterCandidate = Union[str, pathlib.Path, InterpreterSource]
+# A single candidate, or a list of candidates tried in order for ONE format.
+InterpreterCandidateOrList = Union[InterpreterCandidate, Sequence[InterpreterCandidate]]
+# The above, OR a dict keyed by file extension (".xml", ".html", ...) — each
+# entry tried only for a file/format matching THAT extension, never mixed
+# with another entry's candidates (see resolve_candidates /
+# select_interpreter_any_format).
+InterpreterSpec = Union[InterpreterCandidateOrList, Dict[str, InterpreterCandidateOrList]]
+
+# The only xml/html-specific knowledge in this whole module: which DOMParser
+# mode a markup extension implies. A file extension not listed here can
+# still be used for ANY format — markup (pass format="xml"/"html"
+# explicitly) or otherwise (open() infers a format straight from the
+# extension once an interpreter is attached to it, e.g. ".ini" -> "ini") —
+# this dict only grows the set of extensions a format is inferred from via
+# the markup/DOM path specifically; it's not a gate on what's usable at all.
+MARKUP_FORMATS: Dict[str, str] = {".xml": "xml", ".html": "html", ".htm": "html"}
+# The reverse: which extension to use as a registry lookup key when only a
+# format (not a real file/extension) is known — e.g. structile.open(xml_text,
+# format="xml", ...) with no path to infer an extension from.
+CANONICAL_EXT_FOR_FORMAT: Dict[str, str] = {"xml": ".xml", "html": ".html"}
+
+_DOM_LITE_JS_PATH = pathlib.Path(__file__).resolve().parent / "dom_lite.js"
+_SET_MARK = "__structile_set__"
+
+_registry: Dict[str, InterpreterSpec] = {}
+
+
+def _normalize_ext(ext: str) -> str:
+    ext = ext.lower()
+    return ext if ext.startswith(".") else "." + ext
+
+
+# ---- registry: set up once at import time --------------------------------
+def register_interpreter(ext: str, interpreter: Optional[InterpreterSpec]) -> None:
+    """Register one or more interpreters for a file extension, once, at
+    import time — so later `structile.open(path)` / `convert(path, ...)` calls
+    don't need `interpreter=` at all:
+
+        structile.register_interpreter(".xml", "interpreters/generic_xml.js")
+        structile.register_interpreter(".html", ["interpreters/html.js", "interpreters/generic_xml.js"])
+
+    `interpreter` is a single path/raw JS source/`InterpreterSource`, or a
+    list/tuple of candidates tried in order — the first one that
+    successfully parses the data wins (see `select_interpreter`). `None`
+    unregisters `ext` (same as `unregister_interpreter`).
+
+    A direct call here always wins over a plugin's own registration for the
+    same `ext` (see `_plugins.py`'s precedence rule) — calling this
+    "forgets" any plugin ownership of `ext` recorded so far, so a later
+    `load_plugins(force=True)` can't silently re-overwrite what was just set
+    directly.
+    """
+    ext = _normalize_ext(ext)
+    from . import _plugins as _plugins_mod
+
+    _plugins_mod._plugin_owner_by_ext.pop(ext, None)
+    if interpreter is None:
+        _registry.pop(ext, None)
+        logger.debug("structile: unregistered interpreter(s) for %r", ext)
+        return
+    _registry[ext] = interpreter
+    logger.debug("structile: registered interpreter(s) for %r: %r", ext, interpreter)
+
+
+def unregister_interpreter(ext: str) -> None:
+    """Remove any interpreter(s) registered for `ext`."""
+    register_interpreter(ext, None)
+
+
+def get_registered_interpreter(ext: str) -> Optional[InterpreterSpec]:
+    """The raw spec registered for `ext` — a single candidate, a list, or
+    `None` if nothing's registered. See `resolve_candidates` for the
+    normalized list form callers actually use.
+
+    Triggers entry-point plugin discovery first (lazy, at most once per
+    process — see `_plugins.load_plugins`): every renderer's resolution
+    path (`open()`/`diff()`'s markup-mode detection, `resolve_candidates`'s
+    own registry fallback below, `convert()`'s format inference) reaches the
+    registry through this one function, so a plugin's registration becomes
+    visible here with no import of the plugin package and no explicit
+    registration call needed.
+    """
+    from . import _plugins as _plugins_mod
+
+    _plugins_mod.load_plugins()
+    return _registry.get(_normalize_ext(ext))
+
+
+def resolve_candidates(explicit: Optional[InterpreterSpec], ext: Optional[str]) -> List[InterpreterCandidate]:
+    """Normalize `interpreter=` (explicit, wins if given) or the registry
+    entry for `ext` (fallback — `ext` may be `None` when there's no file/
+    extension to key off of, e.g. a literal markup string) into a plain
+    list of candidates, in the order they should be tried. Empty means
+    "nothing available for this format".
+
+    If `explicit` is a `dict` (keyed by file extension — e.g.
+    `{".xml": [...], ".html": [...]}`), only the entry for THIS `ext` is
+    used — candidates registered for a different extension are never tried
+    against a file/format they weren't meant for. A `dict` with no entry
+    for `ext` (or given with `ext=None`) resolves to nothing, same as no
+    interpreter at all — see `select_interpreter_any_format` for the
+    "format itself is unknown, try every entry" case this deliberately
+    doesn't cover.
+    """
+    if isinstance(explicit, dict):
+        normalized = {_normalize_ext(k): v for k, v in explicit.items()}
+        spec = normalized.get(_normalize_ext(ext)) if ext else None
+    else:
+        spec = explicit if explicit is not None else (get_registered_interpreter(ext) if ext else None)
+    if spec is None:
+        return []
+    if isinstance(spec, (str, pathlib.Path, InterpreterSource)):
+        return [spec]
+    return list(spec)
+
+
+# ---- running one candidate via an embedded JS engine (parse or serialize) -
+def _mark_sets(value: Any) -> Any:
+    """JSON has no Set — mark one the same reversible way dom_lite.js's
+    __structileMarkSets/__structileUnmarkSets do on its side, so `value instanceof Set`
+    still works inside the interpreter."""
+    if isinstance(value, (set, frozenset)):
+        try:
+            items = sorted(value)
+        except TypeError:
+            items = list(value)
+        return {_SET_MARK: [_mark_sets(v) for v in items]}
+    if isinstance(value, (list, tuple)):
+        return [_mark_sets(v) for v in value]
+    if isinstance(value, dict):
+        return {k: _mark_sets(v) for k, v in value.items()}
+    return value
+
+
+def _unmark_sets(value: Any) -> Any:
+    if isinstance(value, dict) and list(value.keys()) == [_SET_MARK] and isinstance(value[_SET_MARK], list):
+        return {_unmark_sets(v) for v in value[_SET_MARK]}
+    if isinstance(value, list):
+        return [_unmark_sets(v) for v in value]
+    if isinstance(value, dict):
+        return {k: _unmark_sets(v) for k, v in value.items()}
+    return value
+
+
+def _mini_racer_available() -> bool:
+    try:
+        import py_mini_racer  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def run_interpreter_source(
+    op: str,
+    interpreter_source: str,
+    fmt: str,
+    *,
+    text: Optional[str] = None,
+    value: Any = None,
+) -> Any:
+    """Run one already-resolved interpreter script, as actual JS, inside an
+    embedded V8 engine (the `mini-racer` package — see dom_lite.js/
+    _dom_lite.py) — the only way to either get a real parsed/serialized
+    result out of an interpreter in Python (used by `convert()`), or to
+    test whether a *candidate* interpreter accepts a given document at all
+    (used by `select_interpreter` below). No Node.js, no jsdom, no
+    subprocess: for `fmt` `"xml"`/`"html"` the DOM handed to `interpretXML`
+    is built directly from a Python-parsed tree (stdlib `ElementTree`/
+    `html.parser` — see dom_lite.py) rather than a real browser DOM; see
+    dom_lite.js's header comment for exactly what subset of the DOM this
+    provides. Raises `RuntimeError` if the `mini-racer` package is missing,
+    if `text` isn't well-formed enough to parse as `fmt` (xml only — HTML5
+    parsing never rejects anything, matching a real browser's own lenient
+    behavior), or if the interpreter itself fails (throws, or has no
+    matching function for `op`)."""
+    if not _mini_racer_available():
+        raise RuntimeError(
+            "structile: this needs the 'mini-racer' package (run `pip install "
+            "mini-racer`) — an optional capability, not a hard dependency of "
+            'structile itself. See README.md\'s "Custom formats via an '
+            'interpreter" section.'
+        )
+    from py_mini_racer import JSEvalException, MiniRacer
+
+    is_markup = fmt in ("xml", "html")
+    doc_payload = build_document_payload(text, fmt) if is_markup and op == "parse" else None
+    marked_value_json = json.dumps(_mark_sets(value)) if op == "serialize" else None
+    dom_lite_js = _DOM_LITE_JS_PATH.read_text(encoding="utf-8")
+
+    # Mirrors buildInterpreterFns's function-extraction in
+    # structile.html, and (before it) convert_runner.js's `new
+    # Function(...)` call — same execution shape regardless of which of the
+    # three actually drives an interpreter script. The whole thing is one
+    # try/catch so an interpreter's own thrown Error (the "fail loudly on
+    # the wrong shape" contract every bundled interpreter documents) comes
+    # back as a clean {ok:false, error} instead of a noisy JS stack trace.
+    driver = f"""
+(function(){{
+  try {{
+    var __structileFns = {{
+      interpretXML: (typeof interpretXML === "function") ? interpretXML : null,
+      serializeXML: (typeof serializeXML === "function") ? serializeXML : null,
+      interpretText: (typeof interpretText === "function") ? interpretText : null,
+      serializeText: (typeof serializeText === "function") ? serializeText : null,
+    }};
+    var __structileResult;
+    if ({json.dumps(op)} === "parse") {{
+      if ({json.dumps(is_markup)}) {{
+        if (!__structileFns.interpretXML) throw new Error("Interpreter script must define function interpretXML(xmlDocument)");
+        __structileResult = __structileFns.interpretXML(__structileBuildDocument({json.dumps(doc_payload)}));
+      }} else {{
+        if (!__structileFns.interpretText) throw new Error("Interpreter script must define function interpretText(text)");
+        __structileResult = __structileFns.interpretText({json.dumps(text)});
+      }}
+      return JSON.stringify({{ ok: true, value: __structileMarkSets(__structileResult) }});
+    }} else {{
+      var __structileValue = __structileUnmarkSets(JSON.parse({json.dumps(marked_value_json)}));
+      if ({json.dumps(is_markup)}) {{
+        if (!__structileFns.serializeXML) throw new Error("Interpreter script has no serializeXML — can't serialize to this format");
+        __structileResult = __structileFns.serializeXML(__structileValue);
+      }} else {{
+        if (!__structileFns.serializeText) throw new Error("Interpreter script has no serializeText — can't serialize to this format");
+        __structileResult = __structileFns.serializeText(__structileValue);
+      }}
+      return JSON.stringify({{ ok: true, value: __structileResult }});
+    }}
+  }} catch (e) {{
+    return JSON.stringify({{ ok: false, error: String((e && e.message) || e) }});
+  }}
+}})()
+"""
+
+    logger.debug("structile: running interpreter via mini-racer (%s, format=%r)", op, fmt)
+    mr = MiniRacer()  # fresh isolate per call — candidates never share JS state
+    try:
+        raw = mr.eval(dom_lite_js + "\n" + interpreter_source + "\n" + driver)
+    except JSEvalException as e:
+        raise RuntimeError(f"structile: interpreter script threw while loading: {e}") from e
+    outcome = json.loads(raw)
+    if not outcome["ok"]:
+        raise RuntimeError(outcome["error"])
+    return _unmark_sets(outcome["value"]) if op == "parse" else outcome["value"]
+
+
+@dataclass
+class SelectedInterpreter:
+    candidate: InterpreterCandidate
+    source: str
+    result: Any  # the parsed/serialized value if it was actually run to select it, else None
+
+
+def select_interpreter(
+    candidates: Sequence[InterpreterCandidate],
+    fmt: str,
+    *,
+    op: str = "parse",
+    text: Optional[str] = None,
+    value: Any = None,
+    run: bool = True,
+) -> SelectedInterpreter:
+    """Pick the interpreter that actually handles this data out of
+    `candidates`, tried in order — the first one that doesn't raise wins
+    (see interpreters/generic_xml.js's header comment for why a *correct*
+    interpreter is expected to throw on the wrong shape rather than return
+    something meaningless).
+
+    A single candidate is returned untested when `run=False` — the
+    `open()` `widget`/`browser`/`file` renderers only ever forward
+    the interpreter source to the viewer, which does the real parse
+    client-side, so with nothing to disambiguate there's no reason to run
+    anything here either. `convert()` always needs the actual parsed/
+    serialized Python value back, so it passes `run=True` unconditionally —
+    even a single candidate has to actually run there. Whenever there's
+    more than one candidate, disambiguating them always requires actually
+    running each in turn (via mini-racer), regardless of `run`.
+
+    Raises `ValueError` if `candidates` is empty, or `RuntimeError` (after
+    trying every candidate, and naming how each one failed) if none of them
+    accept the data.
+    """
+    if not candidates:
+        raise ValueError(
+            f"structile: no interpreter registered or provided for {fmt!r} data — pass interpreter=, "
+            "or call register_interpreter(ext, ...) once at import time"
+        )
+    if len(candidates) == 1 and not run:
+        source = read_interpreter(candidates[0])
+        logger.debug("structile: single interpreter candidate for %r, using it without testing", fmt)
+        return SelectedInterpreter(candidate=candidates[0], source=source, result=None)
+
+    # From here on every candidate actually has to run (run=True, or more
+    # than one candidate needs disambiguating) — checked once up front so a
+    # missing 'mini-racer' package surfaces as ONE clear error, not this same
+    # message repeated (and then buried in an aggregate "none of N worked")
+    # once per candidate as run_interpreter_source's own identical check
+    # would give.
+    if not _mini_racer_available():
+        reason = (
+            f"choosing between {len(candidates)} interpreter candidates"
+            if len(candidates) > 1
+            else "running this interpreter"
+        )
+        raise RuntimeError(
+            f"structile: {reason} for {fmt!r} data needs the 'mini-racer' package "
+            "(run `pip install mini-racer`) — an optional capability, not a hard "
+            'dependency of structile itself. See README.md\'s "Custom formats via '
+            'an interpreter" section.'
+        )
+    if len(candidates) > 1:
+        logger.debug("structile: %d interpreter candidates for %r, trying each in order", len(candidates), fmt)
+
+    errors = []
+    for i, candidate in enumerate(candidates):
+        source = read_interpreter(candidate)
+        try:
+            result = run_interpreter_source(op, source, fmt, text=text, value=value)
+        except RuntimeError as e:
+            logger.warning("structile: interpreter candidate %r failed (%s), trying the next one", candidate, e)
+            errors.append(f"{candidate}: {e}")
+            continue
+        if len(candidates) > 1:
+            logger.info("structile: selected interpreter candidate %r (%d of %d)", candidate, i + 1, len(candidates))
+        return SelectedInterpreter(candidate=candidate, source=source, result=result)
+
+    logger.error("structile: no interpreter candidate could handle this %r data (tried %d)", fmt, len(candidates))
+    raise RuntimeError(
+        f"structile: none of {len(candidates)} interpreter candidate(s) could handle this {fmt} data:\n"
+        + "\n".join(f"  - {e}" for e in errors)
+    )
+
+
+def select_interpreter_any_format(
+    interpreter_dict: Dict[str, InterpreterCandidateOrList],
+    *,
+    op: str = "parse",
+    text: Optional[str] = None,
+    value: Any = None,
+) -> tuple[str, SelectedInterpreter]:
+    """Like `select_interpreter`, but for when the *format* itself isn't
+    known ahead of time either — no `format=`, no path to infer an
+    extension from. Tries every `(ext, candidates)` entry in
+    `interpreter_dict` in turn (each under its own format — `MARKUP_FORMATS`'
+    DOM mode for a markup extension, or the extension itself for anything
+    else, e.g. `.ini` -> `"ini"`), stopping at the first candidate — from
+    any entry — that doesn't raise. Returns `(fmt, SelectedInterpreter)`
+    since the winning format wasn't known ahead of time.
+
+    Always actually runs candidates (needs the 'mini-racer' package) — unlike
+    `select_interpreter`'s `run=False` escape hatch (a single, *known*-
+    format candidate can be forwarded to a browser untested, since there's
+    nothing to disambiguate), determining which of several *formats* even
+    applies is inherently a "parse it to find out" question, so there's no
+    untested shortcut here.
+
+    Raises `ValueError` if `interpreter_dict` is empty, `RuntimeError`
+    (naming every attempt, across every extension) if nothing in it can
+    handle the data.
+    """
+    if not interpreter_dict:
+        raise ValueError(
+            "structile: interpreter dict is empty — nothing to try (pass at least one "
+            '{"ext": interpreter} entry)'
+        )
+    errors: List[str] = []
+    tried_any = False
+    for ext, spec in interpreter_dict.items():
+        ext_norm = _normalize_ext(ext)
+        fmt = MARKUP_FORMATS.get(ext_norm) or ext_norm.lstrip(".")
+        candidates = resolve_candidates(spec, ext_norm)
+        if not candidates:
+            continue
+        tried_any = True
+        try:
+            selected = select_interpreter(candidates, fmt, op=op, text=text, value=value, run=True)
+        except (ValueError, RuntimeError) as e:
+            errors.append(f"{ext} ({fmt}): {e}")
+            continue
+        return fmt, selected
+    if not tried_any and not errors:
+        raise ValueError(f"structile: no usable interpreter entries in {interpreter_dict!r}")
+    logger.error("structile: no interpreter (across %d extension(s)) could handle this data", len(interpreter_dict))
+    raise RuntimeError(
+        f"structile: none of the provided interpreters (across {len(interpreter_dict)} extension(s)) "
+        "could handle this data:\n" + "\n".join(f"  - {e}" for e in errors)
+    )