python-pptx2 2.13.0__py3-none-any.whl

pptx2/skill/references/end-to-end-deck.md

@@ -0,0 +1,231 @@
+# End-to-end: a complete branded deck
+
+A worked example that exercises most of the post-fork features in one
+script: design tokens, recipes, transitions, animations, a chart with
+a custom palette, a layout pass through the linter, and an optional
+thumbnail render.
+
+```python
+"""
+Build a branded Q4 review deck.
+
+Demonstrates: DesignTokens, recipes, deck-wide transitions,
+sequenced animations, chart palette, lint-on-save, thumbnails.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from pptx2 import Presentation
+from pptx2.animation import Emphasis, Entrance, Trigger
+from pptx2.chart.data import CategoryChartData
+from pptx2.design.recipes import (
+    bullet_slide,
+    image_hero_slide,
+    kpi_slide,
+    quote_slide,
+    title_slide,
+)
+from pptx2.design.tokens import DesignTokens
+from pptx2.dml.color import RGBColor
+from pptx2.enum.presentation import MSO_TRANSITION_TYPE
+from pptx2.enum.chart import XL_CHART_TYPE
+from pptx2.util import Inches, Pt
+
+
+# ---- Tokens ------------------------------------------------------------------
+
+TOKENS = DesignTokens.from_dict(
+    {
+        "palette": {
+            "primary":    "#4F9DFF",
+            "neutral":    "#1F2937",
+            "background": "#FFFFFF",
+            "positive":   "#10B981",
+            "negative":   "#EF4444",
+            "on_primary": "#FFFFFF",
+        },
+        "typography": {
+            # NB: recipes look up the keys "heading" and "body". Bare
+            # floats are treated as POINTS; bare ints are EMU.
+            "heading": {"family": "Inter", "size": 44.0, "bold": True},
+            "body":    {"family": "Inter", "size": 18.0},
+        },
+        "shadows": {
+            "card": {"blur": 18.0, "distance": 4.0, "alpha": 0.18},
+        },
+        "radii":    {"card": 12.0},
+        "spacings": {"sm": 8.0, "md": 16.0, "lg": 32.0},
+    }
+)
+
+
+# ---- Build the deck ----------------------------------------------------------
+
+def build(out_path: str | Path) -> Presentation:
+    prs = Presentation()
+    prs.slide_width  = Inches(13.333)
+    prs.slide_height = Inches(7.5)
+
+    # Cover
+    title_slide(
+        prs,
+        title="Q4 2026 Review",
+        subtitle="April 2026",
+        tokens=TOKENS,
+    )
+
+    # KPIs
+    kpi_slide(
+        prs,
+        title="Run-rate metrics",
+        kpis=[
+            {"label": "ARR",         "value": "$182M", "delta": +0.27},
+            {"label": "NDR",         "value": "131%",  "delta": +0.03},
+            {"label": "CAC payback", "value": "8 mo",  "delta": -0.10},
+        ],
+        tokens=TOKENS,
+    )
+
+    # Bullets — annotated with a sequenced paragraph reveal.
+    # bullet_slide adds the title textbox first and the body textbox
+    # second, so shapes[1] is reliably the body.
+    bs = bullet_slide(
+        prs,
+        title="Customer impact",
+        bullets=[
+            "Two flagship customers shipped this week.",
+            "NPS improved 8 points QoQ.",
+            "EU expansion ahead of plan.",
+        ],
+        tokens=TOKENS,
+    )
+    body_tf = bs.shapes[1].text_frame
+    Entrance.fade(bs, body_tf, by_paragraph=True)
+
+    # Custom chart slide — chart palette + quick layout
+    cs = prs.slides.add_slide(prs.slide_layouts[5])
+    cs.shapes.title.text = "ARR by segment ($M)"
+    data = CategoryChartData()
+    data.categories = ["Enterprise", "Mid-market", "SMB", "Self-serve"]
+    data.add_series("FY25", (62, 41, 18,  9))
+    data.add_series("FY26", (94, 55, 23, 10))
+    chart_shape = cs.shapes.add_chart(
+        XL_CHART_TYPE.BAR_CLUSTERED,
+        Inches(1), Inches(1.8), Inches(11), Inches(5.0),
+        data,
+    )
+    chart = chart_shape.chart
+    chart.apply_palette("modern")
+    chart.apply_quick_layout("title_axes_legend_bottom")
+    chart.chart_title.text_frame.text = "ARR by segment ($M)"
+
+    # Quote
+    # Recipes use the Blank layout, so slide.shapes.title is None;
+    # quote_slide adds the quote textbox first (shapes[0]).
+    qs = quote_slide(
+        prs,
+        quote="The new dashboards saved my team a week per sprint.",
+        attribution="Director of Eng, Flagship Customer",
+        tokens=TOKENS,
+    )
+    Emphasis.pulse(qs, qs.shapes[0], trigger=Trigger.AFTER_PREVIOUS)
+
+    # Hero closer (supply your own image path)
+    image_hero_slide(
+        prs,
+        title="Thank you",
+        image="assets/closer.jpg",
+        tokens=TOKENS,
+    )
+
+    # Deck-wide fade transition, then upgrade the cover to Morph
+    prs.set_transition(kind=MSO_TRANSITION_TYPE.FADE, duration=400)
+    prs.slides[0].transition.kind     = MSO_TRANSITION_TYPE.MORPH
+    prs.slides[0].transition.duration = 1500
+
+    # Space-aware safety net: lint every slide, auto-fix off-slide
+    # shapes, and bail loudly if anything is still error-severity.
+    _lint_or_die(prs)
+
+    prs.save(out_path)
+    return prs
+
+
+def _lint_or_die(prs: Presentation) -> None:
+    from pptx2.exc import LintError
+
+    # Pass 1: nudge off-slide shapes inside the slide bounds
+    for slide in prs.slides:
+        slide.lint().auto_fix()
+
+    # Pass 2: collect anything still failing
+    errors = []
+    for i, slide in enumerate(prs.slides):
+        for issue in slide.lint().issues:
+            if issue.severity.value == "error":
+                errors.append(f"slide {i + 1}: {issue}")
+
+    if errors:
+        raise LintError("\n".join(errors))
+
+
+# ---- Optional: rasterise thumbnails ------------------------------------------
+
+def render_thumbnails(prs: Presentation, out_dir: str | Path) -> list[Path]:
+    """Best-effort thumbnail render. Skips gracefully if soffice is missing."""
+    from pptx2.render import ThumbnailRendererUnavailable
+
+    try:
+        return prs.render_thumbnails(out_dir=out_dir)
+    except ThumbnailRendererUnavailable as exc:
+        print(f"thumbnail render skipped: {exc}")
+        return []
+
+
+if __name__ == "__main__":
+    deck = build("q4-review.pptx")
+    render_thumbnails(deck, "thumbs")
+```
+
+## What this exercises
+
+- **Phase 9** — `DesignTokens.from_dict`, four recipes (`title_slide`,
+  `kpi_slide`, `bullet_slide`, `quote_slide`, `image_hero_slide`),
+  shape-style fan-out via `tokens=`.
+- **Phase 5** — `Entrance.fade(..., by_paragraph=True)` for a reveal,
+  `Emphasis.pulse(..., trigger=Trigger.AFTER_PREVIOUS)` chained off
+  the previous click.
+- **Phase 4** — `Slide.transition` for the per-slide Morph,
+  `Presentation.set_transition` for the deck-wide fade.
+- **Phase 10** — `Chart.apply_palette("modern")` and
+  `Chart.apply_quick_layout("title_axes_legend_bottom")`.
+- **Phase 2** — `_lint_or_die(...)` as a generation safety net:
+  `slide.lint().auto_fix()` on every slide to nudge off-slide shapes
+  back inside, then a second pass that raises `LintError` on any
+  remaining error-severity issue (text overflow, residual off-slide,
+  etc).
+- **Phase 10** — optional `render_thumbnails(...)` for downstream
+  tooling, with graceful fall-through when LibreOffice isn't
+  installed.
+
+## Adapting for production
+
+- Persist `TOKENS` separately (YAML or `.pptx`) and load with
+  `DesignTokens.from_yaml(...)` / `DesignTokens.from_pptx(...)`. That
+  way design and code evolve independently.
+- In production, use `slide.tidy()` to repair what can be fixed
+  automatically — it clamps `OffSlide` shapes back inside the bounds,
+  autofits overflowing text frames, and restacks contradicted
+  `layer_above` declarations — then decide what to do with the residual
+  issues: log warning-severity ones but ship the deck, raise on
+  error-severity ones. Keep the stricter "raise on any error" behaviour
+  in CI.
+- For the save-time gate, set `prs.lint_on_save = "raise"` and just call
+  `prs.save(...)`: every slide is linted before anything is written, so
+  a failing deck never reaches disk. `"warn"` logs instead. The
+  equivalent for spec-built decks is
+  `pptx2.compose.from_spec(..., lint="raise")`.
+- If you want the chart palette to align with brand tokens rather than
+  the built-in `"modern"`, pass an explicit list:
+  `chart.apply_palette([TOKENS.palette["primary"], ...])`.

pptx2/skill/references/geometry-and-arrows.md

@@ -0,0 +1,334 @@
+# Geometry, text, arrows, and diagrams (v2.8+)
+
+This reference covers the high-level helpers added in v2.8 for building
+slides programmatically without writing EMU arithmetic or XML for
+arrowheads. Everything here is built on top of the inherited 1.0.2 API
+— the underlying ``add_shape`` / ``add_connector`` / ``text_frame``
+surface still works exactly as it always did.
+
+**Reach for these helpers** when you're generating decks dynamically
+(LLM, JSON spec, DB rows). Reach for the lower-level APIs only when
+the helpers don't cover your case.
+
+---
+
+## The `BBox` value object
+
+Every rectangular region on a slide can be expressed as a
+:class:`BBox` (importable from the package root):
+
+```python
+from pptx2 import BBox
+from pptx2.util import Inches
+
+bb = BBox.from_inches(1, 2, 8, 4)        # left, top, width, height
+bb.right                                  # Emu(9 inches)
+bb.cx, bb.cy                              # centre
+bb.area                                   # int (EMU²)
+```
+
+`BBox` is immutable, frozen-dataclass, and unpacks to `(left, top,
+width, height)` — so it splats straight into add_shape and friends:
+
+```python
+slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, *bb)
+slide.shapes.add_textbox(*bb.inset(all=Inches(0.2)))
+```
+
+### Constructors
+
+```python
+BBox.from_inches(1, 2, 4, 3)
+BBox.from_emu(914400, 1828800, 3657600, 2743200)
+BBox.from_shape(some_shape)              # snapshot
+BBox.from_slide(slide)                   # full slide
+```
+
+`shape.bbox` is the same as `BBox.from_shape(shape)` — a snapshot of
+the shape's current geometry. Mutating the shape afterwards does not
+update the box. `bb.apply_to(shape)` pushes a box back onto a shape.
+
+### Transforms
+
+```python
+bb.shifted(dx=Inches(1))                 # translate
+bb.resized(width=Inches(6))              # change one dimension
+bb.inset(all=Inches(0.2))                # shrink uniformly
+bb.inset(x=Inches(0.5), y=Inches(0.2))   # per-axis
+bb.inset(left=Inches(0.1), right=Inches(0.5), top=Inches(0.2))
+bb.sub(0.25, 0, 0.5, 1.0)                # normalised sub-box
+```
+
+`inset()` with no args is a no-op; negative values expand outward.
+
+### Splits
+
+```python
+bb.columns(3, gap=Pt(16))                # n equal columns  ← the n-up case
+bb.rows(2, gap=Pt(12))                   # n equal rows
+bb.split_h([1, 1])                       # two equal columns
+bb.split_h([2, 1])                       # 66%/33% — unequal, so ratios
+bb.split_h([1, 1, 1], gap=Inches(0.1))
+bb.split_v([1, 2])                       # vertical
+bb.grid(3, 2, gap_x=Inches(0.1))         # row-major 3x2 cells
+```
+
+**Never hand-compute `col_w = (avail - (n - 1) * gap) / n`.** That
+arithmetic is what `columns` / `rows` / `grid` are for, and they
+apportion widths so the cells partition the box *exactly* — no rounding
+drift accumulating into the last column:
+
+```python
+row = BBox.from_inches(0.75, 2.4, 11.8, 2.2)
+for box, item in zip(row.columns(3, gap=Pt(16)), items):
+    card = slide.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, *box)
+    card.shadow.clear()
+    card.corner_radius = Pt(6)
+```
+
+For a 5-column × 2-row panel, `row.grid(5, 2, gap_x=Pt(12), gap_y=Pt(12))`
+returns the ten cells row-major — or use
+`Grid.from_box(row, cols=5, rows=2, gutter=Pt(12))` when you want
+span-aware placement (see `design.md`).
+
+### Predicates
+
+```python
+a.contains(b)                            # b fully inside a
+a.intersects(b)
+a.intersection(b)                        # overlap region (BBox)
+a.union(b)                               # smallest enclosing
+```
+
+---
+
+## One-call text — `slide.shapes.add_text`
+
+The historical pattern (add_textbox + tf.word_wrap + tf.text + paragraph
+alignment + run font.name/size/bold/color) collapses to one call:
+
+```python
+slide.shapes.add_text(
+    BBox.from_inches(1, 1, 8, 1),
+    text="Q4 revenue overview",
+    font="Inter",
+    size_pt=24,
+    bold=True,
+    color="#0B5CFF",                     # hex, RGBColor, or (r,g,b) all OK
+    align="center",                      # str shortcut; no enum import
+    anchor="middle",                     # vertical anchor
+    margin_pt=4,
+    word_wrap=True,
+)
+```
+
+Positional length form also works for back-compat:
+`add_text(Inches(1), Inches(2), Inches(8), Inches(1), text="…")`.
+
+Returns the textbox shape so further mutation is possible.
+
+---
+
+## Hex-string colour shortcuts
+
+`shape.fill_hex(hex)` and `shape.line_hex(hex, weight_pt=)` replace the
+three-line `fill.solid(); fore_color.rgb = RGBColor(...)` ritual. Both
+return `self` for chaining:
+
+```python
+slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, *bb) \
+    .fill_hex("#0B5CFF") \
+    .line_hex("#0D0D0D", weight_pt=1.25)
+```
+
+`hex_color=None` clears the fill (transparent background).
+
+---
+
+## Format-preserving text replacement
+
+`shape.set_text_preserving_format(new_text)` is what you want for
+templated placeholders (e.g. `"<TITLE>"`) — it captures the first
+run's font face / size / colour / bold / italic, rebuilds the text,
+and re-applies the formatting to every new run:
+
+```python
+title_shape.set_text_preserving_format("Q4 revenue overview")
+# Font, size, colour, bold all preserved verbatim.
+```
+
+Multi-line works (`"line one\nline two"`); every paragraph inherits
+the template formatting.
+
+---
+
+## Arrows that actually have arrowheads
+
+`add_connector(MSO_CONNECTOR.STRAIGHT, x1, y1, x2, y2)` returns a line
+with no arrowhead. **Use `add_arrow` instead**:
+
+```python
+slide.shapes.add_arrow(
+    start=box_a,                         # Shape, BBox, or (x, y)
+    end=box_b,
+    head="triangle",                     # "triangle"|"arrow"|"stealth"|"diamond"|"oval"|"none"
+    tail=None,
+    color="#0B5CFF",
+    weight_pt=1.5,
+    style="solid",                       # "solid"|"dashed"|"dotted"
+    inset_pt=6.0,                        # pull endpoints back from shape edges
+    end_side="auto",                     # "top"|"right"|"bottom"|"left"|"auto"
+    route="straight",                    # "straight"|"elbow"|"curved"
+)
+```
+
+When `start` / `end` is a Shape or BBox, the arrow auto-routes to the
+mid-edge nearest the opposite endpoint. `inset_pt` is the small pullback
+applied so the arrowhead triangle doesn't bleed into the target box.
+
+---
+
+## Picture replacement and container detection
+
+For a picture that's broken or sub-quality:
+
+```python
+def diagram(slide, bbox):
+    left, right = bbox.split_h([1, 1], gap=Inches(0.1))
+    slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, *left).fill_hex("#0B5CFF")
+    slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, *right).fill_hex("#FFFFFF")
+
+picture.replace_with(diagram, padding=Inches(0.1))
+```
+
+The picture is deleted; the builder is called with a `BBox` sized to
+the picture's old footprint (minus optional padding). The builder
+draws native shapes in the freed area.
+
+When the picture sits inside a "card" rectangle plus a heading,
+`picture.enclosing_container()` returns the bbox of the enclosing card
+(trimmed to avoid sibling text). This is the bbox you actually want
+to redraw into, not the picture's own bbox:
+
+```python
+container_bbox = picture.enclosing_container(exclude_text=True)
+picture.replace_with(builder, padding=Inches(0.05))
+```
+
+---
+
+## Slide-level helpers
+
+```python
+slide.slide_bbox()                       # BBox of the full slide
+slide.content_bbox()                     # BBox of all non-decorative shapes
+slide.find_empty_region(min_width=Inches(2), min_height=Inches(1))
+slide.tidy()                             # lint + auto_fix(safe subset)
+```
+
+`tidy()` is the one-call cleanup before save: it lints, runs the safe
+subset of auto-fixes (OffSlide clamp, TextOverflow flip), and returns
+the list of fixes applied.
+
+---
+
+## Diagram recipes — `pptx2.diagrams`
+
+Six built-in diagram patterns covering ~80% of architecture-deck
+content. Each takes a slide, a `BBox`, and a small content spec:
+
+```python
+from pptx2.diagrams import (
+    horizontal_pipeline, vertical_pipeline,
+    hub_and_spoke, cycle, decision_tree,
+    comparison_columns,
+)
+
+# Pipeline
+horizontal_pipeline(
+    slide, bbox,
+    steps=["Extract", "Classify", "Enrich", "Output"],
+    accent="#0B5CFF",
+)
+
+# Hub-and-spoke
+hub_and_spoke(
+    slide, bbox,
+    centre="Agent",
+    spokes=["Memory", "Tools", "Planning", "Perception"],
+)
+
+# Cyclic loop
+cycle(
+    slide, bbox,
+    steps=["Observe", "Orient", "Decide", "Act"],
+)
+
+# Decision tree (one level of children optional)
+decision_tree(
+    slide, bbox,
+    root="Is the deck dynamic?",
+    branches=[
+        {"label": "Yes", "children": ["Use lint()", "Use fit_text"]},
+        {"label": "No", "children": ["Author manually"]},
+    ],
+)
+
+# N-column comparison
+comparison_columns(
+    slide, bbox,
+    columns=[
+        {"title": "Pros", "body": ["Fast", "Cheap", "Composable"]},
+        {"title": "Cons", "body": ["New API"]},
+    ],
+)
+```
+
+Each recipe returns a small dataclass (`PipelineResult`, `HubAndSpokeResult`,
+…) exposing the underlying shapes for further tweaks.
+
+Step / column dicts accept per-item `fill` and `text_color` overrides:
+
+```python
+horizontal_pipeline(
+    slide, bbox,
+    steps=[
+        {"label": "Cleaned",   "fill": "#E8F0FF", "text_color": "#0B3D9C"},
+        {"label": "Features",  "fill": "#FFFFFF"},
+    ],
+)
+```
+
+---
+
+## End-to-end audit — `pptx2.audit`
+
+For agents producing a full deck, `audit(prs)` returns a structured
+"what I shipped" summary:
+
+```python
+from pptx2 import audit
+
+report = audit(prs)
+print(report.markdown())
+
+# Or programmatically:
+report.has_errors                        # bool
+report.lint_issues                       # [(slide_idx, LintIssue), ...]
+report.broken_pictures                   # [(idx, picture), ...]
+report.empty_slides                      # [idx, ...]
+report.font_warnings                     # [(idx, font), ...]
+report.size_warnings                     # [(idx, name, bytes), ...]
+```
+
+The audit is read-only — it never mutates the deck. The markdown
+output is structured for chat replies.
+
+---
+
+## Render helpers
+
+`render_slides(prs, slides=[0, 1, 2], out_dir="thumbs",
+name_template="slide-{:02d}.png")` is the friendlier wrapper around
+`render_slide_thumbnails` — same engine, but with sensible argument
+naming and a `name_template` for clean file names.