structile 6.1.2__tar.gz → 6.3.0__tar.gz

{structile-6.1.2/structile.egg-info → structile-6.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structile
-Version: 6.1.2
+Version: 6.3.0
 Summary: A spatial editor and diff tool for structured data, inline in Jupyter
 License-Expression: Apache-2.0
 Requires-Python: >=3.8
@@ -232,6 +232,11 @@ data:
   extension): `interpretText(text)` (and optionally `serializeText(value)`),
   given the raw text directly — no DOM involved at all.
 
+An interpreter script may also declare two optional top-level string
+constants, `INTERPRETER_NAME`/`INTERPRETER_VERSION`, purely to
+self-identify — the standalone viewer's `[?]` About popover shows them for
+whichever interpreter is currently active, when either is declared.
+
 `open()` never needs anything beyond its own dependencies for
 either case: every renderer (including `widget`) forwards the interpreter
 source(s) as-is and lets the browser try them client-side. `convert()`

{structile-6.1.2 → structile-6.3.0}/README.pypi.md

@@ -204,6 +204,11 @@ data:
   extension): `interpretText(text)` (and optionally `serializeText(value)`),
   given the raw text directly — no DOM involved at all.
 
+An interpreter script may also declare two optional top-level string
+constants, `INTERPRETER_NAME`/`INTERPRETER_VERSION`, purely to
+self-identify — the standalone viewer's `[?]` About popover shows them for
+whichever interpreter is currently active, when either is declared.
+
 `open()` never needs anything beyond its own dependencies for
 either case: every renderer (including `widget`) forwards the interpreter
 source(s) as-is and lets the browser try them client-side. `convert()`

structile-6.3.0/VERSION

@@ -0,0 +1 @@
+6.3.0

{structile-6.1.2 → structile-6.3.0}/structile/__init__.py

@@ -24,10 +24,12 @@ from ._paths import (
     as_path_like as _as_path_like,
     read_interpreter as _read_interpreter,
     read_text as _read_text,
+    set_viewer_html,
     strict_json_loads as _strict_json_loads,
 )
 from .config import Options, get_option, options, options_from_dict, replace_options, reset_option, resolve_config, resolve_renderer, set_option, use
 from .convert import convert
+from .custom_html import build_custom_html
 from .interpreters import (
     CANONICAL_EXT_FOR_FORMAT as _CANONICAL_EXT_FOR_FORMAT,
     InterpreterSpec,
@@ -35,9 +37,11 @@ from .interpreters import (
     _normalize_ext,
     get_registered_interpreter,
     register_interpreter,
+    register_interpreters_from_manifest,
     resolve_candidates as _resolve_interpreter_candidates,
     unregister_interpreter,
 )
+from .manifest import InterpreterManifestEntry, load_manifest
 from ._plugins import PluginRecord, load_plugins, plugins
 from .render import (
     DiffRenderHandle,
@@ -85,6 +89,11 @@ __all__ = [
     "load_plugins",
     "plugins",
     "PluginRecord",
+    "build_custom_html",
+    "InterpreterManifestEntry",
+    "load_manifest",
+    "register_interpreters_from_manifest",
+    "set_viewer_html",
     "__version__",
 ]
 

{structile-6.1.2 → structile-6.3.0}/structile/_paths.py

@@ -26,7 +26,9 @@ def _viewer_html_override() -> Optional[str]:
 def find_viewer_html() -> pathlib.Path:
     """Locate structile.html. Tries, in order:
 
-    1. `STRUCTILE_VIEWER_HTML` env var, if set (dev/testing override).
+    1. `STRUCTILE_VIEWER_HTML` env var, if set — a dev/testing override,
+       or how a custom-distribution wrapper package (see `set_viewer_html`
+       below) points every renderer at its own bundled, customized HTML.
     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
@@ -56,6 +58,26 @@ def find_viewer_html() -> pathlib.Path:
     )
 
 
+def set_viewer_html(path: Optional[Union[str, pathlib.Path]]) -> None:
+    """Point every `structile` renderer (`open()`, `diff()`, the `widget`/
+    `browser`/`file` renderers, `.to_html()`) at a specific viewer HTML
+    file — `None` reverts to `find_viewer_html()`'s normal resolution.
+
+    This is the documented way for a thin wrapper package to ship its own
+    customized `structile.html` (e.g. one built with interpreters baked in
+    via `structile.build_custom_html`) without forking `structile` itself:
+    call this once, from the wrapper package's own `__init__.py`, with the
+    path to its bundled HTML. It's a thin wrapper around the
+    `STRUCTILE_VIEWER_HTML` env var (read fresh by `find_viewer_html()` on
+    every call, never cached), just under a name that documents this as a
+    supported integration point rather than only a dev/testing knob.
+    """
+    if path is None:
+        os.environ.pop("STRUCTILE_VIEWER_HTML", None)
+    else:
+        os.environ["STRUCTILE_VIEWER_HTML"] = str(path)
+
+
 @dataclass(frozen=True)
 class InterpreterSource:
     """Interpreter JS source text supplied directly, rather than read from a
@@ -131,6 +153,37 @@ def read_interpreter(source: Union[str, pathlib.Path, InterpreterSource]) -> str
     return read_text(p) if p is not None else source  # a bare str that isn't a file is raw JS source text
 
 
+# The one place this module depends on the exact shape of structile.html's
+# main <script> tag, identified by the "use strict" that immediately
+# follows it on the next line (the bare substring "<script>" alone also
+# appears inside a couple of comments elsewhere in the file — see AGENTS.md's
+# note on that CSP-injection lesson from the VS Code extension). Shared by
+# render.py's `window.__STRUCTILE_SNAPSHOT__` bootstrap and
+# custom_html.py's baked-interpreter registry — both just need an arbitrary
+# JSON-safe value visible to the main script before it runs.
+SNAPSHOT_ANCHOR = '\n<script>\n"use strict";'
+
+
+def inject_global_script(html_text: str, var_name: str, value: Any, *, anchor: str = SNAPSHOT_ANCHOR) -> str:
+    """Splice `window.<var_name> = <value as JSON>;` into `html_text`,
+    right before `anchor`. Repeated calls compose correctly regardless of
+    order: each insertion lands before the same anchor text, which is
+    never itself touched, so every injected script still precedes the main
+    <script> that reads it."""
+    idx = html_text.find(anchor)
+    if idx == -1:
+        raise RuntimeError(
+            "structile: could not find structile.html's main <script> tag "
+            "to inject before — has the viewer's structure changed?"
+        )
+    # `<` -> <, same escaping the VS Code extension's jsonForScript
+    # uses, so a "</script"-shaped substring anywhere in the data can't
+    # break out of this <script> block.
+    value_json = json.dumps(value).replace("<", "\\u003c")
+    snippet = "\n<script>\nwindow." + var_name + " = " + value_json + ";\n</script>\n"
+    return html_text[:idx] + snippet + html_text[idx:]
+
+
 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

structile-6.3.0/structile/custom_html.py

@@ -0,0 +1,67 @@
+"""Build a customized `structile.html` with a curated set of interpreters
+baked directly in, at build time — see README.md's "Building a custom/
+branded distribution" section for the full story and
+`tests/fixtures/structile_demo_custom_distribution/` for a working
+template.
+
+Opening the resulting HTML and dropping only a data file of a baked
+extension resolves it immediately — no companion `.js` file ever needed,
+for the extensions this specific build chose to bundle. Stock
+`structile.html` (no manifest applied) is unaffected: the client-side
+registry this bakes into (`window.__STRUCTILE_BAKED_INTERPRETERS__`) is
+empty by default, and `structile.html`'s own extension list
+(`STRUCTURED_EXT_FORMAT`) is only ever merged with it, never replaced by
+it — see the comment above `BAKED_INTERPRETERS` in structile.html.
+
+The trust boundary here is deliberately at build time, not runtime: this
+function reads and embeds whatever JS the manifest points at, verbatim —
+the same trust a user pasting/dropping an interpreter into a running
+session extends to it for that session, just decided once, by whoever
+runs this function, instead of by whoever later opens the file.
+"""
+from __future__ import annotations
+
+import pathlib
+from typing import Dict, Optional, Union
+
+from ._paths import find_viewer_html, inject_global_script, read_interpreter
+from .manifest import ManifestSource, load_manifest
+
+
+def _normalize_ext(ext: str) -> str:
+    ext = ext.lower()
+    return ext if ext.startswith(".") else "." + ext
+
+
+def build_custom_html(
+    manifest: ManifestSource,
+    *,
+    source_html: Optional[Union[str, pathlib.Path]] = None,
+    output: Optional[Union[str, pathlib.Path]] = None,
+) -> str:
+    """Bake `manifest`'s `{extensions, path, name, format}` entries (see
+    `structile.manifest.load_manifest` for accepted `manifest` shapes) into
+    a copy of `structile.html`, and return the resulting HTML text.
+
+    `source_html`: the base HTML to bake into — defaults to
+        `find_viewer_html()`'s own resolution (the dev source next to this
+        repo, or the bundled production build). Pass an explicit path to
+        bake into a specific build instead (e.g. an already-minified
+        `structile.prod.html`).
+    `output`: if given, the resulting HTML is also written there.
+    """
+    entries = load_manifest(manifest)
+    base_html = (
+        pathlib.Path(source_html).read_text(encoding="utf-8")
+        if source_html is not None
+        else find_viewer_html().read_text(encoding="utf-8")
+    )
+    baked: Dict[str, Dict[str, str]] = {}
+    for entry in entries:
+        text = read_interpreter(entry.path)
+        for ext in entry.extensions:
+            baked[_normalize_ext(ext)] = {"format": entry.format, "source": text, "name": entry.name}
+    html_text = inject_global_script(base_html, "__STRUCTILE_BAKED_INTERPRETERS__", baked)
+    if output is not None:
+        pathlib.Path(output).write_text(html_text, encoding="utf-8")
+    return html_text

{structile-6.1.2 → structile-6.3.0}/structile/interpreters.py

@@ -19,6 +19,14 @@ 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`).
 
+An interpreter script may also declare two optional top-level string
+constants, `INTERPRETER_NAME`/`INTERPRETER_VERSION`, purely for
+self-identification — never read or required by anything in this module
+(name/version resolution happens entirely client-side, in
+structile.html's `buildInterpreterFns`, the same place the
+`interpretXML`/`serializeXML`/etc. functions themselves get pulled out),
+surfaced in the standalone viewer's `[?]` About popover.
+
 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*
@@ -39,6 +47,7 @@ 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
+from .manifest import ManifestSource, load_manifest
 
 # 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
@@ -114,6 +123,28 @@ def unregister_interpreter(ext: str) -> None:
     register_interpreter(ext, None)
 
 
+def register_interpreters_from_manifest(manifest: ManifestSource) -> None:
+    """Call `register_interpreter()` once per entry in `manifest` (see
+    `structile.manifest.load_manifest` for accepted shapes) — the
+    Python-side counterpart to `structile.custom_html.build_custom_html`,
+    so a custom distribution can drive both the standalone-HTML baking and
+    the Python registry from the exact same manifest instead of
+    maintaining two separate lists.
+
+    A plugin's own `register(registry)` callback can't call this directly
+    — the facade it receives only exposes `register_interpreter()` (see
+    `_plugins.py`'s `_RegistryFacade`) — so loop over
+    `structile.manifest.load_manifest(...)` and call
+    `registry.register_interpreter(ext, InterpreterSource(text, name=...))`
+    per entry there instead; see README.md's "Building a custom/branded
+    distribution" section for a worked example.
+    """
+    for entry in load_manifest(manifest):
+        text = read_interpreter(entry.path)
+        for ext in entry.extensions:
+            register_interpreter(ext, InterpreterSource(text, name=entry.name))
+
+
 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

structile-6.3.0/structile/manifest.py

@@ -0,0 +1,87 @@
+"""Shared interpreter manifest — the one list a company's custom
+distribution re-reads for two different things: baking interpreters into a
+standalone `structile.html` (see `custom_html.build_custom_html`) and
+registering them with the Python-side registry, either directly
+(`interpreters.register_interpreters_from_manifest`) or from inside an
+entry-point plugin's own `register(registry)` callback (see
+`_plugins.py`'s `_RegistryFacade` — a plugin only ever gets
+`register_interpreter()`, so it loops over `load_manifest(...)` itself
+rather than calling `register_interpreters_from_manifest` directly).
+
+A manifest entry mirrors the VS Code extension's
+`contributes.structileInterpreters` contribution shape (`{extensions,
+path, name, format}` — see
+`vscode-extension/src/interpreterContributions.ts`) so the same mental
+model, and often the same JSON, works across every surface this project
+ships.
+"""
+from __future__ import annotations
+
+import json
+import pathlib
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from ._paths import InterpreterSource
+
+# Anything read_interpreter() already accepts: a path, a bare str (a path
+# if it names an existing file, else literal JS source text), or an
+# explicit InterpreterSource.
+ManifestInterpreterPath = Union[str, pathlib.Path, InterpreterSource]
+
+
+@dataclass(frozen=True)
+class InterpreterManifestEntry:
+    """One `{extensions, path, name, format}` entry — see module docstring.
+
+    `extensions`: file extensions this interpreter handles (e.g. [".axml"]).
+    `path`: anything `read_interpreter()` accepts. When loaded from a JSON
+        manifest file, a relative path is resolved against that file's own
+        directory (see `load_manifest`), not the process's working
+        directory.
+    `name`: a human label used in logs/error messages when this candidate
+        fails during selection.
+    `format`: `"xml"`/`"html"` (the DOM contract) or any other string (the
+        `interpretText` contract) — same meaning as `structile.open()`'s
+        own `format=` argument.
+    """
+
+    extensions: List[str]
+    path: ManifestInterpreterPath
+    name: str
+    format: str
+
+
+def _entry_from_dict(d: Dict[str, Any], *, base_dir: Optional[pathlib.Path]) -> InterpreterManifestEntry:
+    extensions = d["extensions"]
+    if isinstance(extensions, str):
+        extensions = [extensions]
+    path = d["path"]
+    if base_dir is not None and isinstance(path, str) and not pathlib.Path(path).is_absolute():
+        path = base_dir / path
+    return InterpreterManifestEntry(extensions=list(extensions), path=path, name=d["name"], format=d["format"])
+
+
+ManifestSource = Union[str, pathlib.Path, Sequence[Union[Dict[str, Any], InterpreterManifestEntry]]]
+
+
+def load_manifest(source: ManifestSource) -> List[InterpreterManifestEntry]:
+    """Normalize `source` into a list of `InterpreterManifestEntry`.
+
+    `source` is either:
+    - a path to a JSON manifest file — `{"interpreters": [...]}`, each item
+      shaped like `InterpreterManifestEntry`'s fields, with `path` values
+      resolved relative to the manifest file's own directory; or
+    - a plain list of dicts (that same shape) or `InterpreterManifestEntry`
+      instances directly — `path` values are used as-is, since there's no
+      manifest file to resolve a relative path against.
+    """
+    if isinstance(source, (str, pathlib.Path)):
+        manifest_path = pathlib.Path(source)
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+        base_dir = manifest_path.resolve().parent
+        return [_entry_from_dict(item, base_dir=base_dir) for item in data["interpreters"]]
+    entries: List[InterpreterManifestEntry] = []
+    for item in source:
+        entries.append(item if isinstance(item, InterpreterManifestEntry) else _entry_from_dict(item, base_dir=None))
+    return entries

{structile-6.1.2 → structile-6.3.0}/structile/render.py

@@ -31,17 +31,10 @@ from dataclasses import dataclass
 from typing import Any, Dict, List, Optional, Union
 
 from ._log import logger
-from ._paths import find_viewer_html
+from ._paths import find_viewer_html, inject_global_script
 
 RENDERERS = ("widget", "browser", "file", "none", "text")
 
-# The one place in structile.html this module depends on the exact
-# shape of: the main <script> tag, identified by the "use strict" that
-# immediately follows it on the next line (the bare substring "<script>"
-# alone also appears inside a couple of comments elsewhere in the file — see
-# AGENTS.md's note on that CSP-injection lesson from the VS Code extension).
-_SNAPSHOT_ANCHOR = '\n<script>\n"use strict";'
-
 _temp_dir: Optional[str] = None
 
 
@@ -144,24 +137,14 @@ class Payload:
 
 def _inject_snapshot(snapshot: Dict[str, Any]) -> str:
     """Splice an arbitrary `window.__STRUCTILE_SNAPSHOT__` payload into a fresh
-    read of structile.html, right before its main <script> tag.
+    read of structile.html, right before its main <script> tag (see
+    `_paths.inject_global_script`, the shared low-level splicer).
     Shared by `build_standalone_html` (single-value) and
     `build_standalone_diff_html` (two-value, below) — both just build a
     JSON-safe dict in the shape `applyInitialPayload`/`loadDiffPayload`
     already know how to consume and hand it here."""
     viewer_html = find_viewer_html().read_text(encoding="utf-8")
-    idx = viewer_html.find(_SNAPSHOT_ANCHOR)
-    if idx == -1:
-        raise RuntimeError(
-            "structile: could not find structile.html's main <script> tag "
-            "to inject the snapshot before — has the viewer's structure changed?"
-        )
-    # `<` -> <, same escaping the VS Code extension's jsonForScript uses,
-    # so a "</script"-shaped substring anywhere in the data can't break out
-    # of this <script> block.
-    snapshot_json = json.dumps(snapshot).replace("<", "\\u003c")
-    snippet = "\n<script>\nwindow.__STRUCTILE_SNAPSHOT__ = " + snapshot_json + ";\n</script>\n"
-    return viewer_html[:idx] + snippet + viewer_html[idx:]
+    return inject_global_script(viewer_html, "__STRUCTILE_SNAPSHOT__", snapshot)
 
 
 def build_standalone_html(payload: Payload) -> str: