Python API reference
Every call and argument this package exposes, pulled directly from the
source's own docstrings — so a person or an AI agent doesn't have to go
read structile's Python source to know what open() accepts. This page
is generated (via mkdocstrings) from
the latest release on PyPI each time the site is built, so it can't drift
from the real signatures the way a hand-written reference could.
This page documents structile 6.38.1.
This covers the everyday surface — open()/diff(), format/interpreter
selection, viewer settings, and what a call hands back. It doesn't list
every public name: deeper plugin-authoring internals like load_plugins
and PluginRecord, and the raw StructileWidget/StructileDiffWidget
classes behind the widget renderer, are covered in
Writing and distributing interpreters instead, in
context, rather than repeated here as bare signatures.
Rendering a value
structile.open
open(
obj: Any,
*,
name: Optional[str] = None,
height: int = 600,
config: Optional[Union[Options, Dict[str, Any]]] = None,
interpreter: Optional[InterpreterSpec] = None,
format: Optional[str] = None,
path: Optional[Union[str, Path]] = None,
renderer: Optional[str] = None,
out: Optional[Union[str, Path]] = None,
auto_open: bool = True,
default: Optional[Callable[[Any], Any]] = None,
**settings: Any,
) -> RenderHandle
Display a Python value through the active renderer. Always returns a
RenderHandle (never None) with .path, .value, .open(),
.to_html(), .save(path), and a one-line repr() — evaluate it as
the last expression in a Jupyter cell, or pass it to
IPython.display.display, and it renders itself richly there too.
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.
Parameters:
-
obj(Any) –the value to display — any mix of dict/list/tuple/set/None/bool/ int (any size)/float/str/numpy scalar — or a
pathlib.Path/strnaming an existing file to load it from (JSON, then a Python literal — objects written asdatetime.date(...)included — 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-memoryobj(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— seeinterpreters.MARKUP_FORMATS), or has an interpreter attached to it (interpreter=, or something already registered viaregister_interpreter), orformat=set explicitly to anything other than"json"/"python", switches to interpreter mode:obj(or a literal string, withformat=then required) is handed to an interpreter instead of being read as a Python value — seeinterpreter=below..xml/.htmluse the DOM-basedinterpretXML(xmlDocument)contract; any other format (.ini,.toml, ...) uses the raw-textinterpretText(text)contract — see interpreters/generic_xml.js vs interpreters/generic_ini.js. -
name(Optional[str], default:None) –display name. Defaults to the loaded file's stem, else "data".
-
height(int, default:600) –iframe height in px (
widgetrenderer only). -
config(Optional[Union[Options, Dict[str, Any]]], default:None) –viewer settings for this call — an
Optionsinstance, or a plain dict of the same keys (config={"gap": 8, "forNull": "N/A"}), whichever's more convenient; a dict is just turned into anOptionsinternally (seeoptions_from_dict). -
**settings(Any, default:{}) –individual viewer settings for this call — the numeric layout knobs (
gap,n,m,N,M,nameMax,valMax,headerLabelMax,detCols,detRows,dwellMs,kvRows,kvCols,maxWidthFrac, and the nested-container cap'schildCap/childStepwith itslimitChildrenon/off switch — a bool, likecellContainerBadges—warnElements, the page-element count past which a redraw shows a "large view" warning, 0 = never,drawAllBoxes, a bool: draw every box of a big document rather than just those near the window (slower; printing does it anyway),searchOpenAll, a bool: a search opens every dict and table holding a match rather than only the current match's,diffMarksInSource, a bool: in a diff, the source panes mark the differences as the graph does (default on), and the large-file pairloadNoticeSec/loadConfirmSec: the estimated load time, in seconds, past which the viewer shows "Loading…" first, or asks before loading at all, 0 = never),theme, the "Special values" display overrides the viewer's Settings panel edits under that name —forNull/forEmpty(strings shown in place ofNone/"") andvalues(a{exact_string: replacement}table) — cosmetic only, never changes the underlying data; andlinkOpen/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 (seeOptions); andinterpreterOptions, an interpreter's own option values for this document —{INTERPRETER_NAME: {option_id: value}},"@inline": Truefor "Show hints in cells" (see README.md, "Hover hints and interpreter options").config=and**settingsboth take precedence overstructile.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 showNoneas"N/A"everywhere it appears, including nested inside dicts/lists, orstructile.open(data, linkOpen="<link.id", linkClose=">")so a value like"<link.id.20>"links to a same-named dict/table. -
interpreter(Optional[InterpreterSpec], default:None) –a path to a
.jsinterpreter script, raw JS source (interpretXML(xmlDocument)+ optionalserializeXML(value)for markup;interpretText(text)+ optionalserializeText(value)for any other text format — see interpreters/generic_xml.js, interpreters/html.js, interpreters/generic_ini.js), or anInterpreterSource(source text supplied directly rather than read from a path — what an installed plugin package handsregister_interpreter; seestructile.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 (seeresolve_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 (tryInterpreterCandidatesin structile.html) and reports which one worked. This needs no Node.js, for any renderer includingwidget. 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(Optional[str], default:None) –"json"|"python"— parseobj(a path, or a literal string of source text) as exactly that, instead of sniffing it (a literal string is otherwise shown as the one string it is); raises ValueError when it isn't. Or"xml"|"html"| any other string (e.g."ini") — required alongsideinterpreter=/a registered interpreter whenobjisn't a path (no extension to infer it from) — unlessinterpreter=is a dict spanning more than one extension, in which case omittingformat=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-textinterpretText(text)contract instead of DOM parsing. -
path(Optional[Union[str, Path]], default:None) –save destination, overriding
obj's own source path (if any) —widgetrenderer only (the other renderers never write back to a source file; see thebrowser/file/none/textdocs). A Save writes the source file back in its own format (Python-repr for a.py, delimited text for a.csv, the text itself for a plain-text file — keeping its line endings and BOM), and apath=target in the format its extension names (.py,.csv/.tsv, else JSON); seeStructileWidget. -
renderer(Optional[str], default:None) –"widget"|"browser"|"file"|"none"|"text"— overrides resolution for this call only. Otherwise resolved viaSTRUCTILE_RENDERER->config/structile.options.renderer(set_option/use) -> auto-detect (seerender.detect_renderer). -
out(Optional[Union[str, Path]], default:None) –also write the standalone HTML snapshot here (any renderer).
-
auto_open(bool, default:True) –set
Falseto suppress thebrowserrenderer's automaticwebbrowser.open()(it still writes the file; call.open()later to open it manually). -
default(Optional[Callable[[Any], Any]], default:None) –called on any value that isn't one of
obj's own JSON-mappable types (see above); its return value is normalized in its place, same escape hatch asjson.dumps(..., default=...)— e.g.default=strdisplays a date as the plain string"2020-01-01". Without it, such an object (datetime.date,Decimal, your own dataclass, ...) is shown as itsrepr()text, editable in place, and.valueholds a real object again after Save: the original one if its text wasn't touched, otherwise one rebuilt from the edited text. Seestructile.normalize.
structile.diff
diff(
left: Any,
right: Any,
*,
interpreter: Optional[
Union[
InterpreterSpec,
Tuple[
Optional[InterpreterSpec],
Optional[InterpreterSpec],
],
]
] = None,
format: Optional[
Union[str, Tuple[Optional[str], Optional[str]]]
] = None,
name: Optional[
Tuple[Optional[str], Optional[str]]
] = None,
view: str = "unified",
key_columns: Optional[list] = None,
rules: Optional[Dict[str, Any]] = None,
interpreterOptions: Optional[Dict[str, Any]] = None,
height: int = 600,
renderer: Optional[str] = None,
out: Optional[Union[str, Path]] = None,
auto_open: bool = True,
default: Optional[
Union[
Callable[[Any], Any],
Tuple[
Optional[Callable[[Any], Any]],
Optional[Callable[[Any], Any]],
],
]
] = None,
) -> DiffRenderHandle
Display a two-sided diff of left vs right through the active
renderer. Always returns a DiffRenderHandle with .path,
.left_payload/.right_payload, .left_value/.right_value,
.open(), .to_html(), .save(path).
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/
.right_value, which read through to the live StructileDiffWidget
for the widget renderer, same as RenderHandle.value does for
open()).
Parameters:
-
left(Any) –each independently accepts anything
open()'sobjdoes — a Python value, a path, or (withinterpreter=/format=) a raw XML string. -
right(Any) –same contract as
left, independently — the two sides don't have to be the same format or schema. -
interpreter(Optional[Union[InterpreterSpec, Tuple[Optional[InterpreterSpec], Optional[InterpreterSpec]]]], default:None) –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 letsleftandrightbe two genuinely different, mutually-incompatible XML schemas, each with its own interpreter. Seeopen()'sinterpreter=docs for what a single value can be. -
format(Optional[Union[str, Tuple[Optional[str], Optional[str]]]], default:None) –same single-value-or-
(left, right)-tuple convention asinterpreter=. Seeopen()'sformat=docs for what a single value can be. -
name(Optional[Tuple[Optional[str], Optional[str]]], default:None) –(left_name, right_name)— defaults to each side's own inferred name (its file stem, or "left"/"right" for a raw string/value). Always a pair: a single string raises TypeError rather than being split into one name per character. -
view(str, default:'unified') –"unified"|"split". -
key_columns(Optional[list], default:None) –table key-column overrides — same shape the standalone viewer's own diff header accepts. A single string is one column name (
key_columns="sku"is["sku"]). -
rules(Optional[Dict[str, Any]], default:None) –what counts as the same — the viewer's "Flexible diff" panel as a dict, and it opens with these set. A difference a rule accepts isn't hidden silently: it's counted as "≈ within tolerance" in the diff header, which can show it (muted). Every key is optional, camelCase or snake_case:
- strings:
whitespace("exact", "trim", "collapse" or "ignore"),ignore_case,ignore_accents,unicode("none", "nfc", "nfkc"),line_endings(CRLF = LF),dates_within(ISO 8601 dates/times in strings within a duration such as "1d", "2h 30m", "90s"); - numbers:
equal_when, an expression overabs(|left − right|) andrel(abs / max(|left|, |right|)), such as "abs <= 1e-9 or rel <= 1e-6" (literals 0.01, 1e-6, 1%, 1bp; and/or/not),nan_equalandignore_zero_sign(both on by default); - other:
empty_equal(null, missing, "", [] and {} equal),ignore(a regular expression matched against each value's path, such astrades[0].updatedAt— "updatedAt|createdAt" ignores those keys and columns anywhere; whatever matches isn't compared, nor anything under it; "/.../i" or "(?i)" ignores case),ignore_order(lists and table rows as multisets),subset(what only the right side has doesn't count),ignore_key_case; paths: per-path rules,{pattern: settings}or[{"path": pattern, **settings}], where a pattern is a path ("trades[*].price","**.name") or a bare key/column name and the most specific match wins. A settings dict takes the keys above plusignore/exact(True); a string is one rule word ("ignore", "exact", "ignore_order", "subset", ...), "within 1d", or a number expression;show_tolerated: draw the accepted differences from the start.
Checked here — a typo raises ValueError naming every problem.
- strings:
-
height(int, default:600) –iframe height in px (
widgetrenderer only). -
interpreterOptions(Optional[Dict[str, Any]], default:None) –same as
open()'s — an interpreter's own option values,{INTERPRETER_NAME: {option_id: value}}with"@inline": Truefor "Show hints in cells", applied to both sides (each side's interpreter reads its own entry) and to this diff only. The only viewer optiondiff()takes. -
renderer(Optional[str], default:None) –same as
open(). -
out(Optional[Union[str, Path]], default:None) –same as
open(). -
auto_open(bool, default:True) –same as
open(). -
default(Optional[Union[Callable[[Any], Any], Tuple[Optional[Callable[[Any], Any]], Optional[Callable[[Any], Any]]]]], default:None) –same escape hatch as
open()'sdefault=, for whichever side(s) are plain Python values (a markup/interpreter-mode side never reachesnormalize(), 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 asinterpreter=/format=.
Converting between formats
convert
convert(
src: Union[str, Path],
dst_format: str,
interpreter: Optional[InterpreterSpec] = None,
) -> 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
https://danieltuzes.github.io/structile/python-library/#converting-between-formats
for the built-in-vs-JS-runtime boundary and examples.
Parameters:
-
src(Union[str, Path]) –a path (format inferred from its extension: .json/.py/.csv/.tsv/ .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(str) –"json"|"python"|"csv"|"tsv"(the same format written with tabs) |"xml"|"html"| any other string an interpreter is registered/provided for (e.g."ini"). -
interpreter(Optional[InterpreterSpec], default:None) –a path to a
.jsinterpreter script, raw JS source, or a list of candidates tried in order (same contract asstructile.open(..., interpreter=...)— seeselect_interpreter) — required wheneversrcordst_formatisn't"json"/"python"and isn't"csv"/"tsv"either, and nothing is registered for the relevant extension (seeregister_interpreter); needs the optionalmini-racerpackage (pip install mini-racer) to run it — no Node.js, no jsdom, no system install (see interpreters.run_interpreter_source). Converting purely between the built-in formats ("json", "python", "csv", "tsv") needs nothing extra at all.
Custom formats
structile.register_interpreter
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.
structile.unregister_interpreter
Remove any interpreter(s) registered for ext.
structile.get_registered_interpreter
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.
Custom/branded distributions
The calls behind building a custom/branded distribution — baking a curated set of interpreters into your own copy of the viewer, registering that same manifest with the Python-side registry, and pointing every renderer at the result. See that guide for the end-to-end walkthrough and a downloadable template; these are the exact signatures.
structile.build_custom_html
build_custom_html(
manifest: ManifestSource,
*,
source_html: Optional[Union[str, Path]] = None,
output: Optional[Union[str, Path]] = None,
) -> str
Bake manifest's {extensions, path, name, format} entries into a
copy of structile.html, and return the resulting HTML text.
manifest holds ANY NUMBER of interpreters, and baking several formats
into one branded viewer is the normal case. Two accepted shapes (see
structile.manifest.load_manifest): a path to a JSON file shaped
{"interpreters": [ ... ]}, whose path values resolve relative to
that file; or, in memory, the inner list of entry dicts on its own —
NOT the wrapping object. Each entry names its own extensions (one or
several) and format, and one build freely mixes the two contracts
("xml"/"html" use interpretXML/serializeXML, every other
format string uses interpretText/serializeText). An entry with
binary: true (implied by format: "bin") reads BYTES: the viewer
routes a dropped file of that extension straight to its
interpretText, one character per byte, without ever sniffing or
decoding it as text — see structile.manifest.InterpreterManifestEntry.
If two entries claim the same extension the later one silently wins —
no error — so keep the list unambiguous. Extensions absent from the
manifest behave exactly as in the stock viewer, and the built-in
JSON/Python-repr/CSV formats need no entry at all.
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.
structile.register_interpreters_from_manifest
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.
structile.set_viewer_html
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.
structile.load_manifest
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.
structile.plugins
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.
Viewer settings
structile.Options
structile.set_option
Set a module-level default option.
structile.set_option("theme", "dark")
Equivalent to structile.options.<name> = value. Pass value=None to
unset it again (falls back to the viewer's built-in default).
structile.get_option
Read a module-level default option (None if unset).
structile.reset_option
Unset a module-level default option (falls back to the viewer default).
structile.use
Set the module-level default renderer, matplotlib.use()-style.
structile.use("browser")
Equivalent to set_option("renderer", renderer) / options.renderer =
renderer. See structile.render.RENDERERS for the valid names.
What a call returns
structile.RenderHandle
Bases: _RenderHandleBase
What every open() call returns, regardless of renderer.
.value is the displayed value (JSON-safe data, or raw XML text
when an interpreter= was used) — for the widget renderer this stays
live, updated on every Save (same as StructileWidget.value always
was); for every other renderer it's a static snapshot of what was
rendered, since there's no channel back from a plain browser tab/file to
Python. .widget is the underlying StructileWidget for the widget
renderer, None otherwise — an escape hatch for anywidget-specific
features (.dirty, .dirty_count, .on_msg, ...) this handle doesn't
itself proxy.
structile.DiffRenderHandle
Bases: _RenderHandleBase
Returned by structile.diff() — the two-sided counterpart to
RenderHandle, deliberately narrow: the diff GRAPH is always read-only
(there's no single .value the way a plain document has one — see
.left_payload/.right_payload for the static snapshot each side
started from), but for the widget renderer, .left_value/
.right_value read through to the live StructileDiffWidget the same
way RenderHandle.value reads through to StructileWidget — each
side's own source pane is independently editable/saveable in embedded
diff mode (structile.html's performDiffSideSave), even though
the graph itself never is.