Creating and editing a presentation

Install the library, create a presentation with one slide and open it in Keynote, then edit it.

A .keyx file stores a presentation in a form that code can read and write, and Keynote opens it like any other presentation. The library represents that file as Python objects. With the library, you build and change a presentation without writing the file’s contents by hand.

On this page, you install the library and save a presentation with one slide as hello.keyx. You then open that file, change its contents as you would any Python object, and save it again.

Install the library

Run pip in a terminal:

% pip install creator-studio-doc-format

Create a document

A document is a presentation together with its presets, manifest, and resources. A Presentation is a tree of model instances.

Build a Presentation with a slide that holds a text box, wrap it in a KeyxDocument, and save it as hello.keyx, which you can open in Keynote:

from creator_studio_doc_format.core import (
    CanvasObject,
    CharacterProperties,
    Geometry,
    KeynoteTheme,
    KeyxDocument,
    LayoutProperties,
    ParagraphProperties,
    Position,
    Presentation,
    Size,
    Slide,
    SlideObject,
    Stroke,
    Text,
    Textbox,
)

title = Textbox(
    geometry=Geometry(
        position=Position(x=160, y=440), size=Size(width=1600, height=200)
    ),
    stroke=Stroke(empty=True),
    layout_properties=LayoutProperties(vertical_alignment="center"),
    paragraph_properties=ParagraphProperties(
        alignment="center",
        character_properties=CharacterProperties(font_size=96),
    ),
    text=Text(string="Hello, Keynote"),
)
slide = Slide(contents=[SlideObject(object=CanvasObject(textbox=title))])

doc = KeyxDocument(
    Presentation(
        # Without a theme, Keynote uses White in the system locale. The name is
        # localized, so pair it with a locale.
        theme=KeynoteTheme(name="White", locale="en_US"),
        # Without a slide size, Keynote has to supply one, such as the theme's,
        # or reject the document.
        slide_size=Size(width=1920, height=1080),
        slides=[slide],
    )
)

doc.save("hello.keyx")

Most objects on a slide have a Geometry, measured in points. The object sits inside a CanvasObject, which sits inside a SlideObject. slide_size sets the slide’s size in the same units.

A position is measured from the slide’s top-left corner, with y increasing downward. The format’s numeric conventions give the units of angles and of the quantities that aren’t lengths.

Edit an existing document

Open a document with KeyxDocument.open, change its model instances, and save it. To edit a presentation you made in Keynote, export it first by choosing File > Export To > Keynote X.

Important

A .keyx file leaves out some Keynote features, such as transitions, builds, and comments. The format’s release notes list each one. Exporting a presentation drops them, so the document you edit and save holds none of them.

Every model is a Pydantic model, so you edit a model instance as you would any Python object. Read and assign its attributes, and change its lists in place. There are no getters or setters to call.

The following example reads, assigns, constructs, and deletes model instances in hello.keyx:

from creator_studio_doc_format.validation import validate_document

doc = KeyxDocument.open("hello.keyx")
first = doc.presentation.slides[0]  # Read.
first.note = Text(string="Welcome everyone, then move on.")  # Assign.

doc.presentation.slides.append(Slide())  # Construct.
del first.contents[0]  # Delete.

doc.save("edited.keyx", pre_save_hooks=[validate_document])

To catch an edit that breaks the format’s rules before anything is written, pass validate_document() in the pre_save_hooks argument of save.