structile 6.0.2__tar.gz → 6.1.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structile
-Version: 6.0.2
+Version: 6.1.2
 Summary: A spatial editor and diff tool for structured data, inline in Jupyter
 License-Expression: Apache-2.0
 Requires-Python: >=3.8

structile-6.1.2/VERSION

@@ -0,0 +1 @@
+6.1.2

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

@@ -6,9 +6,10 @@
 
 `open()` renders through whichever renderer is active — an inline
 Jupyter widget, a browser tab, a written HTML file, a terminal summary, or
-nothing at all — matplotlib-backend style (see `render.py`). See README.md
-for the full picture (renderers, install steps, supported types, current
-limitations).
+nothing at all — matplotlib-backend style (see `render.py`). See
+https://danieltuzes.github.io/structile/python-library/ for the full
+picture (renderers, install steps, supported types, current limitations)
+— no repo checkout needed to read it.
 """
 from __future__ import annotations
 
@@ -227,105 +228,107 @@ def open(
     the last expression in a Jupyter cell, or pass it to
     `IPython.display.display`, and it renders itself richly there too.
 
-    See README.md ("Python / Jupyter (structile.open)") for examples and the
-    full picture — this is a parameter reference, not a tutorial. Shadows
+    See https://danieltuzes.github.io/structile/python-library/ for
+    examples and the full picture — this is a parameter reference, not a
+    tutorial. Shadows
     the `open` builtin — always call this namespace-qualified
     (`structile.open(...)`), never `from structile import open`.
 
-    obj: the value to display — any mix of dict/list/tuple/set/None/bool/
-        int (any size)/float/str/numpy scalar — or a `pathlib.Path`/`str`
-        naming an existing file to load it from (JSON, falling back to
-        plain text). When loaded from a path whose content IS valid JSON,
-        the file's own literal bytes (not a re-serialization) are what the
-        viewer's source pane shows/edits/saves — so original formatting
-        (whitespace, key order, ...) survives untouched until an edit
-        actually touches it. There's no such "original text" for an
-        in-memory `obj` (no path) or for a path that falls back to plain
-        text (below) — both show a freshly-serialized JSON view instead, as
-        they always have. A path whose extension is markup-like (`.xml`,
-        `.html`/`.htm` — see `interpreters.MARKUP_FORMATS`), or has an
-        interpreter attached to it (`interpreter=`, or something already
-        registered via `register_interpreter`), or `format=` set explicitly
-        to anything other than `"json"`/`"python"`, switches to interpreter
-        mode: `obj` (or a literal string, with `format=` then required) is
-        handed to an interpreter instead of being read as a Python value —
-        see `interpreter=` below. `.xml`/`.html` use the DOM-based
-        `interpretXML(xmlDocument)` contract; any other format (`.ini`,
-        `.toml`, ...) uses the raw-text `interpretText(text)` contract — see
-        interpreters/generic_xml.js vs interpreters/generic_ini.js.
-    name: display name. Defaults to the loaded file's stem, else "data".
-    height: iframe height in px (`widget` renderer only).
-    config: viewer settings for this call — an `Options` instance, or a
-        plain dict of the same keys (`config={"gap": 8, "forNull": "N/A"}`),
-        whichever's more convenient; a dict is just turned into an `Options`
-        internally (see `options_from_dict`).
-    **settings: individual viewer settings for this call — the numeric
-        layout knobs (`gap`, `n`, `m`, `N`, `M`, `nameMax`, `valMax`,
-        `headerLabelMax`, `detCols`, `detRows`, `dwellMs`, `kvRows`,
-        `kvCols`, `maxWidthFrac`), `theme`, the "Special values" display
-        overrides the viewer's Settings panel edits under that name —
-        `forNull`/`forEmpty` (strings shown in place of `None`/`""`) and
-        `values` (a `{exact_string: replacement}` table) — cosmetic only,
-        never changes the underlying data; and `linkOpen`/`linkClose`, the
-        viewer's cross-reference-value marker — a dict value/table cell
-        wrapped between them, verbatim (delimiters included), that names
-        another dict/table anywhere in the document becomes a clickable
-        link that jumps to it (see `Options`). `config=` and
-        `**settings` both take precedence over `structile.options` /
-        `set_option(...)`; anything left unset everywhere falls back to the
-        viewer's default. There's no Settings panel in embedded (widget)
-        mode, so this is the only way to reach these from Python there —
-        e.g. `structile.open(data, forNull="N/A")` to show `None` as `"N/A"`
-        everywhere it appears, including nested inside dicts/lists, or
-        `structile.open(data, linkOpen="<link.id", linkClose=">")` so a value
-        like `"<link.id.20>"` links to a same-named dict/table.
-    interpreter: a path to a `.js` interpreter script, raw JS source
-        (`interpretXML(xmlDocument)` + optional `serializeXML(value)` for
-        markup; `interpretText(text)` + optional `serializeText(value)` for
-        any other text format — see interpreters/generic_xml.js,
-        interpreters/html.js, interpreters/generic_ini.js), or an
-        `InterpreterSource` (source text supplied directly rather than read
-        from a path — what an installed plugin package hands
-        `register_interpreter`; see `structile.plugins()`); a list mixing
-        any of the above; or a dict keyed by file extension (`{".xml": [...],
-        ".html": [...]}`) — only the entry matching the actual file/format
-        is tried, never another extension's candidates (see
-        `resolve_candidates`). Multiple candidates are never disambiguated
-        in Python — the source(s) are forwarded as-is to whichever renderer
-        is active, which tries each one itself (`tryInterpreterCandidates`
-        in structile.html) and reports which one worked. This
-        needs no Node.js, for any renderer including `widget`. Not required
-        if something's already registered for the extension
-        (`register_interpreter`, set up once at import time) — this only
-        overrides that for one call.
-    format: `"xml"` | `"html"` | any other string (e.g. `"ini"`) —
-        required alongside `interpreter=`/a registered interpreter when
-        `obj` isn't a path (no extension to infer it from) — *unless*
-        `interpreter=` is a dict spanning more than one extension, in which
-        case omitting `format=` forwards every entry (each under its own
-        extension's format) to the renderer, which determines the format
-        itself the same no-Node way (`tryInterpreterCandidatesAnyFormat`) —
-        Python never has to run anything just to decide which format
-        applies, or which contract (DOM vs. raw-text) it uses. Any format
-        other than `"xml"`/`"html"` runs through the raw-text
-        `interpretText(text)` contract instead of DOM parsing.
-    path: save destination, overriding `obj`'s own source path (if any) —
-        `widget` renderer only (the other renderers never write back to a
-        source file; see the `browser`/`file`/`none`/`text` docs).
-    renderer: `"widget"` | `"browser"` | `"file"` | `"none"` | `"text"` —
-        overrides resolution for this call only. Otherwise resolved via
-        `STRUCTILE_RENDERER` -> `config`/`structile.options.renderer`
-        (`set_option`/`use`) -> auto-detect (see `render.detect_renderer`).
-    out: also write the standalone HTML snapshot here (any renderer).
-    auto_open: set `False` to suppress the `browser` renderer's automatic
-        `webbrowser.open()` (it still writes the file; call `.open()` later
-        to open it manually).
-    default: called on any value that isn't one of `obj`'s own supported
-        types (see above); its return value is normalized in its place,
-        same escape hatch as `json.dumps(..., default=...)` — e.g.
-        `default=str` displays an otherwise-unsupported object as whatever
-        `str()` shows for it, instead of raising `TypeError`. See
-        `structile.normalize`.
+    Args:
+        obj: the value to display — any mix of dict/list/tuple/set/None/bool/
+            int (any size)/float/str/numpy scalar — or a `pathlib.Path`/`str`
+            naming an existing file to load it from (JSON, falling back to
+            plain text). When loaded from a path whose content IS valid JSON,
+            the file's own literal bytes (not a re-serialization) are what the
+            viewer's source pane shows/edits/saves — so original formatting
+            (whitespace, key order, ...) survives untouched until an edit
+            actually touches it. There's no such "original text" for an
+            in-memory `obj` (no path) or for a path that falls back to plain
+            text (below) — both show a freshly-serialized JSON view instead, as
+            they always have. A path whose extension is markup-like (`.xml`,
+            `.html`/`.htm` — see `interpreters.MARKUP_FORMATS`), or has an
+            interpreter attached to it (`interpreter=`, or something already
+            registered via `register_interpreter`), or `format=` set explicitly
+            to anything other than `"json"`/`"python"`, switches to interpreter
+            mode: `obj` (or a literal string, with `format=` then required) is
+            handed to an interpreter instead of being read as a Python value —
+            see `interpreter=` below. `.xml`/`.html` use the DOM-based
+            `interpretXML(xmlDocument)` contract; any other format (`.ini`,
+            `.toml`, ...) uses the raw-text `interpretText(text)` contract — see
+            interpreters/generic_xml.js vs interpreters/generic_ini.js.
+        name: display name. Defaults to the loaded file's stem, else "data".
+        height: iframe height in px (`widget` renderer only).
+        config: viewer settings for this call — an `Options` instance, or a
+            plain dict of the same keys (`config={"gap": 8, "forNull": "N/A"}`),
+            whichever's more convenient; a dict is just turned into an `Options`
+            internally (see `options_from_dict`).
+        **settings: individual viewer settings for this call — the numeric
+            layout knobs (`gap`, `n`, `m`, `N`, `M`, `nameMax`, `valMax`,
+            `headerLabelMax`, `detCols`, `detRows`, `dwellMs`, `kvRows`,
+            `kvCols`, `maxWidthFrac`), `theme`, the "Special values" display
+            overrides the viewer's Settings panel edits under that name —
+            `forNull`/`forEmpty` (strings shown in place of `None`/`""`) and
+            `values` (a `{exact_string: replacement}` table) — cosmetic only,
+            never changes the underlying data; and `linkOpen`/`linkClose`, the
+            viewer's cross-reference-value marker — a dict value/table cell
+            wrapped between them, verbatim (delimiters included), that names
+            another dict/table anywhere in the document becomes a clickable
+            link that jumps to it (see `Options`). `config=` and
+            `**settings` both take precedence over `structile.options` /
+            `set_option(...)`; anything left unset everywhere falls back to the
+            viewer's default. There's no Settings panel in embedded (widget)
+            mode, so this is the only way to reach these from Python there —
+            e.g. `structile.open(data, forNull="N/A")` to show `None` as `"N/A"`
+            everywhere it appears, including nested inside dicts/lists, or
+            `structile.open(data, linkOpen="<link.id", linkClose=">")` so a value
+            like `"<link.id.20>"` links to a same-named dict/table.
+        interpreter: a path to a `.js` interpreter script, raw JS source
+            (`interpretXML(xmlDocument)` + optional `serializeXML(value)` for
+            markup; `interpretText(text)` + optional `serializeText(value)` for
+            any other text format — see interpreters/generic_xml.js,
+            interpreters/html.js, interpreters/generic_ini.js), or an
+            `InterpreterSource` (source text supplied directly rather than read
+            from a path — what an installed plugin package hands
+            `register_interpreter`; see `structile.plugins()`); a list mixing
+            any of the above; or a dict keyed by file extension (`{".xml": [...],
+            ".html": [...]}`) — only the entry matching the actual file/format
+            is tried, never another extension's candidates (see
+            `resolve_candidates`). Multiple candidates are never disambiguated
+            in Python — the source(s) are forwarded as-is to whichever renderer
+            is active, which tries each one itself (`tryInterpreterCandidates`
+            in structile.html) and reports which one worked. This
+            needs no Node.js, for any renderer including `widget`. Not required
+            if something's already registered for the extension
+            (`register_interpreter`, set up once at import time) — this only
+            overrides that for one call.
+        format: `"xml"` | `"html"` | any other string (e.g. `"ini"`) —
+            required alongside `interpreter=`/a registered interpreter when
+            `obj` isn't a path (no extension to infer it from) — *unless*
+            `interpreter=` is a dict spanning more than one extension, in which
+            case omitting `format=` forwards every entry (each under its own
+            extension's format) to the renderer, which determines the format
+            itself the same no-Node way (`tryInterpreterCandidatesAnyFormat`) —
+            Python never has to run anything just to decide which format
+            applies, or which contract (DOM vs. raw-text) it uses. Any format
+            other than `"xml"`/`"html"` runs through the raw-text
+            `interpretText(text)` contract instead of DOM parsing.
+        path: save destination, overriding `obj`'s own source path (if any) —
+            `widget` renderer only (the other renderers never write back to a
+            source file; see the `browser`/`file`/`none`/`text` docs).
+        renderer: `"widget"` | `"browser"` | `"file"` | `"none"` | `"text"` —
+            overrides resolution for this call only. Otherwise resolved via
+            `STRUCTILE_RENDERER` -> `config`/`structile.options.renderer`
+            (`set_option`/`use`) -> auto-detect (see `render.detect_renderer`).
+        out: also write the standalone HTML snapshot here (any renderer).
+        auto_open: set `False` to suppress the `browser` renderer's automatic
+            `webbrowser.open()` (it still writes the file; call `.open()` later
+            to open it manually).
+        default: called on any value that isn't one of `obj`'s own supported
+            types (see above); its return value is normalized in its place,
+            same escape hatch as `json.dumps(..., default=...)` — e.g.
+            `default=str` displays an otherwise-unsupported object as whatever
+            `str()` shows for it, instead of raising `TypeError`. See
+            `structile.normalize`.
     """
     if isinstance(config, dict):
         config = options_from_dict(config)
@@ -482,8 +485,8 @@ def diff(
     `.left_payload`/`.right_payload`, `.left_value`/`.right_value`,
     `.open()`, `.to_html()`, `.save(path)`.
 
-    See README.md ("Comparing two files (structile.diff)") for examples.
-    Deliberately narrower than `open()`: no per-side viewer
+    See https://danieltuzes.github.io/structile/python-library/#comparing-two-files-structilediff
+    for examples. Deliberately narrower than `open()`: no per-side viewer
     `config=`/`**settings`, and the diff graph itself is always read-only
     for every renderer (including `widget`) — only each side's own source
     pane can be independently edited/saved (see `.left_value`/
@@ -491,27 +494,35 @@ def diff(
     for the `widget` renderer, same as `RenderHandle.value` does for
     `open()`).
 
-    left, right: each independently accepts anything `open()`'s
-        `obj` does — a Python value, a path, or (with `interpreter=`/
-        `format=`) a raw XML string.
-    interpreter, format: a single value applies to BOTH sides (the common
-        case: two files in the same format/schema); a `(left, right)`
-        2-tuple gives each side its own — this is what lets `left` and
-        `right` be two genuinely different, mutually-incompatible XML
-        schemas, each with its own interpreter. See `open()`'s
-        `interpreter=`/`format=` docs for what a single value can be.
-    name: `(left_name, right_name)` — defaults to each side's own inferred
-        name (its file stem, or "left"/"right" for a raw string/value).
-    view: `"unified"` | `"split"`.
-    key_columns: table key-column overrides — same shape the standalone
-        viewer's own diff header accepts.
-    height: iframe height in px (`widget` renderer only).
-    renderer, out, auto_open: same as `open()`.
-    default: same escape hatch as `open()`'s `default=`, for
-        whichever side(s) are plain Python values (a markup/interpreter-mode
-        side never reaches `normalize()`, so this has no effect there) — a
-        single value applies to both sides; a `(left, right)` 2-tuple gives
-        each side its own, same convention as `interpreter=`/`format=`.
+    Args:
+        left: each independently accepts anything `open()`'s
+            `obj` does — a Python value, a path, or (with `interpreter=`/
+            `format=`) a raw XML string.
+        right: same contract as `left`, independently — the two sides don't
+            have to be the same format or schema.
+        interpreter: a single value applies to BOTH sides (the common
+            case: two files in the same format/schema); a `(left, right)`
+            2-tuple gives each side its own — this is what lets `left` and
+            `right` be two genuinely different, mutually-incompatible XML
+            schemas, each with its own interpreter. See `open()`'s
+            `interpreter=` docs for what a single value can be.
+        format: same single-value-or-`(left, right)`-tuple convention as
+            `interpreter=`. See `open()`'s `format=` docs for what a single
+            value can be.
+        name: `(left_name, right_name)` — defaults to each side's own inferred
+            name (its file stem, or "left"/"right" for a raw string/value).
+        view: `"unified"` | `"split"`.
+        key_columns: table key-column overrides — same shape the standalone
+            viewer's own diff header accepts.
+        height: iframe height in px (`widget` renderer only).
+        renderer: same as `open()`.
+        out: same as `open()`.
+        auto_open: same as `open()`.
+        default: same escape hatch as `open()`'s `default=`, for
+            whichever side(s) are plain Python values (a markup/interpreter-mode
+            side never reaches `normalize()`, so this has no effect there) — a
+            single value applies to both sides; a `(left, right)` 2-tuple gives
+            each side its own, same convention as `interpreter=`/`format=`.
     """
     resolved_renderer = resolve_renderer(renderer, None) or _detect_renderer()
     left_interp, right_interp = interpreter if isinstance(interpreter, tuple) else (interpreter, interpreter)

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

@@ -61,8 +61,9 @@ 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
+    plugin — see
+    https://danieltuzes.github.io/structile/advanced-usage/#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

{structile-6.0.2 → structile-6.1.2}/structile/_plugins.py

@@ -1,11 +1,14 @@
 """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.
+registration call, and no wrapper API. See
+https://danieltuzes.github.io/structile/advanced-usage/#distributing-interpreters-as-a-package
+for the full mechanics (precedence,
+discovery timing/caching, the `STRUCTILE_DISABLE_PLUGINS` escape hatch,
+repo-only, contributor-facing) and
+https://danieltuzes.github.io/structile/interpreters/#python-an-installable-plugin
+for the end-user-facing walkthrough (public, no repo checkout needed);
+`tests/fixtures/structile_demo_plugin/` is a working, copyable template.
 
 Plugin contract (public and stable — external packages pin against this):
 
@@ -92,7 +95,8 @@ class _RegistryFacade:
     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
+    `register_interpreter()` call" precedence rule (see
+    https://danieltuzes.github.io/structile/advanced-usage/#distributing-interpreters-as-a-package'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 —

{structile-6.0.2 → structile-6.1.2}/structile/convert.py

@@ -66,28 +66,30 @@ def convert(
 ) -> str:
     """Convert data from one of the viewer's formats to another, entirely
     outside the widget/notebook — parse `src`, then serialize the result as
-    `dst_format`, returning the converted text. See README.md ("Converting
-    between formats") for the built-in-vs-JS-runtime boundary and examples.
-
-    src: a path (format inferred from its extension: .json/.py/.xml/.html —
-        or, once an interpreter is attached to it, any other extension too,
-        e.g. .ini) or a literal string of source text (sniffed: JSON, else
-        Python-repr, else XML if it looks like markup — there's no
-        `src_format=` parameter, so a literal string for any OTHER format
-        needs a `.` path instead, since there's no reliable way to sniff an
-        arbitrary text format from content alone the way XML's leading `<`
-        works).
-    dst_format: `"json"` | `"python"` | `"xml"` | `"html"` | any other
-        string an interpreter is registered/provided for (e.g. `"ini"`).
-    interpreter: a path to a `.js` interpreter script, raw JS source, or a
-        list of candidates tried in order (same contract as
-        `structile.open(..., interpreter=...)` — see `select_interpreter`) —
-        required whenever `src` or `dst_format` isn't `"json"`/`"python"`
-        and nothing is registered for the relevant extension (see
-        `register_interpreter`); needs the optional `mini-racer` package
-        (`pip install mini-racer`) to run it — no Node.js, no jsdom, no
-        system install (see interpreters.run_interpreter_source). Converting
-        purely between "json" and "python" needs nothing extra at all.
+    `dst_format`, returning the converted text. See
+    https://danieltuzes.github.io/structile/python-library/#converting-between-formats
+    for the built-in-vs-JS-runtime boundary and examples.
+
+    Args:
+        src: a path (format inferred from its extension: .json/.py/.xml/.html —
+            or, once an interpreter is attached to it, any other extension too,
+            e.g. .ini) or a literal string of source text (sniffed: JSON, else
+            Python-repr, else XML if it looks like markup — there's no
+            `src_format=` parameter, so a literal string for any OTHER format
+            needs a `.` path instead, since there's no reliable way to sniff an
+            arbitrary text format from content alone the way XML's leading `<`
+            works).
+        dst_format: `"json"` | `"python"` | `"xml"` | `"html"` | any other
+            string an interpreter is registered/provided for (e.g. `"ini"`).
+        interpreter: a path to a `.js` interpreter script, raw JS source, or a
+            list of candidates tried in order (same contract as
+            `structile.open(..., interpreter=...)` — see `select_interpreter`) —
+            required whenever `src` or `dst_format` isn't `"json"`/`"python"`
+            and nothing is registered for the relevant extension (see
+            `register_interpreter`); needs the optional `mini-racer` package
+            (`pip install mini-racer`) to run it — no Node.js, no jsdom, no
+            system install (see interpreters.run_interpreter_source). Converting
+            purely between "json" and "python" needs nothing extra at all.
     """
     text, src_format, src_ext = _infer_source(src, interpreter)
     value = _parse_by_format(text, src_format, interpreter, src_ext)

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

@@ -1,6 +1,8 @@
 """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
+other text format alike — see
+https://danieltuzes.github.io/structile/interpreters/ (the public guide;
+no repo checkout needed) and
+https://danieltuzes.github.io/structile/advanced-usage/#interpreter-selection
 for the full picture.
 
 An interpreter is caller-supplied JS: `interpretXML(xmlDocument)` (optionally
@@ -222,8 +224,8 @@ def run_interpreter_source(
         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.'
+            "structile itself. See "
+            "https://danieltuzes.github.io/structile/interpreters/"
         )
     from py_mini_racer import JSEvalException, MiniRacer
 
@@ -348,8 +350,8 @@ def select_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.'
+            "dependency of structile itself. See "
+            "https://danieltuzes.github.io/structile/interpreters/"
         )
     if len(candidates) > 1:
         logger.debug("structile: %d interpreter candidates for %r, trying each in order", len(candidates), fmt)