python-pptx2 2.13.0__py3-none-any.whl

pptx2/skill/references/animations.md

@@ -0,0 +1,189 @@
+# Animations (Phase 5)
+
+`pptx2.animation` ships a preset-only API that maps directly onto
+PowerPoint's built-in animation library. All generated XML is valid
+OOXML and round-trips through PowerPoint without loss.
+
+## Imports
+
+```python
+from pptx2.animation import Entrance, Exit, Emphasis, MotionPath, Trigger
+from pptx2.util import Inches, Pt
+```
+
+`Trigger` is an alias for `pptx2.enum.animation.PP_ANIM_TRIGGER`.
+
+## Triggers and delay
+
+Every preset accepts an optional `trigger` and `delay` (milliseconds):
+
+```python
+Entrance.fade(slide, shape)                                    # default: ON_CLICK
+Entrance.fly_in(slide, shape, trigger=Trigger.WITH_PREVIOUS)
+Entrance.zoom(slide, shape, trigger=Trigger.AFTER_PREVIOUS, delay=500)
+```
+
+## Entrance presets
+
+```python
+Entrance.appear(slide, shape)
+Entrance.fade(slide, shape)
+Entrance.fly_in(slide, shape, direction="bottom")  # also "top", "left", "right"
+Entrance.float_in(slide, shape)
+Entrance.wipe(slide, shape)
+Entrance.zoom(slide, shape)
+Entrance.wheel(slide, shape)
+Entrance.random_bars(slide, shape)
+```
+
+## Exit presets
+
+```python
+Exit.disappear(slide, shape)
+Exit.fade(slide, shape)
+Exit.fly_out(slide, shape)
+Exit.float_out(slide, shape)
+Exit.wipe(slide, shape)
+Exit.zoom(slide, shape)
+```
+
+## Emphasis presets
+
+```python
+Emphasis.pulse(slide, shape)
+Emphasis.spin(slide, shape)
+Emphasis.teeter(slide, shape)
+```
+
+## Per-paragraph reveal
+
+Reveal a text frame one paragraph at a time, fired by a single click:
+
+```python
+body = slide.placeholders[1].text_frame
+Entrance.fade(slide, body, by_paragraph=True)
+```
+
+Supported presets for `by_paragraph=True`: `appear`, `fade`, `wipe`,
+`zoom`, `wheel`, `random_bars`. The first paragraph fires on the
+caller-supplied trigger (or `ON_CLICK`); subsequent paragraphs default
+to `Trigger.AFTER_PREVIOUS`.
+
+## Sequencing — chain effects from one click
+
+```python
+with slide.animations.sequence():
+    Entrance.fade(slide, title_shape)
+    Entrance.fly_in(slide, body_shape)
+    Emphasis.pulse(slide, badge_shape)
+```
+
+Inside the `with` block:
+- The first effect fires on `Trigger.ON_CLICK` (or whatever `start=` is
+  passed to `sequence(start=...)`).
+- Every subsequent effect defaults to `Trigger.AFTER_PREVIOUS`.
+- Explicit per-call triggers still win.
+
+Sequences cannot be nested.
+
+## Grouping — animate sub-shapes as one cluster
+
+`group()` is the right primitive for "this card / row / panel made of
+several sub-shapes should animate as one visual unit." Inside the
+block, the first effect uses the group's `start` trigger and every
+subsequent effect defaults to `Trigger.WITH_PREVIOUS`:
+
+```python
+for i, card in enumerate(cards):
+    with slide.animations.group(delay=0 if i == 0 else 200):
+        Entrance.fade(slide, card.body)
+        Entrance.fade(slide, card.title)
+        Entrance.fade(slide, card.blurb)
+```
+
+This produces one `AFTER_PREVIOUS` start plus N-1 `WITH_PREVIOUS`
+followers per card — much cheaper for PowerPoint to render than the
+same number of independent click-groups, and dramatically reduces the
+"slide takes a beat to appear" lag on dense decks.
+
+Use `group()` for sub-shape clusters; use `sequence()` for cluster-to-
+cluster chains. They can't be combined.
+
+## Inspecting and clearing animations
+
+`SlideAnimations` is now iterable and supports `len()`:
+
+```python
+print(len(slide.animations))                  # how many entries?
+for entry in slide.animations:
+    print(entry.kind, entry.preset, entry.trigger,
+          "shape=", entry.shape.name if entry.shape else None,
+          "duration=", entry.duration, "delay=", entry.delay)
+```
+
+Each entry is a read-only `AnimationEntry`. To remove the entry from
+the slide call `entry.remove()`; to wipe the whole slide call
+`slide.animations.clear()` (returns the count of entries removed).
+
+`slide.animations.purge_orphans()` is the narrower cousin — it only
+removes entries whose target shape has been deleted.
+
+## Motion paths
+
+```python
+MotionPath.line(slide, shape, dx=Inches(2), dy=Inches(1))
+MotionPath.diagonal(slide, shape, dx=Inches(3), dy=Inches(2))
+MotionPath.circle(slide, shape, radius=Inches(1), clockwise=True)
+MotionPath.arc(slide, shape, dx=Inches(3), dy=Inches(0), height=0.4)
+MotionPath.zigzag(slide, shape, dx=Inches(4), dy=Inches(0),
+                  segments=6, amplitude=0.2)
+MotionPath.spiral(slide, shape, radius=Inches(2),
+                  turns=2.5, clockwise=True)
+
+# Pass a raw OOXML motion-path expression
+MotionPath.custom(slide, shape, "M 0 0 L 0.5 0.5 L 1 0")
+```
+
+All preset constructors normalise EMU inputs against the slide
+dimensions before emitting the path attribute, so the *absolute* travel
+distance is preserved across slide sizes.
+
+## Round-trip safety
+
+Animations authored in PowerPoint survive a read–modify–write cycle.
+Generated effects are appended to the existing `<p:tnLst>` timing tree
+without touching pre-existing `<p:par>` nodes:
+
+```python
+prs = Presentation("hand-authored.pptx")
+slide = prs.slides[0]
+Entrance.fade(slide, slide.shapes[0])           # adds, doesn't disturb
+prs.save("with-extra-fade.pptx")
+```
+
+## End-to-end example
+
+```python
+from pptx2 import Presentation
+from pptx2.animation import Entrance, Emphasis, MotionPath, Trigger
+from pptx2.util import Inches
+
+prs = Presentation()
+slide = prs.slides.add_slide(prs.slide_layouts[5])
+slide.shapes.title.text = "Animated demo"
+
+box = slide.shapes.add_textbox(Inches(1), Inches(2), Inches(8), Inches(1))
+box.text_frame.text = "Click anywhere to animate"
+
+# A 3-step click-driven sequence
+with slide.animations.sequence():
+    Entrance.fade(slide, slide.shapes.title)
+    Entrance.fly_in(slide, box, direction="left")
+    Emphasis.pulse(slide, box)
+
+# Extra effect after the sequence: a motion path on the box
+MotionPath.arc(slide, box, dx=Inches(2), dy=Inches(0), height=0.3,
+               trigger=Trigger.AFTER_PREVIOUS)
+
+prs.save("animated.pptx")
+```

pptx2/skill/references/basics.md

@@ -0,0 +1,421 @@
+# Basics — the inherited 1.0.2 surface
+
+Everything in this file works the same as upstream `python-pptx 1.0.2`.
+It's here so you don't have to leave the skill for boring boilerplate.
+
+## Open / create / save
+
+```python
+from pptx2 import Presentation
+
+prs = Presentation()                     # blank deck, default 16:9
+prs = Presentation("template.pptx")      # open existing
+prs.save("out.pptx")
+```
+
+`Presentation(...)` also accepts a binary file-like object — useful for
+HTTP responses or in-memory generation:
+
+```python
+import io
+buf = io.BytesIO()
+prs.save(buf)
+buf.seek(0)
+return buf.getvalue()
+```
+
+## Slide size
+
+```python
+from pptx2.util import Inches
+
+prs.slide_width  = Inches(13.333)        # 16:9 widescreen
+prs.slide_height = Inches(7.5)
+```
+
+## Adding slides
+
+```python
+title_layout = prs.slide_layouts[0]      # 0 = Title, 1 = Title+Content,
+blank_layout = prs.slide_layouts[6]      # 5 = Title only, 6 = Blank, ...
+
+slide = prs.slides.add_slide(title_layout)
+slide.shapes.title.text = "Q4 Review"
+slide.placeholders[1].text = "April 2026"
+```
+
+Layouts are master-dependent; use `prs.slide_master.slide_layouts` if you
+want to be explicit, or iterate `for L in prs.slide_layouts: print(L.name)`
+to discover what the template ships.
+
+## Text boxes
+
+```python
+from pptx2.util import Inches, Pt
+from pptx2.dml.color import RGBColor
+
+box = slide.shapes.add_textbox(Inches(1), Inches(1), Inches(8), Inches(1))
+tf = box.text_frame
+tf.word_wrap = True
+
+p = tf.paragraphs[0]
+p.text = "Hello world"
+p.font.name = "Inter"
+p.font.size = Pt(36)
+p.font.bold = True
+p.font.color.rgb = RGBColor(0x1F, 0x29, 0x37)
+
+p2 = tf.add_paragraph()
+p2.text = "Subtitle goes here"
+p2.font.size = Pt(18)
+```
+
+### One call instead of per-run styling
+
+Setting `font.*` on every paragraph is the single most common source of
+bloated deck-building code, and it silently misses runs you didn't
+enumerate. `set_paragraph_defaults` applies to *every* paragraph and run
+in the frame, including ones added later in the same breath:
+
+```python
+tf.text = "Headline"
+tf.add_paragraph().text = "Supporting line"
+
+tf.set_paragraph_defaults(
+    font_name="Inter", size=Pt(14), bold=True, color="#333333",
+)
+```
+
+Accepted kwargs are exactly `font_name`, `size`, `bold`, `italic`,
+`color` — all keyword-only, all optional. Note it does **not** take
+spacing arguments; `space_before` / `space_after` / `line_spacing` are
+per-paragraph (below).
+
+### Spacing and margins
+
+```python
+p.space_before = Pt(6)
+p.space_after  = Pt(6)
+p.line_spacing = 1.2               # multiple, or Pt(20) for exact
+
+tf.margin_left = Inches(0.2)       # also margin_right/top/bottom
+```
+
+Paragraphs can also be built run-by-run when you need mixed styling in
+one line:
+
+```python
+p = tf.add_paragraph()
+run = p.add_run(); run.text = "Bold lead-in. "
+run.font.bold = True
+run.font.underline = True
+p.add_line_break()                 # soft break, stays in the paragraph
+```
+
+### Run-level type styling
+
+`font` exposes the run-property knobs that separate "looks branded" from
+"looks generated" — set them on a paragraph's `font` or a specific run's
+`font`:
+
+```python
+eyebrow.font.all_caps = True          # or .small_caps = True (mutually exclusive)
+eyebrow.font.letter_spacing = Pt(2)   # tracking; negative tightens
+old.font.strikethrough = True
+units.font.superscript = True         # or .subscript (share one baseline)
+```
+
+All are tri-state: `None` (the default) inherits from the theme/master,
+`True`/`False` write an explicit override. They round-trip and validate
+against the OOXML schema.
+
+### Text effects (outline, shadow, glow)
+
+Per-run glyph effects live on `run.font`, mirroring shape
+`.line`/`.shadow`/`.glow`:
+
+```python
+run.font.outline.color.rgb = "FF0000"   # coloured glyph outline...
+run.font.outline.width = Pt(1)          # ...of a given stroke width
+run.font.shadow.color.rgb = "808080"; run.font.shadow.blur_radius = Pt(3)
+run.font.glow.color.rgb = "00B0F0";   run.font.glow.radius = Pt(6)
+```
+
+Reads are non-mutating — nothing is written until you assign, so theme
+inheritance is preserved.
+
+## Auto shapes
+
+```python
+from pptx2.enum.shapes import MSO_SHAPE
+
+card = slide.shapes.add_shape(
+    MSO_SHAPE.ROUNDED_RECTANGLE,
+    left=Inches(1), top=Inches(2),
+    width=Inches(4), height=Inches(2.5),
+)
+card.fill.solid()
+card.fill.fore_color.rgb = RGBColor(0xF8, 0xFA, 0xFC)
+card.line.color.rgb = RGBColor(0xE5, 0xE7, 0xEB)
+card.line.width = Pt(1)
+```
+
+### Per-color alpha (transparency)
+
+Both fill and line colours expose `alpha` in the `[0.0, 1.0]` range —
+useful for hairline dividers, glow shapes, and translucent overlays.
+Assign after a colour is set:
+
+```python
+divider.line.color.rgb   = RGBColor(0x0D, 0x0D, 0x0D)
+divider.line.color.alpha = 0.08     # 8% opaque hairline
+```
+
+### Two-stop linear gradients
+
+```python
+bar.fill.linear_gradient("#06D6FE", "#B14AED", angle=90)   # top→bottom
+```
+
+`angle` follows the OOXML convention: `0` is left→right, `90` is
+top→bottom, `180` is right→left, `270` is bottom→top.
+
+→ **Multi-stop gradients, gradient kinds, mutable stop lists, and the
+full alpha surface live in `effects.md`** — the canonical fills and
+effects reference. Don't go looking in two places.
+
+## Pictures
+
+```python
+pic = slide.shapes.add_picture(
+    "hero.jpg",
+    left=Inches(0), top=Inches(0),
+    width=prs.slide_width, height=prs.slide_height,
+)
+```
+
+### Cropping
+
+Crop values are *fractions of the original image*, not lengths — `0.1`
+trims 10% off that edge. They compose with the placement box, so crop
+first, then size:
+
+```python
+pic = slide.shapes.add_picture("hero.png", Inches(1), Inches(1),
+                               width=Inches(4))
+pic.crop_left = 0.10               # also crop_right/top/bottom
+pic.crop_top  = 0.05
+pic.alt_text  = "Q4 revenue by segment"   # set this; screen readers need it
+```
+
+### Anchored placement
+
+`add_picture`, `add_shape`, and `add_textbox` accept an
+``anchor=`` keyword that collapses the
+``add → measure → reposition`` idiom for branding elements:
+
+```python
+# Logo at bottom-right with a 0.25" margin, height-only sizing:
+slide.shapes.add_picture(
+    "logo.png",
+    anchor="bottom-right",
+    margin=Inches(0.25),
+    height=Inches(0.32),
+)
+
+# Title centred in the top half of a parent card:
+slide.shapes.add_textbox(
+    Inches(0), Inches(0), Inches(2), Inches(0.5),
+    anchor="top-center", margin=Inches(0.25),
+    container=card,         # any shape with .width / .height
+)
+```
+
+`anchor` is one of `top-left`, `top-center`, `top-right`,
+`middle-left`, `middle-center` (or bare `center`),
+`middle-right`, `bottom-left`, `bottom-center`, `bottom-right`.
+Both `center` / `centre` spellings are accepted. `container` is the
+slide by default; pass any shape (or anything exposing
+`.width` / `.height`) to anchor inside a card / group / placeholder.
+
+## Grouping shapes
+
+`slide.shapes.add_group_shape()` returns a `GroupShape` whose
+`.shapes` collection has the same `add_*` methods as a slide. The
+group's offset/extent shrink-wrap to its members as you add them.
+
+```python
+group = slide.shapes.add_group_shape()
+group.shapes.add_shape(MSO_SHAPE.RECTANGLE, Inches(1), Inches(1), Inches(2), Inches(1))
+group.shapes.add_shape(MSO_SHAPE.OVAL, Inches(4), Inches(2), Inches(1), Inches(1))
+
+group.fill.solid()                 # tint the whole group (members paint on top)
+group.fill.fore_color.rgb = "1F4E79"
+group.move(Inches(0.5), Inches(0)) # translate group + every member, O(1)
+
+for shape in group.walk():         # depth-first, recurses into nested groups
+    ...                            # filter shape.shape_type for leaves only
+
+group.fit_to_children()            # re-tighten bbox after editing members directly
+promoted = group.ungroup()         # dissolve; members keep their on-screen geometry
+```
+
+- A group admits a **fill** but not a **line** — the OOXML schema has
+  no `a:ln` on `p:grpSpPr`, so there is intentionally no `group.line`.
+  (Outline a group by outlining a backing rectangle inside it.)
+- `ungroup()` returns the promoted shapes and preserves z-order. It
+  raises `ValueError` on a rotated/flipped group; reset rotation and
+  flip to 0 first.
+
+## Tables
+
+```python
+table_shape = slide.shapes.add_table(
+    rows=4, cols=3,
+    left=Inches(1), top=Inches(2),
+    width=Inches(8), height=Inches(3),
+    style="clean",   # disable inherited style flags for hand-styled tables
+)
+table = table_shape.table
+
+# Header
+for i, label in enumerate(("Metric", "Value", "Δ QoQ")):
+    cell = table.cell(0, i)
+    cell.text = label
+    cell.text_frame.paragraphs[0].font.bold = True
+
+# Body
+for row, (k, v, d) in enumerate([("ARR", "$182M", "+27%"),
+                                  ("NDR", "131%",  "+3%"),
+                                  ("CAC payback", "8 mo", "−1 mo")], start=1):
+    table.cell(row, 0).text = k
+    table.cell(row, 1).text = v
+    table.cell(row, 2).text = d
+```
+
+Pass `style="clean"` whenever you plan to apply custom cell borders
+or fills. The default inherited table style otherwise overlays them
+and renders inconsistently across PowerPoint and LibreOffice.
+
+(See `tables.md` for `Cell.borders`, the post-fork addition.)
+
+## Charts
+
+```python
+from pptx2.chart.data import CategoryChartData
+from pptx2.enum.chart import XL_CHART_TYPE
+
+data = CategoryChartData()
+data.categories = ["Q1", "Q2", "Q3", "Q4"]
+data.add_series("ARR", (100, 130, 155, 182))
+
+chart_shape = slide.shapes.add_chart(
+    XL_CHART_TYPE.COLUMN_CLUSTERED,
+    Inches(1), Inches(2), Inches(8), Inches(4.5),
+    data,
+)
+chart = chart_shape.chart
+chart.has_title = True
+chart.chart_title.text_frame.text = "ARR ($M)"
+```
+
+(See `charts.md` for chart palettes, quick layouts, and per-series fills.)
+
+## Knowing what a shape is
+
+Before touching a shape you found by iteration, ask what it actually is
+— the accessors raise rather than return `None` when the shape has no
+such content:
+
+```python
+for shape in slide.shapes:
+    if shape.has_text_frame:
+        print(shape.text_frame.text)
+    if shape.has_table:
+        print(shape.table.rows)
+    if shape.has_chart:
+        print(shape.chart.chart_type)
+    if shape.is_placeholder:
+        print("placeholder idx", shape.placeholder_format.idx,
+              "type", shape.placeholder_format.type)
+    print(shape.shape_id, shape.name)   # shape_id is unique per slide
+```
+
+`shape.delete()` removes a shape *and* purges any animation timing
+entries that targeted it — PowerPoint silently "repairs" decks with
+orphan timing references, so prefer it over detaching the element by
+hand.
+
+## Iterating an existing deck
+
+```python
+prs = Presentation("input.pptx")
+for slide in prs.slides:
+    for shape in slide.shapes:
+        if shape.has_text_frame:
+            for para in shape.text_frame.paragraphs:
+                for run in para.runs:
+                    print(run.text)
+```
+
+## Common units
+
+```python
+from pptx2.util import Inches, Pt, Cm, Emu, Mm
+
+Inches(1)   # 914400 EMU
+Pt(12)      # 152400 EMU
+Cm(2.54)    # ≈ Inches(1)
+```
+
+Use these everywhere — never write the EMU integers directly.
+
+Arithmetic on lengths is fine — python-pptx2 coerces float coordinates
+to integer EMU at the API boundary, so this works:
+
+```python
+card_w = (Inches(12.33) - Inches(0.25)) / 2   # produces a float
+slide.shapes.add_chart(chart_type, x, y, card_w, height, data)
+slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, left, top, card_w, h)
+shape.width = card_w   # setter coerces too
+```
+
+Both ``/`` (true division → float) and ``//`` (floor division → int)
+work; pick whichever reads more cleanly. The coercion is round-half-
+to-even, so it's unbiased over long expression chains.
+
+### International & layout text properties
+
+```python
+p = tf.paragraphs[0]
+p.rtl = True                       # right-to-left (Hebrew / Arabic / Farsi)
+p.start_at = 5                     # numbered list starting at 5 (arabicPeriod)
+p.set_numbered("romanLcPeriod", 3) # i. ii. iii. starting at 3
+
+tf.column_count = 2                # two-column text body
+tf.column_spacing = Pt(18)         # gutter between columns
+
+p.tab_stops.add_tab_stop(Inches(1), "center")   # left | center | right | decimal
+```
+
+### Sections, slide order, and speaker notes
+
+```python
+# Named sections (PowerPoint outline / slide-sorter groupings)
+prs.sections.add("Intro", start_slide_index=0)
+prs.sections.add("Body",  start_slide_index=2)
+for section in prs.sections:
+    print(section.name, section.slide_ids)   # section.name is read/write
+
+# Reorder slides without touching XML
+prs.slides.move(0, 2)              # send slide 0 to position 2
+prs.slides.reorder([2, 0, 1])     # full permutation (indices or Slide objects)
+
+# First-class speaker notes
+slide.notes = "Remember to thank the sponsors."   # creates the notes slide
+print(slide.notes)                # "" when the slide has no notes
+```
+
+`start_slide_index` claims every slide from that position to the deck
+end. `move` raises `IndexError` out of range; `reorder` raises
+`ValueError` unless given a clean permutation.