codechu-treedata 0.1.0

Stdlib-only N-ary tree data structures and algorithms.

   ┌──────────────────────────────────────────────────┐
   │  c o d e c h u — t r e e d a t a                 │
   │       root                                       │
   │       ├── a                                      │
   │       │   └── a1                                 │
   │       └── b                                      │
   │  ······N-ary trees, in and out of memory········ │
   └──────────────────────────────────────────────────┘

Generic N-ary tree primitives and algorithms.

codechu-treedata

Stdlib-only N-ary tree data structures — a generic Node, traversal, search, prune/map/filter, JSON & ASCII & DOT serialization, structural diff/merge, and an O(1) lookup index. No domain coupling: works for any hierarchy. Python 3.10+.

Install

pip install codechu-treedata

API

from codechu_treedata import (
    Node, Index,
    dfs_pre, dfs_post, bfs,
    find, find_all, find_by_path,
    prune, map_tree, filter_tree,
    to_dict, from_dict, to_ascii, to_dot, to_lines,
    diff, merge,
)

root = Node("root", payload=1)
a = root.add(Node("a", 2))
a.add(Node("a1", 3))
root.add(Node("b", 5))

# Traversal
[n.name for n in dfs_pre(root)]      # ['root', 'a', 'a1', 'b']
[n.name for n in bfs(root)]          # ['root', 'a', 'b', 'a1']

# Search
find(root, lambda n: n.payload == 3) # → Node('a1')
find_by_path(root, ["root", "a", "a1"])

# Mutation
prune(root, lambda n: n.name == "a")  # in place
double = map_tree(root, lambda p: (p or 0) * 2)

# Serialization
print(to_ascii(root))
to_dict(root)                         # JSON-friendly
from_dict(d)                          # round-trip

# Diff / merge
diff(old_tree, new_tree)              # [(path, action, payload), …]
merge(a, b, conflict_resolver=lambda na, nb: max(na.payload, nb.payload))

# O(1) index (snapshot — rebuild after mutations)
idx = Index(root)
idx.get("a1")

Design

• Pure stdlib. Zero third-party dependencies.
• Generic. payload is opaque — attach any object. The library never inspects it (except for equality in diff / merge).
• Predictable. Pre-order DFS is the default for find_all, to_lines, and Index insertion order.
• Snapshot index. Index is built once; structural changes do not auto-invalidate it. Callers rebuild after mutations. Keeps the read path branch-free.

Tests

pip install -e ".[dev]"
ruff check .
pytest -q

License

MIT — see LICENSE.