Navigating a document efficiently

Find the model instances you need without reading the whole document.

A document can hold thousands of model instances, because even a short presentation carries its theme’s layouts and styles. The right tool depends on what you already know about the document.

Find specific model instances

When you know the model you want but not where its instances are, search the tree. iterate_models() takes any model instance, such as a presentation or a single slide. It yields that instance, then every model instance nested inside it, in pre-order.

A common use case is searching a document’s text. The following example prints the text of every Text and TextRun on each slide:

from creator_studio_doc_format.core import KeyxDocument, Text, TextRun
from creator_studio_doc_format.navigation import iterate_models

doc = KeyxDocument.open("presentation.keyx")
# Per slide, because the presentation also holds placeholder text from
# slide layouts.
for number, slide in enumerate(doc.presentation.slides, start=1):
    for item in iterate_models(slide):
        if isinstance(item.model, (TextRun, Text)) and item.model.string:
            print(number, repr(item.model.string))

For creator_studio_doc_format/examples/fixtures/Tidal_en.keyx, the output starts with:

1 'A theme built for testing, not for sale'
2 'Example Company'
2 ' · Confidential'
3 '#'
7 'Photo caption sample'
8 'Testing is the ultimate confidence.'
8 'A. Synthetic Author'
11 'Second line'

Each item that iterate_models yields is an IteratedModel, which holds the model instance together with where it sits in the tree. An item’s ancestors lists the model instances that enclose it, starting from the outermost. Its path names the fields that lead to it.

The following example finds the caption text inside an Image:

from creator_studio_doc_format.core import Image

for number, slide in enumerate(doc.presentation.slides, start=1):
    for item in iterate_models(slide):
        if not (isinstance(item.model, (TextRun, Text)) and item.model.string):
            continue

        if any(isinstance(ancestor, Image) for ancestor in item.ancestors):
            print(number, repr(item.model.string))

For creator_studio_doc_format/examples/fixtures/Tidal_en.keyx, it prints 7 'Photo caption sample'.

Explore an unfamiliar document

When you don’t yet know what a document contains, print only part of its tree. Limiting the depth and length is a quick way to see its structure. Lower the limits until the output fits, then descend into the branch you want and raise them again.

This library doesn’t depend on rich, so install it separately with pip install rich. The following example uses rich to print the top levels of the presentation’s tree:

from rich.pretty import pretty_repr

print(
    pretty_repr(
        doc.presentation,
        max_depth=3,  # Stays out of the deeply nested styles.
        max_length=8,  # Truncates long contents lists.
        max_string=80,  # Keeps one slide's body text from filling the screen.
    )
)

Read resources only when you need them

open() reads every resource into memory, so a document with many images or movies opens slowly. open_lazy() reads a resource’s bytes only when you first access them, so the same document opens as fast as its JSON:

with KeyxDocument.open_lazy("big-presentation.keyx") as big:
    print(len(big.presentation.slides))  # This reads no resource.
    photo = big.resources["sample_photo.jpg"]  # This reads only that file.

The document keeps the file open until the with block ends. Read the resources you need inside the block. save and doc.resources.items() read every resource, so call them inside the block too. Editing model instances and running validate_document read no resources.