Skip to content

Examples & study material

Twelve runnable notebooks (plus one plain script), the interpreter scripts they load, and the sample data files behind them — the same material used to develop and test Structile itself, packaged so you can run every one of them with nothing but pip install structile and no access to the source repository.

Download structile_study_material.zip — unzip it anywhere and follow the steps below. Nothing in it requires the private source repository; every notebook locates its own data by relative path inside the zip.

Setup

pip install structile
pip install jupyter

Three notebooks (05_interpreters.ipynb, 07_convert.ipynb, 11_interpreter_hints.ipynb) have parts that need one more optional package to actually run — the XML/INI conversion examples, and structile.about's listing of what an interpreter can do:

pip install mini-racer

(a prebuilt wheel bundling a real V8 JS engine — no Node.js, no npm, no system install). The first two wrap those parts in try/except RuntimeError so they still run end to end and tell you what they skipped if you don't install it; structile.about just says what it couldn't read.

Start here

New to Structile? Open examples/00_tour.ipynb — one notebook, one pass through most of the library (a JSON value from a literal/variable/ file, the browser view, diff(), editing and reading back a value, XML via an interpreter, cross-format/cross-schema diffs, and short stops at interpreter hover hints and the flexible diff's tolerances), each part actually rendered rather than just described.

File Covers
00_tour.ipynb Start here: a surface-level pass through most of the library in one notebook.
01_basics.py The smallest open() calls — literal values, loading a file, name=. Run with python examples/01_basics.py.
02_renderers.ipynb The renderer layer: widget/browser/file/none/text, resolution order, use(), out=/auto_open=, the RenderHandle contract.
03_editing_and_saving.ipynb The widget renderer's read-write contract — Save, path=, and mutation semantics.
04_configuring_the_viewer.ipynb The viewer's own settings (gap, theme, layout knobs) — Options, set_option, config=.
05_interpreters.ipynb Custom formats via an interpreter — XML via the DOM contract; INI via the raw-text contract; CSV for contrast, which needs no interpreter at all; a candidate list tried in order; register_interpreter; two more bundled XML schemas; and baking a document + its interpreter into one shareable standalone HTML file.
06_diff.ipynb structile.diff() — comparing two files, including two mutually-incompatible XML schemas each with their own interpreter; and rules=, the flexible diff's tolerances set from Python (numbers within a tolerance, whitespace and case, ignored paths, per-path rules); and a realistic reconciliation — a portfolio against a recalculation of it, 64 differences of which the rules leave 6 real changes (the live diff demo).
07_convert.ipynb structile.convert() — format conversion outside the widget/notebook, XML and INI directions included.
08_logging.ipynb Turning on Structile's own logger and reading its severity levels.
09_troubleshooting_widget_rendering.ipynb Diagnostic notebook for "the widget renderer works in one Jupyter environment but not another" — a progressive series of probes isolating which layer actually breaks.
10_plugins.ipynb Distributing an interpreter as an installable package (entry-point plugins) — who does what (plugin author vs. consumer), st.plugins()/load_plugins(force=True) for introspection, and one broken plugin never breaking another's registration or your open() call. See also the interpreters guide for the same walkthrough as prose.
11_interpreter_hints.ipynb Interpreter hover hints and options — the hoverHint(value, ctx, options) contract and the INTERPRETER_OPTIONS controls the viewer's puzzle-piece panel draws for it; hints in cells; hints in a diff; pre-setting options from Python with interpreterOptions= — including generic_xml.js's scaled-amount hint for showing amounts in millions or converted to another currency (live demo); and structile.about for what a viewer and its interpreters can do. See Hover hints and interpreter options for the same as prose.

Open any notebook with jupyter lab examples/ (or VS Code's own notebook support) from wherever suits you.

What's in the zip, besides the notebooks

  • interpreters/ — the example interpreter scripts the notebooks above load: generic_xml.js, html.js, tagged_xml.js, generic_ini.js, keyed_xml.js (a third, mutually-incompatible XML schema, used by 10_plugins.ipynb), and two more — flat_attrs_xml.js (a whole record as one element's own attributes) and implicit_xml.js (no id=/key=/type= convention at all — a tag's own name is its key). generic_xml.js also carries the scaled-amount hover hint — amounts in millions, or converted to another currency — and the options that 11_interpreter_hints.ipynb switches on. Real, working code — a legitimate starting point for your own interpreter, not just a demo. See Writing and distributing interpreters for the contract these implement.
  • samples/ — the data files the notebooks load: JSON configs and tables, the same data expressed in three deliberately incompatible XML schemas (used together in 10_plugins.ipynb and the cross-schema diff parts of 00_tour.ipynb), the CSV roster (which needs no interpreter — CSV is read natively), and one more sample each for flat_attrs_xml.js/implicit_xml.js, so the diff/interpreter examples aren't working with toy data invented just for the docs.

These are committed with their notebook outputs cleared (small, diff-friendly files, if you keep them under version control yourself) — run the cells to see what they actually produce.