Libreoffice Impress

Structured Targets: ImpressTarget

from impress import ImpressTarget

ImpressTarget(
    kind=(
        "slide" | "shape" | "text" | "table" | "chart" |
        "media" | "notes" | "master_page" | "list" | "insertion" | "image"
    ),
    slide_index=None,
    shape_name=None,
    shape_index=None,
    shape_type=None,
    placeholder=None,
    text=None,
    after=None,
    before=None,
    occurrence=None,
    master_name=None,
)

Target kinds

Resolution rules

• Slide indices are zero-based.
• shape_name and shape_index are mutually exclusive.
• placeholder targets support explicit values such as title, body, and subtitle.
• Use after and before to narrow text or list resolution inside one resolved text-bearing object.
• For object targets, prefer shape_name; use shape_index only when slide order is stable.
• delete_item() accepts any non-slide delete target: text, notes, list, shape, image, table, chart, or media.

Formatting Payload: TextFormatting

from impress import TextFormatting

TextFormatting(
    bold=None,
    italic=None,
    underline=None,
    font_name=None,
    font_size=None,
    color=None,          # named color or integer
    align=None,          # "left" | "center" | "right" | "justify"
)

Notes:

• At least one formatting field must be set.
• Color accepts a named color or 0xRRGGBB integer.
• Paragraph alignment is applied through the same formatting payload as character styling.

Geometry Payload: ShapePlacement

from impress import ShapePlacement

ShapePlacement(x_cm=1.0, y_cm=2.0, width_cm=8.0, height_cm=4.0)

• Geometry values are in centimetres.
• Width and height must be positive.

List Items

from impress import ListItem

ListItem(text="Confirm scope", level=0)

• level is zero-based nesting.
• Nesting cannot skip levels.
• List editing is structural; do not add manual - prefixes.
• Headless snapshot rendering may not visibly paint bullets even when list metadata is correct.

Patch DSL

Use patch() or session.patch() to apply ordered operations.

[operation]
type = replace_text
target.kind = text
target.slide_index = 2
target.placeholder = body
target.text = Quarterly revenue rose 18%
new_text = Quarterly revenue rose 21%

[operation]
type = insert_list
target.kind = insertion
target.slide_index = 2
target.shape_name = Agenda Box
target.after = Action Items
list.ordered = false
items <<JSON
[
  {"text": "Confirm scope", "level": 0},
  {"text": "Review outputs", "level": 0},
  {"text": "Update notes", "level": 1}
]
JSON

[operation]
type = delete_item
target.kind = chart
target.slide_index = 4
target.shape_name = Disposable Chart

Supported operation types

• add_slide
• delete_slide
• move_slide
• duplicate_slide
• insert_text
• replace_text
• format_text
• insert_list
• replace_list
• insert_text_box
• insert_shape
• delete_item
• insert_image
• replace_image
• insert_table
• update_table
• insert_chart
• update_chart
• insert_media
• replace_media
• set_notes
• apply_master_page
• set_master_background

Patch value rules

• Use target.* fields for the primary target.
• Use master.* fields for apply_master_page.
• Use format.* fields for TextFormatting.
• Use placement.* fields for ShapePlacement.
• Use list.ordered plus JSON items for list operations.
• items and data must be valid JSON.
• Heredoc blocks are supported with <<TAG ... TAG for multiline text or JSON.

Modes

• atomic stops on first failure, restores the original file bytes, and persists nothing.
• best_effort keeps successful earlier operations and records later failures.

PatchApplyResult fields:

• mode
• overall_status = "ok" | "partial" | "failed"
• operations = list of PatchOperationResult
• document_persisted

For standalone patch(path, ...), document_persisted means the changes were saved to disk. For session.patch(...), it means the patch produced successful mutations in the current open session state.

Example: Edit a Deck in Session

from pathlib import Path

from impress import (
    ImpressTarget,
    ListItem,
    ShapePlacement,
    TextFormatting,
    open_impress_session,
)
from impress.core import create_presentation

output = str(Path("test-output/demo.odp").resolve())
create_presentation(output)

with open_impress_session(output) as session:
    session.add_slide(layout="TITLE_AND_CONTENT")
    session.replace_text(
        ImpressTarget(kind="text", slide_index=1, placeholder="title"),
        "Executive Summary",
    )
    session.replace_text(
        ImpressTarget(kind="text", slide_index=1, placeholder="body"),
        "Quarterly revenue rose 18%.",
    )
    session.insert_text_box(
        ImpressTarget(kind="slide", slide_index=1),
        "Action Items",
        ShapePlacement(1.0, 5.0, 10.0, 4.0),
        name="Agenda Box",
    )
    session.insert_list(
        [
            ListItem(text="Confirm scope", level=0),
            ListItem(text="Review output", level=0),
            ListItem(text="Update packaging", level=1),
        ],
        ordered=False,
        target=ImpressTarget(
            kind="insertion",
            slide_index=1,
            shape_name="Agenda Box",
            after="Action Items",
        ),
    )
    session.format_text(
        ImpressTarget(
            kind="text",
            slide_index=1,
            placeholder="body",
            text="Quarterly revenue rose 18%.",
        ),
        TextFormatting(bold=True, align="center"),
    )

Example: Patch an Existing Presentation

from impress import patch

result = patch(
    "/abs/path/demo.odp",
    """
[operation]
type = replace_text
target.kind = text
target.slide_index = 1
target.placeholder = body
new_text = Quarterly revenue rose 21%.

[operation]
type = insert_media
target.kind = slide
target.slide_index = 1
media_path = /abs/path/demo.wav
placement.x_cm = 1.0
placement.y_cm = 9.0
placement.width_cm = 5.0
placement.height_cm = 3.0
name = Demo Media

[operation]
type = delete_item
target.kind = media
target.slide_index = 1
target.shape_name = Demo Media
""",
    mode="best_effort",
)

print(result.overall_status)

Snapshots

from pathlib import Path
from impress import snapshot_slide

result = snapshot_slide(doc_path, 0, "/tmp/slide1.png")
print(result.file_path, result.width, result.height)
Path(result.file_path).unlink(missing_ok=True)

Use snapshots to verify slide layout after text edits, master-page changes, table/chart placement, or other visual operations.

Common Mistakes

• Passing a relative path; UNO-facing Impress APIs expect absolute file paths.
• Using one-based slide indices.
• Using fragile single-word text anchors when a fuller phrase is available.
• Expecting exact shape names after LibreOffice-native slide duplication; UNO may rename duplicates such as Name 1.
• Supplying malformed JSON in items or data patch fields.
• Calling session methods after session.close().