python-pptx2 2.13.0__py3-none-any.whl

pptx2/shared.py

@@ -0,0 +1,82 @@
+"""Objects shared by pptx2 modules."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pptx2.opc.package import XmlPart
+    from pptx2.oxml.xmlchemy import BaseOxmlElement
+    from pptx2.types import ProvidesPart
+
+
+class ElementProxy(object):
+    """Base class for lxml element proxy classes.
+
+    An element proxy class is one whose primary responsibilities are fulfilled by manipulating the
+    attributes and child elements of an XML element. They are the most common type of class in
+    python-pptx other than custom element (oxml) classes.
+    """
+
+    def __init__(self, element: BaseOxmlElement):
+        self._element = element
+
+    def __eq__(self, other: object) -> bool:
+        """Return |True| if this proxy object refers to the same oxml element as does *other*.
+
+        ElementProxy objects are value objects and should maintain no mutable local state.
+        Equality for proxy objects is defined as referring to the same XML element, whether or not
+        they are the same proxy object instance.
+        """
+        if not isinstance(other, ElementProxy):
+            return False
+        return self._element is other._element
+
+    def __ne__(self, other: object) -> bool:
+        if not isinstance(other, ElementProxy):
+            return True
+        return self._element is not other._element
+
+    @property
+    def element(self):
+        """The lxml element proxied by this object."""
+        return self._element
+
+
+class ParentedElementProxy(ElementProxy):
+    """Provides access to ancestor objects and part.
+
+    An ancestor may occasionally be required to provide a service, such as add or drop a
+    relationship. Provides the :attr:`_parent` attribute to subclasses and the public
+    :attr:`parent` read-only property.
+    """
+
+    def __init__(self, element: BaseOxmlElement, parent: ProvidesPart):
+        super(ParentedElementProxy, self).__init__(element)
+        self._parent = parent
+
+    @property
+    def parent(self):
+        """The ancestor proxy object to this one.
+
+        For example, the parent of a shape is generally the |SlideShapes| object that contains it.
+        """
+        return self._parent
+
+    @property
+    def part(self) -> XmlPart:
+        """The package part containing this object."""
+        return self._parent.part
+
+
+class PartElementProxy(ElementProxy):
+    """Provides common members for proxy-objects that wrap a part's root element, e.g. `p:sld`."""
+
+    def __init__(self, element: BaseOxmlElement, part: XmlPart):
+        super(PartElementProxy, self).__init__(element)
+        self._part = part
+
+    @property
+    def part(self) -> XmlPart:
+        """The package part containing this object."""
+        return self._part

pptx2/skill/SKILL.md

@@ -0,0 +1,450 @@
+---
+name: python-pptx2
+description: Build PowerPoint (.pptx) decks from Python with the python-pptx2 library — a fork of power-pptx / python-pptx. Use this skill whenever the user wants to generate, mutate, lint, theme, animate, or render PowerPoint decks programmatically. The headline reason this line exists is **space-awareness**: text that doesn't overflow its box and shapes that don't slide off the edges of the slide. Reach for it especially when generation is dynamic (LLM, DB, CLI, JSON spec) and the deck has to look right without manual cleanup. Other features include native LaTeX equations, visual effects, animations, transitions, theme writer, design tokens, slide recipes, slide thumbnails, chart palettes, SVG embedding, 3D, and SmartArt text substitution.
+---
+
+# python-pptx2
+
+`python-pptx2` is a fork of `power-pptx` (and, through it, `python-pptx`),
+distributed on PyPI as `python-pptx2` and imported as `import pptx2`.
+Use it for every PowerPoint generation / mutation task.
+
+## The headline: space-aware authoring
+
+The single biggest reason this fork exists is to make programmatic
+decks **physically correct**: text doesn't overflow its container,
+shapes don't sit off the slide, and elements that overlap do so on
+purpose. Three layered tools — used together — catch ~all real-world
+issues:
+
+1. **`TextFrame.fit_text(...)`** measures with Pillow font metrics
+   and bakes a fitting size into the XML *before* save.
+2. **`text_frame.auto_size = MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE`** lets
+   PowerPoint shrink at render time as a fallback.
+3. **`slide.lint()`** catches what slipped through; `auto_fix()`
+   nudges off-slide shapes back inside.
+
+**Read `references/space-aware-authoring.md` first** if the user is
+generating decks from any dynamic input. It's the reason this skill
+exists.
+
+The whole upstream 1.0.2 API still works — the rest of this skill
+focuses on the post-fork additions because they're what's most often
+missed by snippets pulled from the wider internet.
+
+## Cheat sheet (most common operations)
+
+The 25 calls that cover ~90% of deck-generation tasks. Reach for
+`references/geometry-and-arrows.md` for the full surface; this is the
+working set:
+
+```python
+from pptx2 import Presentation, BBox, audit
+from pptx2.diagrams import horizontal_pipeline, hub_and_spoke, cycle
+from pptx2.enum.shapes import MSO_SHAPE
+from pptx2.util import Inches, Pt
+
+# --- open / save ---
+prs = Presentation()                       # new blank deck
+prs = Presentation("file.pptx")            # open existing
+prs.save("out.pptx")
+
+# --- slides ---
+slide = prs.slides.add_slide(prs.slide_layouts[5])   # Title Only
+slide = prs.slides.add_slide(prs.slide_layouts[6])   # Blank
+
+# --- geometry (BBox is splattable into add_*) ---
+bb = BBox.from_inches(1, 2, 8, 4)
+left, right = bb.split_h([1, 1], gap=Inches(0.2))
+inner = bb.inset(all=Inches(0.2))
+
+# --- n-up rows/grids: never hand-compute (avail - (n-1)*gap) / n ---
+for cell in bb.columns(3, gap=Pt(16)):     # equal columns; .rows(n) too
+    slide.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, *cell)
+
+# --- text (one call) ---
+slide.shapes.add_text(bb, text="Hello",
+                      size_pt=24, bold=True,
+                      color="#0B5CFF", align="center")
+
+# --- native equation from LaTeX (pip install "python-pptx2[math]") ---
+slide.shapes.add_equation(bb, latex=r"\frac{a}{b}", size_pt=28)
+para = slide.shapes.add_text(bb, text="Euler: ").text_frame.paragraphs[0]
+para.add_math(r"e^{i\pi}+1=0")
+
+# --- shape with chainable colour ---
+slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, *bb) \
+    .fill_hex("#FFFFFF").line_hex("#0D0D0D", weight_pt=1.25)
+
+# --- flat card: no theme drop-shadow, radius in points ---
+card = slide.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, *inner)
+card.shadow.clear()                        # kills the inherited effectRef too
+card.corner_radius = Pt(6)                 # not adjustments[0]
+
+# --- arrow with proper triangular head + auto edge routing ---
+start_shape = slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, *left)
+end_shape   = slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, *right)
+slide.shapes.add_arrow(start=start_shape, end=end_shape,
+                       head="triangle", color="#0B5CFF", weight_pt=1.5)
+
+# --- format-preserving text replacement (templated placeholders) ---
+title_shape.set_text_preserving_format("New title")
+
+# --- picture replacement (broken / sub-quality picture → native shapes) ---
+picture.replace_with(lambda slide, bbox: ..., padding=Inches(0.1))
+
+# --- diagram recipes ---
+horizontal_pipeline(slide, bb, steps=["Extract", "Classify", "Enrich"])
+hub_and_spoke(slide, bb, centre="Agent",
+              spokes=["Memory", "Tools", "Planning"])
+
+# --- table styling without dropping to raw fill/font loops ---
+table.format_cells(rows=0, fill="#1F2937", color="#FFFFFF", bold=True)
+table.format_cells(rows=slice(1, None), size_pt=11, align="right")
+
+# --- space-aware fit (returns the size it applied) ---
+size = tf.fit_text(font_family="Inter", max_size=24)
+
+# --- single-call cleanup before save ---
+slide.tidy()                               # lints + safe auto-fixes
+
+# --- tell the linter an overlap is deliberate (widest -> narrowest) ---
+slide.lint_group_overlaps(card, accent, label)   # one visual cluster
+badge.allow_overlap_with(card)                   # exactly this one pair
+card.layer, badge.layer_above = "card", "card"   # also asserts z-order
+
+# --- validate at save time (off by default) ---
+prs.lint_on_save = "raise"                 # or "warn"; raises before writing
+
+# --- whole-deck audit (markdown summary) ---
+print(audit(prs).markdown())
+
+# --- render thumbnails ---
+from pptx2.render import render_slides
+render_slides(prs, slides=[0, 1, 2], out_dir="thumbs",
+              name_template="slide-{:02d}.png")
+```
+
+That whole sheet fits on one screen — it's the working set.
+
+## When to use this skill
+
+- The user wants to **generate a deck** from Python or a JSON / dict spec
+- The user is concerned about **text overflow** or **layout correctness**
+  in generated decks (lead with `space-aware-authoring.md`)
+- The user wants to **add visual effects** (shadow, glow, soft edges,
+  blur, reflection, alpha) to shapes
+- The user wants **animations**, **transitions**, or **motion paths**
+- The user wants to **read or write a theme** (palette + fonts), or
+  apply one from a `.potx`
+- The user wants to **lint / auto-fix** geometry issues
+- The user wants to **import a slide** between decks or **apply a template**
+- The user wants a **design system** (tokens, recipes, Grid/Stack layout)
+- The user wants **chart palettes**, **quick layouts**, or per-series
+  gradient/pattern fills
+- The user wants **slide thumbnails** rendered to PNG
+- The user wants **3D** primitives (bevels / extrusion) or **SmartArt
+  text substitution**
+- The user wants **native SVG embedding** with PNG fallback
+
+## Install
+
+```bash
+pip install python-pptx2
+```
+
+The `cairosvg` dependency is optional — install only if you want
+`add_svg_picture(...)` to auto-rasterise the PNG fallback. `pyyaml` is
+optional too — install only if you want `DesignTokens.from_yaml`.
+
+## Reference snippets
+
+This skill ships a `references/` directory with focused recipe
+collections. Read just the file you need — they're self-contained.
+
+| File | What it covers |
+|---|---|
+| `references/space-aware-authoring.md` | **READ THIS FIRST.** Pre-flight measurement (`fit_text`, `TextFitter.best_fit_font_size`), `auto_size` flags, the linter, and a robust layout pattern. **Phase 2 + Phase 6 text-fit estimator.** |
+| `references/geometry-and-arrows.md` | `BBox` value object (`columns`/`rows`/`split_h`/`grid`), `add_text` / `add_arrow` / `fill_hex` / `line_hex` convenience, `set_text_preserving_format`, `Picture.replace_with`, `Slide.tidy()`, diagram recipes (`horizontal_pipeline`, `hub_and_spoke`, `cycle`, `decision_tree`, `comparison_columns`), `audit(prs)`. **v2.8.** |
+| `references/lint.md` | Detail on `slide.lint()`, issue types, `auto_fix`, and the `from_spec(..., lint="raise")` hook. **Phase 2.** |
+| `references/design.md` | `DesignTokens`, `shape.style` facade, `Grid` / `Stack` layout primitives (geometry-safe placement), slide recipes (`title_slide`, `bullet_slide`, `kpi_slide`, `quote_slide`, `image_hero_slide`), starter pack. **Phase 9.** |
+| `references/math.md` | Native PowerPoint equations from LaTeX (`add_equation`, `paragraph.add_math`). Requires `python-pptx2[math]`. **v2.13.** |
+| `references/basics.md` | The 1.0.2 surface: `Presentation`, slides, placeholders, shapes, textboxes, tables, pictures, charts. Quick-reference cheatsheet. |
+| `references/effects.md` | **The canonical fills-and-effects reference.** Shadow (including `shadow.clear()`), glow, soft edges, blur, reflection, alpha-tinted colors, gradient fills (linear / radial / rectangular / shape), line ends/caps/joins/compound. Other files link here rather than repeat it. **Phase 3 + Phase 6.** |
+| `references/animations.md` | `Entrance` / `Exit` / `Emphasis` presets, triggers, by-paragraph reveal, sequencing context manager, motion paths. **Phase 5.** |
+| `references/transitions.md` | Per-slide and deck-wide transitions including Morph and other `p14:` extensions. **Phase 4.** |
+| `references/compose.md` | `from_spec` (JSON authoring with built-in lint), `import_slide`, `apply_template`. **Phase 2 + Phase 7.** |
+| `references/theme.md` | Reading + writing the theme palette and fonts; `theme.apply(...)`; theme-aware color resolution via `pptx2.inherit.resolve_color`. **Phase 6 + Phase 7.** |
+| `references/picture-effects.md` | Picture transparency / brightness / contrast / recolor (grayscale / sepia / washout / duotone) and SVG embedding. **Phase 6.** |
+| `references/charts.md` | Chart palettes, quick layouts, per-series gradient/pattern fills, plus the inherited chart API. **Phase 10.** |
+| `references/render.md` | Slide thumbnails via LibreOffice. **Phase 10.** |
+| `references/three-d.md` | Bevels and extrusion via `shape.three_d`. **Phase 8.** |
+| `references/smart-art.md` | Text substitution inside an existing template's SmartArt. **Phase 8.** |
+| `references/tables.md` | The inherited table API, plus `cell.format(...)` / `table.format_cells(...)` styling, `Cell.borders`, and `fit_to_box`. |
+| `references/end-to-end-deck.md` | A complete worked example: tokens, recipes, animations, transitions, charts, **and a lint pass before save**. |
+
+## Top-level imports beyond `Presentation`
+
+These are stable package-root re-exports — prefer them over deeper
+import paths:
+
+```python
+from pptx2 import (
+    Presentation,
+    # Immutable rectangular region; splats into add_* APIs.
+    BBox,
+    # One-call deck audit (lint + picture + empty-slide + font checks).
+    audit, AuditReport,
+    # Figure adapters — Plotly / Matplotlib / SVG / HTML → slide picture.
+    # Third-party deps are imported lazily; missing deps surface a clear
+    # FigureBackendUnavailable with the right pip install command.
+    add_plotly_figure, add_matplotlib_figure,
+    add_svg_figure,    add_html_figure,
+    FigureBackendUnavailable,
+    MathBackendUnavailable,
+    # Shape-level building blocks (token-driven; return small
+    # dataclasses exposing constituent shapes for further tweaks).
+    add_kpi_card, add_progress_bar,
+    KpiCard,      ProgressBar,
+)
+```
+
+## House rules for code you write
+
+1. **Always `from pptx2 import Presentation`** — never invent another
+   import path.
+2. **Default to space-aware patterns** for any text the user controls
+   at runtime: `fit_text` *or* `auto_size = TEXT_TO_FIT_SHAPE`, plus a
+   `slide.lint()` pass before save.
+3. **Reads should not mutate.** All effect / color / line proxies in
+   python-pptx2 return `None` for unset properties; assign `None` to
+   clear.
+4. **Use EMU through helpers**: `Inches`, `Pt`, `Emu`, `Cm` from
+   `pptx2.util`. Never write raw EMU integers when a helper exists.
+5. **Use `BBox` / `Grid` / `Stack` for placement** when you have more
+   than two shapes on a slide — they compute geometry from the slide's
+   real dimensions (or a region you hand them), so you can't
+   accidentally walk off the right edge, and there's no column
+   arithmetic to get wrong.
+6. **Prefer recipes for whole-slide layouts** when the user wants a
+   "good enough" pitch deck; drop down to direct `add_shape` /
+   `add_textbox` only when the recipes don't fit.
+7. **Save once at the end** — build the deck in memory, then call
+   `prs.save(...)`. Don't open and re-save inside loops.
+8. **For released-version constraints**: pin `python-pptx2>=2.8.0`
+   when generating requirements files — that's the minimum that
+   ships the `BBox`, `add_text`, `add_arrow`, `diagrams`, and
+   `audit` surface used in this skill.
+
+## A space-aware mini-template
+
+The pattern you'll reach for most often:
+
+```python
+from pptx2 import Presentation
+from pptx2.enum.text import MSO_AUTO_SIZE
+from pptx2.util import Inches
+
+prs = Presentation()
+slide = prs.slides.add_slide(prs.slide_layouts[5])
+slide.shapes.title.text = "Q4 Review"
+
+# Body box that has to swallow runtime-supplied text
+box = slide.shapes.add_textbox(Inches(0.6), Inches(1.6),
+                                Inches(12), Inches(5))
+tf = box.text_frame
+tf.word_wrap = True
+tf.text = USER_SUPPLIED_BODY
+
+# Belt: pick a determined size now using Pillow font metrics
+tf.fit_text(font_family="Inter", max_size=24)
+
+# Braces: let PowerPoint shrink on the way down if a user later edits
+tf.auto_size = MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE
+
+# Catch anything that slipped through. auto_fix() mutates the slide
+# (nudges OffSlide shapes in, autofits overflowing frames, restacks
+# contradicted layer declarations) and refreshes report.issues itself.
+slide.lint().auto_fix()
+report = slide.lint()
+errors = [i for i in report.issues if i.severity.value == "error"]
+if errors:
+    raise RuntimeError("\n".join(str(e) for e in errors))
+
+prs.save("out.pptx")
+```
+
+## Recent additions worth knowing
+
+These changes ship after v2.5 and are easy to miss:
+
+- **`Chart.recolour(palette)`** is the recommended single entry
+  point — auto-dispatches per chart type (per-point on pie /
+  doughnut, per-series otherwise). `apply_palette` warns and
+  routes when called on a doughnut.
+- **`Chart.line_color`** and **`Chart.apply_dark_theme(text=, line=)`**
+  pin axis lines + gridlines for dark-deck styling.
+- **Horizontal bar charts (`BAR_*`)** now default to top-to-bottom
+  reading order (`reverse_order=True`). Override with
+  `chart.category_axis.reverse_order = False` for legacy ordering.
+  Column charts are unaffected.
+- **`anchor=` keyword on `add_picture` / `add_shape` / `add_textbox`**
+  collapses corner / centre placement to one call (see
+  `references/basics.md`).
+- **`add_table(..., style="clean")`** disables every inherited style
+  flag — use it whenever you'll set custom cell borders or fills.
+- **`add_kpi_card(slide, ...)` / `add_progress_bar(slide, ...)`** —
+  shape-level building blocks beneath the slide-level recipes
+  (see `references/design.md`).
+- **`shape.shadow.clear()`** is the way to guarantee *no* shadow.
+  Clearing the individual shadow properties (or the deprecated
+  `shadow.inherit = False`) leaves the shape's `<a:effectRef idx="2"/>`
+  in place — a soft drop shadow in most themes — so cards keep a
+  phantom shadow nobody asked for. `clear()` drops the explicit shadow
+  elements *and* re-points the effect reference, keeping glow / soft
+  edges / blur / reflection intact.
+- **`shape.corner_radius`** reads and writes a rounded rectangle's
+  radius as a real length (`card.corner_radius = Pt(6)`), instead of the
+  `adjustments[0]` fraction-of-the-shorter-side that has to be eyeballed
+  per shape size.
+- **`BBox.columns(n, gap=...)` / `BBox.rows(n, gap=...)`** replace the
+  `(available - (n - 1) * gap) / n` loop for card rows, stat grids, and
+  panels. `Grid.from_box(box, cols=..., rows=...)` puts a full grid over
+  a region rather than the whole slide.
+- **`cell.format(...)` / `table.format_cells(rows=..., cols=..., ...)`**
+  style table cells with the same keywords as `add_text` (`fill`,
+  `color`, `bold`, `size_pt`, `align`, `anchor`, `margin`) — no more
+  `cell.fill.solid(); cell.fill.fore_color.rgb = ...` loops.
+- **`fit_text` is explicit about fallback metrics.** It returns the size
+  it applied, and warns (`FontMetricsWarning`) when a *named* family
+  isn't installed and measurement silently drops to Pillow's default
+  font — naming one is what makes it audible, so omitting `font_family`
+  stays quiet while `font_family="Calibri"` does not. `strict=True`
+  raises instead; `pptx2.text.fonts.font_is_installed("Inter")`
+  checks up front.
+- **Float coordinates from arithmetic are coerced** at constructor
+  entry and at `shape.left/top/width/height` setters, so
+  `(Inches(N) - gutter) / 2` style expressions can be passed straight
+  through. Pre-2.6.1 these produced float-valued `<a:off>` / `<a:ext>`
+  attributes that PowerPoint rejected with the "Repair?" dialog.
+
+## Anti-patterns to avoid
+
+LLM-generated python-pptx2 code falls into the same handful of traps.
+Flagging them up front saves the trial-and-error round.
+
+- **Don't** access `tf.paragraphs` twice and compare wrapper objects
+  with `is`. The property returns *fresh* `_Paragraph` objects every
+  call, so `p is not para` is always true — your filter will remove
+  the wrong paragraph. Use `set_text_preserving_format(new_text)` for
+  the common "replace text, keep formatting" case.
+- **Don't** assume `add_connector(MSO_CONNECTOR.STRAIGHT, ...)` puts
+  an arrowhead on the line. It produces a bare line. Use
+  `slide.shapes.add_arrow(start, end, head="triangle")` — it sets the
+  arrowhead, inset, edge routing, and colour in one call.
+- **Don't** size a diagram to a broken picture's bbox when there's an
+  enclosing card. The card area is what you want. Use
+  `picture.enclosing_container()` to find the right box, then
+  `picture.replace_with(builder)`.
+- **Don't** delete a picture and then assume sibling shape indexes
+  are stable. Process in reverse index order, or capture the shapes
+  to mutate *before* iterating.
+- **Don't** import `RGBColor` / `PP_ALIGN` / `MSO_VERTICAL_ANCHOR`
+  for every styling call. Use the hex-string and short-name kwargs:
+  `slide.shapes.add_text(bb, text="…", color="#0B5CFF", align="center",
+  anchor="middle")`. Hex strings, tuples, and `RGBColor` all work
+  everywhere a colour is accepted.
+- **Don't** write raw EMU integers. `BBox.from_inches(1, 2, 8, 4)`
+  for regions, `Inches(1)` / `Pt(12)` for individual lengths. Float
+  arithmetic on EMU is fine — coordinates are coerced at the setter.
+- **Don't** lint + auto_fix + lint again to clear safe issues. Use
+  `slide.tidy()` — it's the one-call wrapper.
+- **Don't** hand-roll `col_w = (avail - (n - 1) * gap) / n` and a running
+  cursor for card rows or stat grids. `bb.columns(n, gap=Pt(16))` (and
+  `bb.rows(...)`, `bb.grid(cols, rows)`, `Grid.from_box(bb, cols=...)`)
+  return exact, drift-free boxes.
+- **Don't** try to remove a shadow by assigning `None` to
+  `shadow.blur_radius` / `distance`, or by `shadow.inherit = False`.
+  Neither touches the theme effect style, so the shadow is still
+  rendered. Use `shape.shadow.clear()` — the only call that does.
+- **Don't** set a corner radius by guessing `adjustments[0]` (it's a
+  fraction of the shorter side, so the same value means a different
+  radius on every differently-sized card). Use
+  `shape.corner_radius = Pt(6)`.
+- **Don't** invent OMML / `a14:m` XML, and don't rasterise ordinary
+  formulas with matplotlib just to get them on a slide. Use
+  `slide.shapes.add_equation(bb, latex=r"\frac{a}{b}")` or
+  `paragraph.add_math(...)` (`pip install "python-pptx2[math]"`).
+- **Don't** style table cells with `cell.fill.solid()` +
+  `cell.fill.fore_color.rgb` + per-run font loops. Use
+  `cell.format(...)` / `table.format_cells(...)` — and note that a
+  cell's anchor and insets belong on the cell, not on its text frame.
+- **Don't** trust `fit_text` when the font isn't installed. The
+  measurement falls back to Pillow's default metrics and the result is
+  an estimate — bundle the `.ttf` and pass `font_file=`, or pass
+  `strict=True` so the build fails instead of shipping a guess.
+
+## Common pitfalls
+
+- **Calling `shape.shadow.inherit`** raises `DeprecationWarning`. Read
+  individual properties (`blur_radius`, `distance`, `direction`,
+  `color`) and check for `None` instead; to *remove* a shadow call
+  `shape.shadow.clear()`.
+- **`fit_text` degrades to a best guess for uninstalled fonts.** Font
+  metrics come from the machine running the build, so a brand face that
+  isn't installed (the usual case in a container or CI) is measured with
+  Pillow's default font. Check with
+  `pptx2.text.fonts.font_is_installed(...)`, pass `font_file=` with
+  the real `.ttf`, or use `strict=True`. `slide.lint()` is unaffected —
+  its overflow check is font-agnostic — which is why the lint pass is
+  worth keeping even when the metrics are exact.
+- **Bare-int sizes in `DesignTokens` typography** are interpreted as
+  **EMU**, not points. Use floats (`44.0`) or `Pt(44)` to mean
+  44-point font.
+- **Recipes use the Blank layout**, so `slide.shapes.title` is `None`.
+  Address shapes by index (`slide.shapes[0]`, `slide.shapes[1]`, …).
+- **`add_svg_picture` without `cairosvg` and without a `png_fallback`**
+  raises `CairoSvgUnavailable`. Either install cairosvg or supply a
+  pre-rasterised PNG.
+- **`auto_fix()` repairs geometry, not judgment.** It clamps `OffSlide`,
+  flips `TextOverflow` frames to `TEXT_TO_FIT_SHAPE`, snaps
+  `OffGridDrift`, and restacks `LayerOrderViolation`. It will never
+  touch `ShapeCollision`, `LowContrast`, `MinFontSize` or
+  `ZOrderAnomaly` — those need a designer. Prefer `tf.fit_text(...)`
+  *before* save over relying on the overflow fix.
+- **Slide thumbnails require `soffice` on PATH** (LibreOffice).
+  Otherwise you get `ThumbnailRendererUnavailable`.
+- **`MSO_PATTERN_TYPE.ERCENT_40`** is the upstream typo and emits a
+  `DeprecationWarning`. Use `PERCENT_40`.
+- **Calling `chart.apply_palette` on a pie / doughnut** emits a
+  `UserWarning` and routes through `color_by_category`. Use
+  `chart.recolour(palette)` directly to silence it.
+
+## Where to look in the project
+
+If the user has the `python-pptx2` repo checked out alongside this
+skill, these paths are useful for source-of-truth lookup:
+
+- `src/pptx2/lint.py` — `SlideLintReport`, `TextOverflow`, `OffSlide`,
+  `ShapeCollision`, `LayerOrderViolation`, `LintSeverity`.
+- `src/pptx2/shapes/base.py` — `lint_group`, `lint_skip`,
+  `allow_overlap_with`, `layer` / `layer_above` (overlap intent).
+- `src/pptx2/text/text.py`, `src/pptx2/text/layout.py` — `fit_text`,
+  `TextFitter`, `_best_fit_font_size`.
+- `src/pptx2/animation.py` — `Entrance`, `Exit`, `Emphasis`,
+  `MotionPath`, `SlideAnimations`.
+- `src/pptx2/compose/` — `from_spec`, plus the `import_slide` /
+  `apply_template` re-exports.
+- `src/pptx2/theme.py`, `src/pptx2/inherit.py` — theme reader/writer and
+  `resolve_color`.
+- `src/pptx2/dml/effect.py`, `src/pptx2/dml/picture.py`,
+  `src/pptx2/dml/line.py` — Phase 3/6 visual effects, picture filters,
+  line-end formatting.
+- `src/pptx2/design/` — `tokens`, `style`, `layout`, `recipes`.
+- `src/pptx2/chart/palettes.py`, `src/pptx2/chart/quick_layouts.py`.
+- `src/pptx2/render.py` — slide-thumbnail renderer.
+- `src/pptx2/smart_art.py`, `src/pptx2/_svg.py`.
+- `examples/starter_pack/` — three example token sets and a build script.
+
+The user-facing Sphinx documentation under `docs/user/` mirrors the
+sections in this skill and is a good source of additional prose.

pptx2/skill/__init__.py

@@ -0,0 +1,78 @@
+"""Bundled Claude Code skill for python-pptx2.
+
+Ships the ``SKILL.md`` and reference markdown that drive the Claude
+Code (and Claude Agent SDK) ``python-pptx2`` skill, so that pip-installing
+python-pptx2 is enough to make the skill available wherever the library
+runs.
+
+Typical usage from a shell::
+
+    # Install into the current user's Claude skills directory
+    python -m pptx2.skill install
+
+    # Or just print where the skill files live inside the package
+    python -m pptx2.skill path
+
+Programmatic usage::
+
+    from pptx2.skill import skill_root, install_skill
+
+    src = skill_root()                  # pathlib.Path inside the package
+    dest = install_skill()              # default: ~/.claude/skills/python-pptx2
+    dest = install_skill(target="/some/other/dir/python-pptx2")
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Optional
+
+__all__ = ["skill_root", "install_skill", "DEFAULT_INSTALL_DIR"]
+
+
+#: Default destination directory for ``install_skill``.
+#:
+#: Matches the convention that Claude Code uses for user-level skills.
+#: Override by passing ``target=`` to :func:`install_skill`.
+DEFAULT_INSTALL_DIR = Path.home() / ".claude" / "skills" / "python-pptx2"
+
+
+def skill_root() -> Path:
+    """Return the directory inside the installed package that holds the skill.
+
+    Contains ``SKILL.md`` and a ``references/`` subdirectory.  This is
+    a regular filesystem path even when the package is installed inside
+    a wheel, because setuptools copies ``package_data`` files onto disk.
+    """
+    return Path(__file__).resolve().parent
+
+
+def install_skill(
+    target: Optional[Path] = None, *, overwrite: bool = True
+) -> Path:
+    """Copy the bundled skill to *target* (default :data:`DEFAULT_INSTALL_DIR`).
+
+    Returns the destination directory.  When *overwrite* is ``True``
+    (the default), an existing skill at *target* is replaced; pass
+    ``overwrite=False`` to raise :class:`FileExistsError` instead.
+    """
+    src = skill_root()
+    dest = Path(target) if target is not None else DEFAULT_INSTALL_DIR
+
+    if dest.exists():
+        if not overwrite:
+            raise FileExistsError(
+                f"refusing to overwrite existing skill at {dest!s}; "
+                "pass overwrite=True or remove it first"
+            )
+        shutil.rmtree(dest)
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    # Copy SKILL.md and references/ but not __init__.py / __main__.py.
+    dest.mkdir()
+    shutil.copy2(src / "SKILL.md", dest / "SKILL.md")
+    refs_src = src / "references"
+    if refs_src.is_dir():
+        shutil.copytree(refs_src, dest / "references")
+    return dest

pptx2/skill/__main__.py

@@ -0,0 +1,64 @@
+"""Command-line entry point for the bundled Claude skill.
+
+Usage::
+
+    python -m pptx2.skill install [TARGET]   # copy skill into target dir
+    python -m pptx2.skill path               # print on-disk skill source
+    python -m pptx2.skill                    # same as `path`
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from pptx2.skill import DEFAULT_INSTALL_DIR, install_skill, skill_root
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m pptx2.skill",
+        description=(
+            "Manage the bundled python-pptx2 Claude skill.  "
+            "Ships SKILL.md and reference docs to your Claude skills directory."
+        ),
+    )
+    sub = parser.add_subparsers(dest="cmd")
+
+    install = sub.add_parser(
+        "install", help="copy the bundled skill into a Claude skills directory"
+    )
+    install.add_argument(
+        "target",
+        nargs="?",
+        type=Path,
+        default=None,
+        help=f"destination directory (default: {DEFAULT_INSTALL_DIR})",
+    )
+    install.add_argument(
+        "--no-overwrite",
+        action="store_true",
+        help="error out if the destination already exists",
+    )
+
+    sub.add_parser("path", help="print the package-internal skill directory")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "install":
+        try:
+            dest = install_skill(args.target, overwrite=not args.no_overwrite)
+        except FileExistsError as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+        print(f"installed python-pptx2 skill -> {dest}")
+        return 0
+
+    # default + `path`
+    print(skill_root())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())