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.