Examples & study material

Eleven 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

Two notebooks (05_interpreters.ipynb, 07_convert.ipynb) have parts that need one more optional package to actually run their XML/INI conversion examples:

pip install mini-racer

(a prebuilt wheel bundling a real V8 JS engine — no Node.js, no npm, no system install). Both notebooks 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.

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, and cross-format/cross-schema diffs), 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 (HTML included) via the DOM contract, INI via the raw-text contract, a candidate list tried in order, register_interpreter.
06_diff.ipynb	structile.diff() — comparing two files, including two mutually-incompatible XML schemas each with their own interpreter.
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.

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, and keyed_xml.js (a third, mutually-incompatible XML schema, used by 10_plugins.ipynb). 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, and 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), 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.