python-pptx2 2.13.0__py3-none-any.whl

pptx2/skill/references/lint.md

@@ -0,0 +1,275 @@
+# Layout linter (Phase 2)
+
+Programmatic decks tend to ship the same handful of bugs over and
+over: text spilling out of its container, shapes off-slide, layered
+elements that aren't intended overlaps. The linter is built for
+exactly that use case — it's especially useful when feeding decks
+generated from LLM output or arbitrary user input.
+
+## Run on a slide
+
+```python
+report = slide.lint()
+report.issues          # list[LintIssue]
+report.has_errors      # bool
+print(report.summary())
+```
+
+For a whole deck, iterate the slides yourself:
+
+```python
+all_issues = []
+for slide in prs.slides:
+    all_issues.extend(slide.lint().issues)
+```
+
+`from_spec` (see `compose.md`) accepts a deck-level
+``"lint": "warn" | "raise"`` field that walks every slide for you.
+
+## Issue types
+
+```python
+from pptx2.lint import TextOverflow, OffSlide, ShapeCollision
+
+for issue in report.issues:
+    if isinstance(issue, TextOverflow):
+        print("overflow", issue.shapes[0].name, "ratio", issue.ratio)
+    elif isinstance(issue, OffSlide):
+        print("off-slide", issue.shapes[0].name, "side", issue.side)
+    elif isinstance(issue, ShapeCollision):
+        a, b = issue.shapes
+        print("collision", a.name, b.name,
+              "intersection_pct", issue.intersection_pct)
+```
+
+`LayerOrderViolation` carries the declared `layer` name, and its
+`shapes` tuple is `(declaring_shape, layer_shape)`.
+
+Every issue carries a `severity` (`LintSeverity.ERROR` / `WARNING` /
+`INFO`), a `code` string, a `message`, and a `shapes` tuple of the
+shapes it implicates.
+
+`TextOverflow` uses Pillow font metrics and respects margins, vertical
+anchor, line spacing, and `auto_size`.
+
+## Auto-fix
+
+```python
+fixes = report.auto_fix()                  # mutates; returns list[str]
+preview = report.auto_fix(dry_run=True)    # no mutation; returns list[str]
+```
+
+What's currently fixable:
+
+- **`OffSlide`** → translates the shape so it sits inside the slide
+  bounds (shrinking it first if it is larger than the slide). Returns a
+  one-line description of each nudge.
+- **`TextOverflow`** → flips the frame to
+  `MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE` so PowerPoint shrinks the runs at
+  render time. Non-destructive: the text is preserved verbatim.
+- **`OffGridDrift`** → snaps the drifted edge onto the dominant grid
+  line.
+- **`LayerOrderViolation`** → restacks the shape that declared
+  `layer_above` so the drawing order matches what you declared.
+  Geometry is untouched.
+
+Reported only, never auto-fixed:
+
+- **`ShapeCollision`** → auto-nudging would almost always break the
+  design. Declare the overlap instead — see below.
+- **`LowContrast`**, **`MinFontSize`**, **`ZOrderAnomaly`**,
+  **`MasterPlaceholderCollision`** → need designer judgment.
+
+`slide.tidy()` is the one-call wrapper: it lints, then applies the safe
+subset (`fix_offslide`, `fix_overflow`, `fix_layer_order` on by default;
+`fix_grid_drift` off).
+
+## Declaring an overlap is intentional
+
+`ShapeCollision` is the noisiest rule, because deliberate layering —
+a badge on a card, an accent bar on a panel — looks identical to a
+copy-paste bug from a bounding box alone. Tell the linter what you
+meant and it stops guessing. Three ways, narrowest last:
+
+```python
+# 1. Group tag — n-ary and symmetric. Everything sharing a non-empty
+#    tag may overlap everything else in the tag.
+card.lint_group = "kpi-1"
+accent.lint_group = "kpi-1"
+slide.lint_group("kpi-1", card, accent, label)     # batch form
+slide.lint_group_overlaps(card, accent, label)     # auto-names the group
+
+# 2. Pairwise allowance — licenses exactly one pair, nothing else.
+badge.allow_overlap_with(card)
+badge.disallow_overlap_with(card)                  # revoke
+badge.overlap_allowances                           # frozenset[int] of shape ids
+
+# 3. Layer hints — the only form that also asserts z-order.
+card.layer = "card"
+badge.layer_above = "card"
+```
+
+Use a **group** when several shapes form one visual cluster; a
+**pairwise allowance** when only one specific overlap is meant to be
+legal and you want the rest still policed; **layer hints** when the
+stacking order itself matters.
+
+An allowance may only name a shape on the **same slide**, and passing
+one from another slide raises `ValueError`. Use `shape.delete()` rather
+than removing the element by hand — it purges allowances naming the
+deleted shape, which matters because ids get recycled and a stale one
+would later match an unrelated shape. Allowances are keyed on
+`cNvPr/@id`, which is unique per slide but repeats across a deck — so a
+borrowed id would either read as a bogus self-reference or silently
+match an unrelated shape here and suppress a collision that was real.
+
+Layer hints are the only one that can *fail*. Declaring
+`layer_above = "card"` asserts this shape is painted on top of every
+overlapping shape whose `layer` is `"card"`. If the shape tree says
+otherwise — the shape claiming to be on top comes earlier in `spTree`
+and is drawn underneath — you get a `LayerOrderViolation` (severity
+ERROR), because the declaration records what you meant and the drawing
+order is what failed to deliver it:
+
+```python
+report = slide.lint()
+report.auto_fix()          # restacks it for you; geometry untouched
+```
+
+A shape name with a dotted prefix is grouped implicitly, so naming
+shapes `"card.bg"` / `"card.title"` groups them under `"card"` with no
+extra calls. Set `shape.lint_group = ""` to opt a dotted name out.
+
+All of it lives in the shape's `cNvPr/extLst`, the OOXML-sanctioned
+extension point, so it survives save/open and PowerPoint leaves it
+alone. Related but different: `shape.lint_skip = {"MinFontSize"}`
+silences a rule on a shape rather than declaring intent.
+
+## Machine-readable output (for agents / CI)
+
+`summary()` is for humans; `to_dict()` / `to_json()` are for code. Use
+them to feed lint results back into an LLM auto-fix loop or a CI gate
+instead of regex-parsing the summary string.
+
+```python
+report = slide.lint()
+report.to_dict()    # {"has_errors", "issue_count", "issues": [...]}
+report.to_json()    # same, as a JSON string (indent=2 default)
+```
+
+Each issue is self-describing — it carries `code`, `severity`,
+`message`, the names of the `shapes` involved, and every
+detector-specific field (`OffSlide.side`, `TextOverflow.ratio`, the
+`ShapeCollision` scoring, …):
+
+```json
+{"code": "OffSlide", "severity": "error",
+ "message": "Shape 'Rectangle 1' extends beyond the right edge of the slide.",
+ "shapes": ["Rectangle 1"], "side": "right"}
+```
+
+The whole-deck `audit()` report has the same pair:
+
+```python
+from pptx2 import audit
+
+data = audit(prs).to_dict()   # adds a "slide" index to every lint issue
+if data["has_errors"]:
+    ...                        # hand `data` straight to the model to fix
+```
+
+## Save-time hooks (via `from_spec`)
+
+If you build the deck through `pptx2.compose.from_spec`, the spec dict
+accepts a top-level ``"lint"`` field:
+
+```python
+from pptx2.compose import from_spec
+
+prs = from_spec({
+    "slides": [...],
+    "lint": "raise",          # also "warn" or "off" (default)
+})
+```
+
+`"warn"` logs every issue through stdlib `logging`; `"raise"` raises
+`pptx2.exc.LintError` if any error-severity issue is found.
+
+## Save-time hooks (any presentation)
+
+Every `Presentation` has a `lint_on_save` switch, whatever built it:
+
+```python
+prs = pptx2.Presentation("deck.pptx")
+prs.lint_on_save = "off"      # default — no checks, no cost
+prs.lint_on_save = "warn"     # log error-severity issues, still write the file
+prs.lint_on_save = "raise"    # raise LintError instead of writing the file
+
+prs.save("out.pptx")
+```
+
+Only **error**-severity issues count; warnings and info never trigger it.
+The lint pass runs *before* anything is written, so `"raise"` never leaves a
+bad file on disk. `"warn"` logs on the `pptx2.presentation` logger. The
+setting lives on the in-memory object only — re-open the saved file and it is
+back to `"off"`.
+
+## Recommended pattern for generators
+
+```python
+from pptx2.exc import LintError
+
+prs = build_deck_from_user_input(...)
+
+# 1. Auto-fix what we can, slide by slide
+for slide in prs.slides:
+    report = slide.lint()
+    report.auto_fix()
+
+# 2. Re-run and bail on any remaining errors
+remaining = []
+for slide in prs.slides:
+    remaining.extend(i for i in slide.lint().issues
+                     if getattr(i, "severity", None) == "error")
+if remaining:
+    raise LintError("; ".join(str(i) for i in remaining))
+
+prs.save("out.pptx")
+```
+
+## CI loop: SARIF export + baseline diff
+
+`summary()` is for humans; SARIF and diff are for CI.
+
+```python
+report = slide.lint()
+report.to_sarif(slide_index=0)        # SARIF v2.1.0 dict (GitHub code-scanning)
+report.to_sarif_json()                # JSON string
+
+from pptx2.lint import lint_report_to_sarif
+sarif = lint_report_to_sarif([s.lint() for s in prs.slides])   # whole deck
+
+report.fingerprints()                 # list[str] -- the stable ids diff() uses
+new_issues = current.diff(baseline)   # only issues NOT in baseline
+both = current.diff_detail(baseline)  # {"added": [...], "fixed": [...]}
+```
+
+Severities map ERROR→error, WARNING→warning, INFO→note. A
+moved-but-still-broken shape keeps its fingerprint, so `diff()` won't
+flag it as new.
+
+## Accessibility
+
+```python
+picture.alt_text = "Bar chart of Q3 revenue by region."   # -> <p:cNvPr descr=...>
+picture.title_text = "Q3 revenue"                          # -> <p:cNvPr title=...>
+
+from pptx2 import accessibility
+report = accessibility.audit_accessibility(prs)            # read-only
+if report.has_errors:                  # picture with no alt text = error
+    print(report.markdown())
+report.to_dict()                       # JSON-serializable for a CI gate / LLM loop
+```
+
+Flags: `MissingAltText` (pictures = error), `LowContrast` (below WCAG AA
+4.5:1), `NoSlideTitle` (no title landmark for navigation).

pptx2/skill/references/math.md

@@ -0,0 +1,86 @@
+# Native equations from LaTeX
+
+PowerPoint stores editable equations as Office Math (OMML) inside an
+`a14:m` marker. python-pptx2 does **not** compile LaTeX itself. It calls
+two libraries and wraps the result:
+
+1. [`latex2mathml`](https://pypi.org/project/latex2mathml/) — LaTeX → MathML
+2. [`mathml2omml`](https://pypi.org/project/mathml2omml/) — MathML → OMML
+
+Install them with:
+
+```bash
+pip install "python-pptx2[math]"
+```
+
+Missing converters raise `MathBackendUnavailable` with that install line.
+
+## Display equation — `slide.shapes.add_equation`
+
+Same calling convention as `add_text`: a `BBox` or `(left, top, width, height)`.
+
+```python
+from pptx2 import Presentation, BBox
+from pptx2.util import Inches
+
+prs = Presentation()
+slide = prs.slides.add_slide(prs.slide_layouts[6])
+
+slide.shapes.add_equation(
+    BBox.from_inches(1, 2, 8, 1.5),
+    latex=r"\frac{-b \pm \sqrt{b^2-4ac}}{2a}",
+    size_pt=28,
+    color="#111827",
+    align="center",
+)
+
+slide.shapes.add_equation(
+    Inches(1), Inches(4), Inches(8), Inches(1),
+    latex=r"E = mc^2",
+)
+```
+
+The shape is a text box. The equation is editable in PowerPoint's
+equation editor. `display=True` (the default) wraps OMML in
+`m:oMathPara`.
+
+Keyword args: `latex` (required), `display`, `font`, `size_pt`,
+`color`, `align`, `anchor`, `margin_pt`.
+
+## Inline equation — `paragraph.add_math`
+
+Sits between ordinary runs in the same paragraph:
+
+```python
+box = slide.shapes.add_textbox(Inches(1), Inches(1), Inches(8), Inches(1))
+p = box.text_frame.paragraphs[0]
+p.add_run().text = "Euler's identity "
+p.add_math(r"e^{i\pi} + 1 = 0")
+p.add_run().text = " holds for all real π."
+```
+
+`display=False` (the default here) emits inline `m:oMath`. Pass
+`size_pt` / `color` / `font` to style the math runs.
+
+`paragraph.clear()` and assigning `paragraph.text` remove the equation
+along with the runs.
+
+## Bare converter
+
+```python
+from pptx2.math import latex_to_omml
+
+omml = latex_to_omml(r"\sum_{i=1}^{n} i")
+# '<m:oMath>…</m:oMath>'
+```
+
+Wrappers (`$…$`, `$$…$$`, `\(…\)`, `\[…\]`, `equation` / `align`
+environments) are stripped before conversion.
+
+## What this is not
+
+- Not a TeX engine. Environments like `tikzpicture` will not render.
+- Not Microsoft's `MML2OMML.XSL` (that stylesheet cannot be
+  redistributed). The MathML → OMML step is the `mathml2omml` package.
+- Not an image. If you need a PNG of a formula, use
+  `add_matplotlib_figure` with mathtext instead.

pptx2/skill/references/picture-effects.md

@@ -0,0 +1,129 @@
+# Picture effects + native SVG (Phase 6)
+
+Pictures gain a dedicated `effects` accessor that wraps the OOXML
+`<a:blip>` filters, plus native SVG support with PNG fallback.
+
+## Picture filters
+
+```python
+from pptx2 import Presentation
+from pptx2.util import Inches
+from pptx2.dml.color import RGBColor
+
+prs = Presentation()
+slide = prs.slides.add_slide(prs.slide_layouts[6])  # blank
+
+pic = slide.shapes.add_picture(
+    "hero.jpg", Inches(0), Inches(0),
+    width=prs.slide_width, height=prs.slide_height,
+)
+
+# Continuous adjustments — all in [-1.0, 1.0] (or [0.0, 1.0] for transparency)
+pic.effects.transparency = 0.3        # 30% see-through
+pic.effects.brightness   = 0.10
+pic.effects.contrast     = 0.05
+```
+
+## Recolor presets
+
+`recolor` is a **property, not a method** — assign to it. There are
+exactly four modes; anything else raises `ValueError`, and the existing
+effect is left intact because the value is validated before it mutates.
+
+```python
+pic.effects.recolor = "grayscale"
+pic.effects.recolor = "sepia"         # a preset duotone under the hood
+pic.effects.recolor = "washout"       # PowerPoint's "Washout"
+pic.effects.recolor = "duotone"       # neutral grey duotone; see below
+                                      # to pick your own two colours
+
+pic.effects.recolor                   # read it back: the mode, or None
+```
+
+There is no `"black_and_white"` mode. `"washout"` is the closest
+equivalent.
+
+## Duotone
+
+```python
+pic.effects.set_duotone(
+    RGBColor(0x12, 0x1E, 0x4D),       # shadow color
+    "#A8C0FF",                         # highlight color (hex with or without '#')
+)
+
+# Plain RGB tuples are also accepted
+pic.effects.set_duotone((18, 30, 77), (168, 192, 255))
+```
+
+To clear, assign `None` — there is no `clear_recolor()` method:
+
+```python
+pic.effects.recolor = None            # drops any duotone / grayscale / etc.
+```
+
+## Native SVG with PNG fallback
+
+`add_svg_picture` embeds both an SVG and a PNG fallback inside the
+same `<a:blip>` so PowerPoint and earlier viewers each render the
+right one.
+
+```python
+# Auto-rasterise via the optional `cairosvg` dependency
+slide.shapes.add_svg_picture("logo.svg", Inches(0.5), Inches(0.5))
+
+# Bring your own fallback PNG
+slide.shapes.add_svg_picture(
+    "logo.svg",
+    Inches(0.5), Inches(0.5),
+    width=Inches(1.5), height=Inches(1.5),
+    png_fallback="logo.png",
+)
+```
+
+If `cairosvg` isn't installed and you don't pass `png_fallback`, the
+call raises `pptx2._svg.CairoSvgUnavailable` with a clear install hint.
+
+The `image/svg+xml` content type is registered with the package so
+SVG parts authored elsewhere round-trip through PowerPoint untouched.
+
+## End-to-end: tinted photo with overlay text
+
+```python
+from pptx2 import Presentation
+from pptx2.util import Inches, Pt
+from pptx2.dml.color import RGBColor
+from pptx2.enum.shapes import MSO_SHAPE
+
+prs = Presentation()
+slide = prs.slides.add_slide(prs.slide_layouts[6])
+
+# Full-bleed hero image, duotoned to brand colors
+pic = slide.shapes.add_picture(
+    "hero.jpg", 0, 0,
+    width=prs.slide_width, height=prs.slide_height,
+)
+pic.effects.set_duotone(RGBColor(0x12, 0x1E, 0x4D), "#A8C0FF")
+
+# Bottom band with overlay text
+band = slide.shapes.add_shape(
+    MSO_SHAPE.RECTANGLE,
+    0, prs.slide_height - Inches(1.5),
+    prs.slide_width, Inches(1.5),
+)
+band.fill.solid()
+band.fill.fore_color.rgb   = RGBColor(0x12, 0x1E, 0x4D)
+band.fill.fore_color.alpha = 0.55
+band.line.fill.background()
+
+box = slide.shapes.add_textbox(
+    Inches(0.6), prs.slide_height - Inches(1.2),
+    prs.slide_width - Inches(1.2), Inches(0.9),
+)
+p = box.text_frame.paragraphs[0]
+p.text = "Q4 2026"
+p.font.size = Pt(40)
+p.font.bold = True
+p.font.color.rgb = RGBColor(0xFF, 0xFF, 0xFF)
+
+prs.save("hero.pptx")
+```

pptx2/skill/references/render.md

@@ -0,0 +1,151 @@
+# Slide thumbnails (Phase 10)
+
+`pptx2.render` shells out to LibreOffice to rasterise slides as PNGs.
+This is for review tooling, dashboards, and CI artifacts — it does not
+require Microsoft PowerPoint or an Office license, but `soffice` must
+be on `$PATH` (or you can point at a custom binary).
+
+## Convenience methods
+
+```python
+# All slides → ./thumbs/<n>.png
+paths = prs.render_thumbnails(out_dir="thumbs")
+
+# Single slide as bytes
+png = slide.render_thumbnail(return_bytes=True)
+
+# Single slide written to a specific path
+slide.render_thumbnail(out_path="cover.png")
+```
+
+## Module-level entry points
+
+```python
+from pptx2.render import (
+    render_slide_thumbnails,
+    render_slide_thumbnail,
+)
+
+paths = render_slide_thumbnails(
+    prs,
+    out_dir="thumbs",
+    slide_indexes=[0, 3, 7],                              # only these slides
+    soffice_bin="/opt/libreoffice/program/soffice",
+    timeout=60,                                            # seconds
+)
+
+png = render_slide_thumbnail(slide, return_bytes=True)
+```
+
+The output resolution is whatever LibreOffice's headless PNG
+converter chooses — there's no `width=` knob. If you need a specific
+size, post-process with Pillow (``Image.open(...).resize(...)``).
+
+## Pointing at a custom binary
+
+Three ways to choose `soffice`, in priority order:
+
+1. The `soffice_bin=` keyword argument
+2. The `POWER_PPTX_SOFFICE` environment variable
+3. The first `soffice` (or `libreoffice`) on `$PATH`
+
+```python
+import os
+os.environ["POWER_PPTX_SOFFICE"] = "/opt/libreoffice/program/soffice"
+prs.render_thumbnails(out_dir="thumbs")
+```
+
+## Known limitations of the LibreOffice thumbnail path
+
+The `soffice` + `pdftoppm` pipeline that backs `render_thumbnails`
+renders most decks faithfully, but a few cross-renderer quirks are
+worth knowing about — these show up in the thumbnail even when the
+generated `.pptx` opens correctly in PowerPoint:
+
+* **Emoji glyphs render as tofu** on systems without an emoji font
+  installed (most Linux runtimes lack one by default). PowerPoint
+  uses Segoe UI Emoji as a fallback; LibreOffice headless typically
+  does not. For decks meant to be thumbnail-reviewed on the same
+  machine, prefer Unicode glyphs from the shipped DejaVu families
+  (`•`, `→`, `★`, `‹›`, `■`, etc.) over emoji codepoints.
+* **Un-aligned text in fresh textboxes** renders centered instead of
+  left-aligned. A textbox created via `slide.shapes.add_textbox(...)`
+  has no `a:pPr/@algn` attribute; PowerPoint treats that as the
+  OOXML default (left), LibreOffice as centered. Set
+  `paragraph.alignment = PP_ALIGN.LEFT` explicitly to make
+  thumbnails match how PowerPoint will render the slide.
+* **`wrap="none" + spAutoFit` (the textbox default) re-centers under
+  LibreOffice.** A fresh textbox has `<a:bodyPr wrap="none">
+  <a:spAutoFit/></a:bodyPr>`. PowerPoint shrinks the box around the
+  declared anchor; LibreOffice re-centers the shrunken box inside
+  its original width, so a kicker line declared at
+  `left=Inches(1.1), width=Inches(11)` renders near the middle of
+  the slide rather than the left edge. Setting `tf.word_wrap = True`
+  suppresses `spAutoFit` and keeps the declared geometry intact —
+  fold it into every textbox in a recipe-style helper.
+
+## Errors
+
+```python
+from pptx2.render import (
+    ThumbnailRendererUnavailable,
+    ThumbnailRendererError,
+)
+
+try:
+    paths = prs.render_thumbnails(out_dir="thumbs")
+except ThumbnailRendererUnavailable as e:
+    # soffice not on PATH — message includes an install hint
+    print(e)
+except ThumbnailRendererError as e:
+    # soffice ran but produced no PNG / exited non-zero / timed out
+    print(e)
+```
+
+## Patterns
+
+### Generate review images for an HTML preview
+
+```python
+import base64
+
+prs.save("deck.pptx")
+images = []
+for i in range(len(prs.slides)):
+    png = prs.slides[i].render_thumbnail(return_bytes=True)
+    images.append(base64.b64encode(png).decode("ascii"))
+
+html = "\n".join(
+    f'<img src="data:image/png;base64,{b64}" width="640">'
+    for b64 in images
+)
+```
+
+### CI artefacts
+
+```python
+# In tests/conftest.py or similar
+from pathlib import Path
+
+def attach_deck_thumbs(prs, out: Path):
+    out.mkdir(exist_ok=True)
+    return prs.render_thumbnails(out_dir=out)
+```
+
+### Skip on dev machines without LibreOffice
+
+```python
+import shutil
+import pytest
+
+requires_soffice = pytest.mark.skipif(
+    shutil.which("soffice") is None and shutil.which("libreoffice") is None,
+    reason="LibreOffice not installed",
+)
+
+@requires_soffice
+def test_renders_thumbnails(tmp_path):
+    prs = build_demo_deck()
+    paths = prs.render_thumbnails(out_dir=tmp_path)
+    assert len(paths) == len(prs.slides)
+```