About This Manual¶

What Mountainash TreeSpec Is¶

Mountainash TreeSpec is a Python library for bidirectional hierarchical data transformation. It flattens tree-structured data — XML, JSON, Protobuf, Pydantic models, Avro — into normalised relational tables, and rebuilds the original structure from those tables with round-trip fidelity. A declarative spec (TreeSpec, NodeSpec, ChildSpec) describes how each node in a tree maps to table rows, how children are dispatched (inline, separate table, or routed by attribute), and how keys propagate as foreign keys between the resulting tables.

The library ships five independently installable format handlers — JSON/dataclass, XML/xsdata, Protobuf, Pydantic, and Avro — all built against a common SchemaHandler protocol, plus a streaming flattener for multi-gigabyte XML files, batch processing for multi-file workloads with deduplication, and a hooks system for attaching Polars transforms during flatten or build.

What This Manual Covers¶

This is a guided manual, not the API reference. The auto-generated reference documentation tells you what each class and method does; this manual explains why TreeSpec is designed the way it is, when to reach for each feature, and how the pieces — spec model, flatten engine, build engine, type system, schema handling, format handlers, batch processing, and hooks — fit together. It's organised as 9 chapters that progress from foundational concepts through to the full engine internals.

If you're deciding whether this manual is a good use of your time, see the Course Description page for the intended audience, prerequisites, and a chapter-by-chapter syllabus. If you're ready to start, jump to Chapter 1: Foundation Concepts.

Relationship to the Code Repository¶

This manual documents the mountainash-treespec Python package. The library's source code, issue tracker, and installable releases live in the code repository at github.com/mountainash-io/mountainash-treespec; this textbook site is generated and maintained alongside that codebase and describes the design intent and usage patterns behind it, not just its public API surface. Where this manual and the code disagree, the code is authoritative — please open an issue on the repository.

Authorship and License¶

This manual was written by Nathaniel Ramm.

All content in this site is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0). You are free to share and adapt the material with attribution, for non-commercial purposes, under the same license. Commercial rights are reserved by the copyright holder — see the License page for full terms, or the Contact page for commercial licensing inquiries.