structile 6.0.0__py3-none-any.whl

structile/_dom_lite.py

@@ -0,0 +1,128 @@
+"""Pure-Python DOM-lite tree builder for structile.convert()'s xml/html
+interpreter path (see interpreters.py's run_interpreter_source and
+dom_lite.js). Replaces jsdom's real DOM with the small subset every bundled
+interpreter (and the documented contract in README.md's "Custom formats via
+an interpreter" section) actually uses at the element level — tagName,
+getAttribute, children, textContent — plus documentElement/doctype/body at
+the document level.
+
+NOT a general DOM implementation: no namespaces, no siblings, no comments/
+CDATA nodes, no querySelector beyond a bare tag name (see dom_lite.js). A
+custom interpreter that needs more than this documented subset isn't
+supported by convert()'s Node-free path; structile.html's own
+browser-side DOMParser (used by every renderer, including widget) is
+unaffected by any of this and still hands interpreters a real DOM.
+"""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from html.parser import HTMLParser
+from typing import Any, Dict, List, Optional
+
+# Elements a real HTML5 parser never expects a closing tag for — without
+# this, a bare "<br>" would swallow every sibling after it as its children,
+# since handle_starttag would push it onto the open-element stack forever.
+_VOID_HTML_TAGS = {
+    "area", "base", "br", "col", "embed", "hr", "img", "input",
+    "link", "meta", "param", "source", "track", "wbr",
+}
+
+
+def build_document_payload(text: str, fmt: str) -> Dict[str, Any]:
+    """`fmt` is "xml" or "html". Returns the {"root", "body", "hasDoctype"}
+    payload dom_lite.js's __structileBuildDocument expects. Raises `RuntimeError`
+    on genuinely malformed markup — xml only, matching a real DOMParser:
+    HTML5 parsing never rejects anything (see interpreters/html.js's own
+    header comment), so `fmt == "html"` never raises here either."""
+    return _build_html_payload(text) if fmt == "html" else _build_xml_payload(text)
+
+
+def _build_xml_payload(text: str) -> Dict[str, Any]:
+    try:
+        root = ET.fromstring(text)
+    except ET.ParseError as e:
+        raise RuntimeError(f"Could not parse XML: {e}") from e
+    return {"root": _xml_node(root), "body": None, "hasDoctype": False}
+
+
+def _xml_node(el: ET.Element) -> Dict[str, Any]:
+    # Built bottom-up in one pass: each child's own "text" is already its
+    # full recursive textContent by the time it comes back, so the parent
+    # just appends that plus the child's own tail (the text between that
+    # child's closing tag and the next sibling) rather than re-walking the
+    # whole subtree again.
+    children: List[Dict[str, Any]] = []
+    text_parts = [el.text or ""]
+    for child_el in el:
+        child_node = _xml_node(child_el)
+        children.append(child_node)
+        text_parts.append(child_node["text"])
+        text_parts.append(child_el.tail or "")
+    return {"tag": el.tag, "attrs": dict(el.attrib), "children": children, "text": "".join(text_parts)}
+
+
+class _HTMLTreeBuilder(HTMLParser):
+    """Builds a plain tag/attrs/children tree from arbitrary (possibly
+    malformed) HTML — deliberately lenient, same as a real browser's HTML5
+    parser: an unmatched end tag is ignored rather than raising, and a void
+    element (_VOID_HTML_TAGS) never expects one at all."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.has_doctype = False
+        self._root: Dict[str, Any] = {"tag": "#document", "attrs": {}, "children": [], "text": ""}
+        self._stack: List[Dict[str, Any]] = [self._root]
+
+    def handle_decl(self, decl: str) -> None:
+        if decl.strip().lower().startswith("doctype"):
+            self.has_doctype = True
+
+    def handle_starttag(self, tag: str, attrs: List[Any]) -> None:
+        node = {"tag": tag, "attrs": dict(attrs), "children": [], "text": ""}
+        self._stack[-1]["children"].append(node)
+        if tag not in _VOID_HTML_TAGS:
+            self._stack.append(node)
+
+    def handle_startendtag(self, tag: str, attrs: List[Any]) -> None:
+        self._stack[-1]["children"].append({"tag": tag, "attrs": dict(attrs), "children": [], "text": ""})
+
+    def handle_endtag(self, tag: str) -> None:
+        for i in range(len(self._stack) - 1, 0, -1):
+            if self._stack[i]["tag"] == tag:
+                del self._stack[i:]
+                return
+        # Unmatched end tag (no open element with this name) — ignored, the
+        # same "just do your best" leniency a real HTML5 parser has for
+        # malformed markup, rather than raising.
+
+    def handle_data(self, data: str) -> None:
+        self._stack[-1]["text"] += data
+
+
+def _find_html_node(node: Dict[str, Any], tag: str) -> Optional[Dict[str, Any]]:
+    if node["tag"] == tag:
+        return node
+    for child in node["children"]:
+        found = _find_html_node(child, tag)
+        if found is not None:
+            return found
+    return None
+
+
+def _finalize_html_node(node: Dict[str, Any]) -> Dict[str, Any]:
+    children = [_finalize_html_node(c) for c in node["children"]]
+    text = node.get("text", "") + "".join(c["text"] for c in children)
+    return {"tag": node["tag"], "attrs": node["attrs"], "children": children, "text": text}
+
+
+def _build_html_payload(text: str) -> Dict[str, Any]:
+    builder = _HTMLTreeBuilder()
+    builder.feed(text)
+    builder.close()
+    html_node = _find_html_node(builder._root, "html") or builder._root
+    body_node = _find_html_node(builder._root, "body")
+    return {
+        "root": _finalize_html_node(html_node),
+        "body": _finalize_html_node(body_node) if body_node is not None else None,
+        "hasDoctype": builder.has_doctype,
+    }

structile/_log.py

@@ -0,0 +1,33 @@
+"""The package's one logger — `logging.getLogger("structile")`, shared by
+every module. A library only ever emits records; it never configures
+handlers/levels for them (that's the application's call) — the
+`NullHandler` is just to keep Python quiet about "no handlers found" if
+nothing else in the process has configured logging at all.
+
+Severity conventions used throughout this package:
+    DEBUG    - internal decisions with no user-visible effect on their own
+               (which renderer/interpreter candidate is being tried, cache
+               hits) — useful when something downstream looks wrong and you
+               need to see why a choice was made.
+    INFO     - a real action happened (a file was written, a browser tab was
+               opened, an interpreter was selected among several candidates,
+               a save was written to disk).
+    WARNING  - something recoverable didn't go as expected but execution
+               continues (an interpreter candidate failed and the next one
+               in line is being tried; a value had to be coerced/dropped).
+    ERROR    - logged immediately before raising, only where the exception
+               message alone would lose useful context (e.g. which of
+               several candidates were tried and how each failed) — not
+               duplicated at every raise site, since the exception itself
+               already carries its own message to the caller.
+
+    import logging
+    logging.getLogger("structile").setLevel(logging.DEBUG)
+    logging.basicConfig()   # or any other handler setup
+"""
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("structile")
+logger.addHandler(logging.NullHandler())

structile/_paths.py

@@ -0,0 +1,148 @@
+"""Path/text-loading helpers shared between open() (__init__.py),
+convert() (convert.py), widget.py, and render.py — kept in their own module
+so none of those end up importing each other.
+"""
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+from dataclasses import dataclass
+from typing import Any, Optional, Union
+
+_PACKAGE_DIR = pathlib.Path(__file__).resolve().parent
+_REPO_ROOT = _PACKAGE_DIR.parent
+# The minified, identifier-renamed production build — see AGENTS.md's
+# "Production build" section and scripts/build_production.js. Built once,
+# checked in, and shipped as package data (`[tool.setuptools.package-data]`
+# in pyproject.toml), NOT generated during `pip install`.
+_BUNDLED_PROD_VIEWER_HTML = _PACKAGE_DIR / "static" / "structile.prod.html"
+
+
+def _viewer_html_override() -> Optional[str]:
+    return os.environ.get("STRUCTILE_VIEWER_HTML")
+
+
+def find_viewer_html() -> pathlib.Path:
+    """Locate structile.html. Tries, in order:
+
+    1. `STRUCTILE_VIEWER_HTML` env var, if set (dev/testing override).
+    2. The human-readable dev source at the repo root — present for an
+       editable, in-repo install (`pip install -e .`) or when just running
+       this repo's own tests/scripts/build_samples.py. Always preferred
+       over the bundled build below so local edits to structile.html take
+       effect immediately, without needing scripts/build_production.js
+       re-run first.
+    3. The bundled production build (see `_BUNDLED_PROD_VIEWER_HTML` above)
+       — what a real `pip install structile` resolves to, since a built
+       wheel has no repo checkout sitting next to it.
+    """
+    override = _viewer_html_override()
+    candidates = [pathlib.Path(override)] if override else []
+    candidates.append(_REPO_ROOT / "structile.html")
+    candidates.append(_BUNDLED_PROD_VIEWER_HTML)
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    raise FileNotFoundError(
+        "structile: could not find structile.html (looked at: "
+        + ", ".join(str(c) for c in candidates)
+        + "). This package expects either an editable install (`pip install "
+        "-e .`) run from inside the structile repository, right next to "
+        "structile.html, or a normal `pip install structile` with its "
+        "bundled production build intact. If you've moved things, point "
+        "the STRUCTILE_VIEWER_HTML environment variable at a viewer HTML "
+        "file directly."
+    )
+
+
+@dataclass(frozen=True)
+class InterpreterSource:
+    """Interpreter JS source text supplied directly, rather than read from a
+    file path — for an interpreter that lives inside an installed package
+    (e.g. loaded via `importlib.resources.files()` from an entry-point
+    plugin — see docs/advanced.md's "Distributing interpreters as a
+    package" and `structile.load_plugins`) instead of at a stable filesystem
+    path.
+
+    Accepted anywhere a path is accepted: the `interpreter=` argument of
+    `open()`, `diff()` (either side, or the `(left, right)` tuple form),
+    `convert()`, and `register_interpreter()` — alone, or inside a candidate
+    list freely mixed with paths. A bare `str` interpreter argument still
+    means a path (or, if it doesn't happen to name an existing file, literal
+    JS source text — see `read_interpreter`'s existing convention below,
+    unchanged); this wrapper is what disambiguates "this is source text, not
+    a path" for a caller (like a plugin's `register()`) that has text in
+    hand and no file to point at.
+
+    `text`: the interpreter's JS source code (`interpretXML`/`serializeXML`
+        for markup, or `interpretText`/`serializeText` for any other format
+        — exactly what a `.js` file would contain).
+    `name`: a human label used only in logs/error messages when this
+        candidate fails during selection — with a plugin, the user may have
+        no idea which candidates were even tried, so naming it there is the
+        only way to make that failure legible.
+    """
+
+    text: str
+    name: str = "<inline>"
+
+    def __repr__(self) -> str:
+        return f"InterpreterSource(name={self.name!r}, len(text)={len(self.text)})"
+
+
+def as_path_like(value: Any) -> Optional[pathlib.Path]:
+    """`value` if it names a file to load — a `PurePath` always counts (even
+    if missing, so callers can raise a proper FileNotFoundError on it), a
+    plain `str` only if it happens to name an existing file. `None` means
+    "this is a literal value, not a path"."""
+    if isinstance(value, pathlib.PurePath):
+        return pathlib.Path(value)
+    if isinstance(value, str) and os.path.isfile(value):
+        return pathlib.Path(value)
+    return None
+
+
+def read_text(p: pathlib.Path) -> str:
+    if not p.is_file():
+        raise FileNotFoundError(f"structile: no such file: {p}")
+    # "utf-8-sig" transparently strips a leading UTF-8 BOM (common in files
+    # saved by Windows tools/editors) and decodes byte-identically to plain
+    # "utf-8" when no BOM is present — a pure widening of what's accepted,
+    # never a behavior change for the (vast majority) BOM-less case. Plain
+    # "utf-8" left a BOM as a leading U+FEFF character, which made
+    # json.loads reject an otherwise-valid .json file outright (see
+    # test_structile.py's BOM test).
+    return p.read_text(encoding="utf-8-sig")
+
+
+def read_interpreter(source: Union[str, pathlib.Path, InterpreterSource]) -> str:
+    """The single point where an interpreter candidate — a path, a bare str
+    (a path if it names an existing file, else literal JS source text), or
+    an explicit `InterpreterSource` — is normalized to plain JS source text.
+    Both JS execution paths (the browser-side trial `open()`/`diff()` use,
+    and the `mini-racer` path `convert()`/`select_interpreter` use) funnel
+    through this one function, so a new candidate kind (like
+    `InterpreterSource`) only ever needs handling here."""
+    if isinstance(source, InterpreterSource):
+        return source.text
+    p = as_path_like(source)
+    return read_text(p) if p is not None else source  # a bare str that isn't a file is raw JS source text
+
+
+def strict_json_loads(text: str) -> Any:
+    """`json.loads`, but rejecting the non-standard `NaN`/`Infinity`/
+    `-Infinity` constants CPython's `json` module otherwise accepts by
+    default (`parse_constant`'s default just returns the corresponding
+    float). Those tokens aren't valid JSON (RFC 8259) and
+    structile.html's own `JSON.parse`-based parser rejects them —
+    so code that uses this (instead of a bare `json.loads`) to decide
+    whether some text genuinely IS valid JSON (e.g. `_load_path`'s
+    `parsed_as_json`, which gates forwarding literal raw text to the viewer
+    as trusted `format="json"` source) must reject them too, or it risks
+    forwarding a document the browser's own parser will refuse."""
+
+    def _reject_constant(token: str) -> Any:
+        raise ValueError(f"{token} is not valid JSON")
+
+    return json.loads(text, parse_constant=_reject_constant)

structile/_plugins.py

@@ -0,0 +1,230 @@
+"""Entry-point-based interpreter plugin discovery — lets an organisation
+distribute its own interpreter(s) as an ordinary, `pip install`-able Python
+package that `structile` picks up with no import of the plugin package, no
+registration call, and no wrapper API. See docs/advanced.md's "Distributing
+interpreters as a package" section for the full mechanics (precedence,
+discovery timing/caching, the `STRUCTILE_DISABLE_PLUGINS` escape hatch) and
+README.md for the end-user-facing walkthrough; `tests/fixtures/
+structile_demo_plugin/` is a working, copyable template.
+
+Plugin contract (public and stable — external packages pin against this):
+
+    # pyproject.toml
+    [project.entry-points."structile.interpreters"]
+    my_plugin = "my_package:register"
+
+    # my_package/__init__.py
+    def register(registry) -> None:
+        registry.register_interpreter(".myext", "path/to/interpreter.js")
+
+`registry` (see `_RegistryFacade` below) is a small facade exposing only
+`register_interpreter()` — never `structile.interpreters` itself, so a
+plugin can't reach (or break) anything else in the package.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from importlib import metadata
+from typing import Any, Dict, Iterable, List, Optional
+
+from ._log import logger
+from ._paths import InterpreterSource
+
+GROUP = "structile.interpreters"
+
+_loaded = False
+
+
+@dataclass
+class PluginRecord:
+    """One discovered `structile.interpreters` entry point — what
+    `structile.plugins()` reports: which entry point it was, which
+    distribution it came from (name + version), and which extensions it
+    actually registered.
+
+    `success=False` means this entry point's `ep.load()` or `register()`
+    call raised (the exception is already logged at WARNING with
+    `exc_info=True` — see `load_plugins`) — `error` holds a short
+    `"ExceptionType: message"` summary and `extensions` stays empty. A
+    record is included here either way: a plugin that silently vanished
+    from `plugins()` on failure is indistinguishable from one that was
+    never installed at all, which is exactly the case someone reaching for
+    `plugins()`/`--plugins` to debug "why didn't my plugin load" needs to
+    see."""
+
+    entry_point: str
+    distribution: str
+    version: str
+    extensions: List[str] = field(default_factory=list)
+    success: bool = True
+    error: Optional[str] = None
+
+
+_plugin_records: List[PluginRecord] = []
+# ext -> distribution name currently owning it via PLUGIN discovery (never a
+# real, direct register_interpreter() call — see _RegistryFacade.register_interpreter
+# and interpreters.register_interpreter/unregister_interpreter, which clear
+# an entry here the moment a caller registers/unregisters it directly).
+_plugin_owner_by_ext: Dict[str, str] = {}
+
+
+def _entry_points_for_group() -> Iterable[Any]:
+    """The one place entry-point iteration happens — monkeypatched by tests
+    to yield fake entry points instead of scanning real installed packages
+    (see tests/test_plugins.py). `importlib.metadata.entry_points()` returns
+    a `SelectableGroups`-like object with `.select(group=...)` on Python
+    3.10+, but only supports the older dict-like `.get(group, [])` on
+    3.8/3.9 — this repo's `requires-python` is `>=3.8`, so both are needed;
+    no `importlib_metadata` dependency required either way."""
+    eps = metadata.entry_points()
+    return eps.select(group=GROUP) if hasattr(eps, "select") else eps.get(GROUP, [])
+
+
+def _env_truthy(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() not in ("", "0", "false", "no")
+
+
+class _RegistryFacade:
+    """The only object a plugin's `register(registry)` function ever sees —
+    deliberately just `register_interpreter()`, a documented, stable public
+    surface a plugin can pin against, without exposing anything else a
+    plugin could reach into or break.
+
+    Enforces the "a plugin registration never beats a real, direct
+    `register_interpreter()` call" precedence rule (see docs/advanced.md's
+    precedence table) and tracks which extensions THIS plugin registered,
+    for `structile.plugins()`. If two plugins register the same extension,
+    the last one loaded wins and a WARNING names both distributions —
+    entry-point iteration order isn't guaranteed, so the warning fires
+    regardless of which one happens to win.
+    """
+
+    def __init__(self, record: PluginRecord) -> None:
+        self._record = record
+
+    def register_interpreter(self, ext: str, interpreter: Any) -> None:
+        from . import interpreters as _interpreters
+
+        ext_norm = _interpreters._normalize_ext(ext)
+        if ext_norm in _interpreters._registry and ext_norm not in _plugin_owner_by_ext:
+            logger.debug(
+                "structile: plugin %r tried to register %r, but it's already registered directly — "
+                "plugin registration skipped (a direct register_interpreter() call always wins)",
+                self._record.distribution,
+                ext_norm,
+            )
+            return
+        previous_owner = _plugin_owner_by_ext.get(ext_norm)
+        if previous_owner is not None and previous_owner != self._record.distribution:
+            logger.warning(
+                "structile: two plugins both registered an interpreter for %r — %r (entry point %r) "
+                "wins, loaded after %r",
+                ext_norm,
+                self._record.distribution,
+                self._record.entry_point,
+                previous_owner,
+            )
+        if isinstance(interpreter, InterpreterSource) and interpreter.name == "<inline>":
+            logger.debug(
+                "structile: plugin %r registered %r via an InterpreterSource with no name= — pass a "
+                "name= (e.g. the distribution name) so failures naming this candidate are legible",
+                self._record.distribution,
+                ext_norm,
+            )
+        _interpreters.register_interpreter(ext, interpreter)
+        _plugin_owner_by_ext[ext_norm] = self._record.distribution
+        if ext_norm not in self._record.extensions:
+            self._record.extensions.append(ext_norm)
+
+
+def load_plugins(force: bool = False) -> None:
+    """Discover and register every installed `structile.interpreters`
+    entry-point plugin — see this module's docstring for the contract.
+
+    Lazy: called from the interpreter-resolution path
+    (`interpreters.get_registered_interpreter`), never from `import
+    structile` — importing the package must never have this side effect,
+    and a broken plugin must never break `import structile`.
+
+    Idempotent: runs at most once per process unless `force=True` (for
+    tests, and for a notebook user who just `pip install`ed a plugin
+    mid-session and wants it picked up without restarting the kernel).
+
+    Each plugin is fully isolated: a bad `ep.load()`, or a `register()` call
+    that raises, is logged at WARNING (`exc_info=True`) and never propagated
+    — one broken plugin can't break anyone else's `structile.open()` call,
+    or even registration of its own other extensions attempted before the
+    raise. It's still recorded (as a failed `PluginRecord`, see below) rather
+    than silently dropped, so `structile.plugins()`/`--plugins` can surface
+    it.
+
+    Set `STRUCTILE_DISABLE_PLUGINS` (any truthy value) to skip discovery
+    entirely — logged at DEBUG — for locked-down environments where someone
+    needs to prove a plugin isn't interfering.
+    """
+    global _loaded
+    if _loaded and not force:
+        return
+    if force:
+        _plugin_records.clear()
+        _plugin_owner_by_ext.clear()
+    _loaded = True
+
+    if _env_truthy("STRUCTILE_DISABLE_PLUGINS"):
+        logger.debug("structile: STRUCTILE_DISABLE_PLUGINS is set, skipping interpreter plugin discovery")
+        return
+
+    for ep in _entry_points_for_group():
+        dist = getattr(ep, "dist", None)
+        distribution = dist.name if dist is not None else ep.name
+        version = dist.version if dist is not None else ""
+        try:
+            register_fn = ep.load()
+        except Exception as exc:
+            logger.warning("structile: plugin entry point %r failed to load, skipping", ep.name, exc_info=True)
+            _plugin_records.append(
+                PluginRecord(
+                    entry_point=ep.name,
+                    distribution=distribution,
+                    version=version,
+                    success=False,
+                    error=f"{type(exc).__name__}: {exc}",
+                )
+            )
+            continue
+        record = PluginRecord(entry_point=ep.name, distribution=distribution, version=version)
+        try:
+            register_fn(_RegistryFacade(record))
+        except Exception as exc:
+            logger.warning(
+                "structile: plugin %r (entry point %r) raised during register(), skipping",
+                distribution,
+                ep.name,
+                exc_info=True,
+            )
+            record.success = False
+            record.error = f"{type(exc).__name__}: {exc}"
+            _plugin_records.append(record)
+            continue
+        _plugin_records.append(record)
+        logger.debug(
+            "structile: plugin %r (entry point %r) registered %r", distribution, ep.name, record.extensions
+        )
+
+
+def plugins() -> List[PluginRecord]:
+    """Every `structile.interpreters` entry point discovered so far —
+    loaded successfully or not (check `.success`/`.error`): entry-point
+    name, distribution name/version, and which extensions it registered —
+    a support/debugging surface a user can run themselves to answer "why
+    did my file open with the wrong schema?" or "why didn't my plugin load
+    at all?" without reading any source or turning on logging. Including
+    failures here (rather than only ones that loaded) matters precisely
+    because the person most likely to call this is the one whose plugin
+    *isn't* working — for them, an empty/incomplete list is indistinguishable
+    from "never installed". Triggers discovery itself (same lazy/idempotent
+    rule as everywhere else), so it's safe to call before anything else has
+    resolved an interpreter."""
+    load_plugins()
+    return list(_plugin_records)