[Epic] Animations & Transitions [STRATEGIC]

[MHoroszowski]

Problem

The PowerPoint timing tree (<p:timing>) is the single largest unmodelled subsystem in python-pptx. It governs entrance / exit / emphasis animations on shapes, motion paths, slide transitions (fade, push, wipe, morph), and trigger-based timing. The XML round-trips today via CT_SlideTiming as an opaque preserved blob, but there is no Python API at any level — neither read nor write. PowerPoint Morph transitions (scanny/python-pptx#942), shape entrance animations (scanny/python-pptx#1106), animation delays (scanny/python-pptx#861), and timing programmability (scanny/python-pptx#256, 8c) are all unanswered. ECMA-376 §19.5.41 lists ~200 elements in the timing tree alone — this epic is STRATEGIC DEBT and needs phased delivery across multiple releases.

Sub-features

Phase A — Slide transitions (small, valuable, do first)

• Slide.transition accessor: type (fade / push / wipe / cover / split / cut / dissolve / morph / random), speed (slow / med / fast or duration), advance-on-click vs advance-after-time, sound
• Convenience: Slide.transition.morph() for the high-demand morph transition
• Round-trip preservation of all unmodelled transitions

Phase B — Per-shape effect read API

• Shape.animations collection — read-only enumeration of effects targeting this shape (entrance / exit / emphasis / motion-path / trigger / delay)
• Effect.delay, .duration, .preset_class, .preset_id, .preset_subtype, .trigger

Phase C — Per-shape effect write API

• Shape.add_animation(effect_type, preset, delay=, duration=, trigger=) — author entrance/exit/emphasis on shapes
• Common presets: appear, fly-in, fade-in, fly-out, fade-out, pulse, spin, grow/shrink

Phase D — Motion paths and advanced timing

• <p:animMotion> motion-path API (line, arc, custom SVG-style path)
• Sequential / parallel timing trees (<p:par> / <p:seq>)
• Click-trigger and shape-trigger conditions

Prior art

• Open PRs: none in upstream queue addressing the timing tree.
• User issues this would close: #102, #256, #264, #376, #400, #861, #942, #954, #1004, #1106.
• OOXML: PresentationML §19.5.50 <p:transition> (slide transitions, simple), §19.5.41 <p:timing> → <p:tnLst> → <p:par> → <p:cTn> → <p:childTnLst> (the deep timing tree, ~200 elements). Morph: <p:morph> in P2010+ extLst. Motion: §19.5.4 <p:animMotion>.
• Code paths: src/pptx/oxml/slide.py (existing CT_SlideTiming), new src/pptx/animation/ subpackage, new src/pptx/transitions.py.

Acceptance criteria

• Phase A: 100% of upstream slide-transition presets author and round-trip; Morph transition specifically lands.
• Phase B: read-API enumerates all 100+ animation presets across a corpus of test decks.
• Phase C: 80%+ of common entrance/exit/emphasis presets author correctly.
• Phase D: motion-path round-trip + author at least line+arc.
• 50+ unit tests across phases.
• Behave scenarios per phase.

Effort: L

Strategic debt — multi-quarter scope. Recommend phased: Phase A in one release (~3 weeks), Phase B in the next (~4 weeks), Phase C in the third (~6 weeks), Phase D as opt-in (~6 weeks). Total ~5 months across 4 releases.

Labels

status:strategic-debt, priority:P2. Highest-engagement single-domain unmet demand on the upstream tracker once you exclude already-shipped categories.