Model navigation

Iterate depth-first over a tree of models.

A child model can sit in a plain field, a list, a dictionary, an Override wrapper, or a TaggedUnionModel union case, so walking the tree by hand takes care.

iterate_models

creator_studio_doc_format.navigation.iterate_models(root)[source]

Yields a model, then every model reachable from it, in depth-first pre-order.

The iteration descends model fields, list[BaseModel], and dict[_, BaseModel], including a model held in an Override. An Override that is unset or cleared holds no model and is skipped.

Parameters:
root : BaseModel

The model to start from.

Yields:

IteratedModel – Each model, a parent before its descendants. A model under two parents appears once for each.

IteratedModel

class creator_studio_doc_format.navigation.IteratedModel(model)[source]

One model the iteration yields, with lazy access to its position in the tree.

Each read of ancestors, index_path, or path costs O(depth). Caching the value can speed up a hot loop.

An IteratedModel compares and hashes by identity, so it can go in a set. A model yielded twice gives two IteratedModel instances, and they compare unequal.

You don’t create an IteratedModel directly. iterate_models() yields them.

model : BaseModel

The model at this position in the tree.

property ancestors : tuple[BaseModel, ...]

The enclosing models, outermost first. It’s () for the root.

property index_path : tuple[int, ...]

The list indices along the path from the root, without field names.

For example, iterating a slide gives (2, 3) for contents[2].object.group.children[3], and () for the root. Read ancestors or path when field names matter.

property path : str

The dotted path from the root. It’s "" for the root.

For example, iterating a slide gives contents[0].object.shape.text. A dictionary key goes through repr, so field['a'] and field[3] stay distinct.

See also

Navigating a document efficiently: searching a document’s text, and filtering by what encloses a match.