Slide layout authoring

Create slides from a theme’s layouts, and fill in their text and image placeholders.

Each placeholder has a name that identifies it within a slide layout. A text placeholder takes text, an image placeholder takes an image, and a movie or audio placeholder has no setter.

summarize_slide_layouts

creator_studio_doc_format.authoring.summarize_slide_layouts(theme)[source]

Returns the placeholders of each slide layout.

Parameters:
theme : KeynoteTheme

The theme that holds the slide layouts.

Returns:

Each layout’s placeholders, keyed by layout name, or {} when theme.slide_layouts is absent.

Return type:

dict[str, list[LayoutPlaceholderSummary]]

LayoutPlaceholderSummary

class creator_studio_doc_format.authoring.LayoutPlaceholderSummary(name, object_case, prompt, tag)[source]

A read-only summary of a placeholder in a slide layout.

One summary stands for every placeholder that shares its name and setter. You don’t create a summary directly. summarize_slide_layouts() returns them.

name : str

The placeholder’s name within its layout, which a setter takes. A custom placeholder’s name is its tag. Any other placeholder’s name is its kind’s member name, such as "TITLE".

object_case : str

The case the placeholder’s canvas object holds. A text placeholder holds a case such as "shape" or "textbox", and an image placeholder holds "image".

prompt : str | None

The prompt or sample text Keynote shows in the placeholder. It’s None when there’s none, as for an image, movie, or audio placeholder.

tag : str | None

The label the theme’s designer gives a custom placeholder. It’s None for a predefined one such as "TITLE".

slide_from_layout

creator_studio_doc_format.authoring.slide_from_layout(theme, layout_name)[source]

Returns a new slide made from a layout, as Keynote creates one.

Parameters:
theme : KeynoteTheme

The theme to instantiate the layout from.

layout_name : str

The layout’s name, which is a key of the result of summarize_slide_layouts().

Returns:

The new slide. Only its "TITLE" and "BODY" placeholders start empty. A custom placeholder keeps its sample text, and an image placeholder keeps its sample photo until a setter replaces it. Add the slide to presentation.slides to put it in a document.

Return type:

Slide

Raises:

KeyError – layout_name matches no layout identifier or layout name in theme.

set_slide_placeholder_text

creator_studio_doc_format.authoring.set_slide_placeholder_text(slide, placeholder_name, lines, *, list_levels=None)[source]

Writes lines into a text placeholder and returns the paragraphs it wrote.

Every line takes the placeholder’s own paragraph and text style at every level. Some built-in themes style each level of the sample text differently, so a nested line needs that level’s style. Set it on the returned paragraph.

Parameters:
slide : Slide

The slide to write into.

placeholder_name : str

The text placeholder’s name, as summarize_slide_layouts() reports it.

lines : str | list[str] | None

One paragraph’s text, or a list with one text per paragraph. None or [] clears the placeholder, and "" writes an empty run.

list_levels : list[int] | None

Each line’s list level, from 0 for the top level through 8, with one entry per line. A placeholder with text that is a plain string ignores it.

Returns:

The paragraphs written into the placeholder. They’re live, so changing one changes the slide. A placeholder with text that is a plain string has no paragraphs, so the result is [] and the function joins the lines with newlines.

Return type:

list[Paragraph]

Raises:
  • KeyError – No placeholder named placeholder_name exists on slide.

  • TypeError – placeholder_name names an image, movie, or audio placeholder, or a text placeholder that has no Text.

  • ValueError – list_levels has a different length than lines, or a level outside 0 through 8.

set_slide_placeholder_image

creator_studio_doc_format.authoring.set_slide_placeholder_image(slide, placeholder_name, resource, *, size=None)[source]

Points an image placeholder at a resource and returns the image.

Important

The function doesn’t store the image’s bytes. An indirect resource needs them in doc.resources, and by default the document’s save raises ValueError without them.

Parameters:
slide : Slide

The slide to write into.

placeholder_name : str

The image placeholder’s name, as summarize_slide_layouts() reports it.

resource : Resource

The image’s resource.

size : Size | None

The width and height of the image resource holds. The function then fills the placeholder’s mask with the image and centers it there, as with Replace Image in Keynote. Only the aspect ratio matters. None keeps the placeholder’s geometry, and the image stretches to it.

Returns:

The placeholder’s image, now pointing at resource. It is live, so changing its geometry adjusts the crop.

Return type:

Image

Raises:
  • KeyError – No placeholder named placeholder_name exists on slide.

  • TypeError – placeholder_name names a text, movie, or audio placeholder.

  • ValueError – size has a width or height that isn’t positive.