python-pptx2 2.13.0__py3-none-any.whl

pptx2/skill/references/charts.md

@@ -0,0 +1,254 @@
+# Charts: palettes, quick layouts, per-series fills (Phase 10)
+
+The chart helpers below stack on top of the existing chart API; nothing
+here replaces `chart_style` or the underlying series formatting — they
+just make common operations one line each.
+
+## A baseline chart
+
+```python
+from pptx2 import Presentation
+from pptx2.chart.data import CategoryChartData
+from pptx2.enum.chart import XL_CHART_TYPE
+from pptx2.util import Inches
+
+prs = Presentation()
+slide = prs.slides.add_slide(prs.slide_layouts[5])
+slide.shapes.title.text = "Run-rate metrics"
+
+data = CategoryChartData()
+data.categories = ["Q1", "Q2", "Q3", "Q4"]
+data.add_series("ARR", (100, 130, 155, 182))
+data.add_series("NDR (%)", (115, 118, 124, 131))
+
+chart_shape = slide.shapes.add_chart(
+    XL_CHART_TYPE.COLUMN_CLUSTERED,
+    Inches(1), Inches(2), Inches(11), Inches(5),
+    data,
+)
+chart = chart_shape.chart
+```
+
+## Updating a chart's data in place
+
+`replace_data` swaps the whole categories-and-series payload while
+keeping the chart's formatting, palette and layout — the right move when
+refreshing a templated deck, since rebuilding the chart would discard
+every style you applied:
+
+```python
+from pptx2.chart.data import CategoryChartData
+
+data = CategoryChartData()
+data.categories = ["Q1", "Q2", "Q3", "Q4"]
+data.add_series("FY27", (18.2, 19.6, 21.4, 24.9))
+
+chart.replace_data(data)      # formatting survives; the embedded
+                              # worksheet is rewritten to match
+```
+
+Adding or removing series works too — the plot re-reads the series count
+from the new data.
+
+## Recolouring (recommended entry point)
+
+`Chart.recolour(palette, by="auto")` is the single entry point you
+should reach for first. ``by="auto"`` (the default) dispatches per
+chart type — per-point colouring on pie / doughnut / pie-of-pie
+variants, per-series colouring on everything else — so a developer
+who just wants "recolour my chart" doesn't have to remember which
+helper applies. ``recolor`` is the US-spelling alias.
+
+```python
+chart.recolour(["#4F9DFF", "#7FCFA1", "#F7B500"])
+
+# Force a mode if you need to:
+chart.recolour(palette, by="series")    # always per-series
+chart.recolour(palette, by="category")  # always per-point
+```
+
+For doughnut / pie charts specifically, `recolour` is the right
+call — `apply_palette` is series-level and a doughnut has only one
+series, so it would tint every slice the same. Calling
+`apply_palette` on a doughnut now warns and routes through the
+right method, but explicit `recolour` is cleaner.
+
+## Chart palettes
+
+`Chart.apply_palette(palette)` recolors every series in declaration
+order from a named built-in or an iterable of color-likes. Palettes
+wrap when the chart has more series than colors:
+
+```python
+chart.apply_palette("modern")          # built-in
+chart.apply_palette(["#4F9DFF", "#7FCFA1", "#F7B500"])
+
+# Mix and match — any color-like works
+from pptx2.dml.color import RGBColor
+chart.apply_palette([
+    RGBColor(0x4F, 0x9D, 0xFF),
+    "#7FCFA1",
+    (247, 181, 0),
+])
+```
+
+Six built-ins ship in `pptx2.chart.palettes`:
+
+- `modern`
+- `classic`
+- `editorial`
+- `vibrant`
+- `monochrome_blue`
+- `monochrome_warm`
+
+```python
+from pptx2.chart.palettes import (
+    CHART_PALETTES,
+    palette_names,
+    resolve_palette,
+)
+
+print(palette_names())                 # → ['modern', 'classic', ...]
+colors = resolve_palette("editorial")  # → list[RGBColor]
+```
+
+`resolve_palette` is also handy for sharing the same colors with
+non-chart shapes.
+
+The `chart_style` integer is left untouched, so the palette overrides
+only the per-series fill without rewriting the rest of the style.
+
+## Quick layouts
+
+`Chart.apply_quick_layout(layout)` toggles title / legend / axis-title
+/ gridline visibility in opinionated combinations. Ten built-in
+presets ship in `pptx2.chart.quick_layouts`:
+
+```python
+chart.apply_quick_layout("title_legend_right")
+chart.apply_quick_layout("title_legend_bottom")
+chart.apply_quick_layout("title_legend_top")
+chart.apply_quick_layout("title_legend_left")
+chart.apply_quick_layout("title_no_legend")
+chart.apply_quick_layout("no_title_no_legend")
+chart.apply_quick_layout("title_axes_legend_right")
+chart.apply_quick_layout("title_axes_legend_bottom")
+chart.apply_quick_layout("minimal")
+chart.apply_quick_layout("dense")
+```
+
+Custom layouts can be supplied as a dict spec:
+
+```python
+chart.apply_quick_layout({
+    "has_title":       True,
+    "title_text":      "ARR ($M)",
+    "has_legend":      True,
+    "legend_position": "bottom",
+    "category_axis":   {"has_major_gridlines": False},
+    "value_axis":      {"has_major_gridlines": True,
+                        "tick_labels": True},
+})
+```
+
+Missing keys leave the chart untouched so layouts compose cleanly.
+Charts without category/value axes (e.g. pie) silently skip the
+corresponding keys.
+
+## Per-series gradient and pattern fills
+
+`chart.series[i].format.fill` is a regular `FillFormat`, so all four
+gradient kinds and `MSO_PATTERN_TYPE` patterns work per-series with no
+chart-specific shim:
+
+```python
+fill = chart.series[0].format.fill
+fill.gradient(kind="linear")
+fill.gradient_stops.replace([
+    (0.0, "#0F2D6B"),
+    (1.0, "#4F9DFF"),
+])
+
+# Patterned fill on the second series
+from pptx2.enum.dml import MSO_PATTERN_TYPE
+pat = chart.series[1].format.fill
+pat.patterned()
+pat.pattern   = MSO_PATTERN_TYPE.WIDE_DOWNWARD_DIAGONAL
+pat.fore_color.rgb = (0x10, 0xB9, 0x81)
+pat.back_color.rgb = (0xFF, 0xFF, 0xFF)
+```
+
+## Dark-deck styling
+
+For dark backgrounds you usually need to recolor every text-bearing
+location *and* every axis line / gridline. Two write-only facades and
+one one-call helper handle it:
+
+```python
+chart.text_color = "#FFFFFF"   # walks chart font, legend, title, data labels
+chart.line_color = "#3A3E5F"   # walks axis lines + gridlines (where present)
+
+# Or, the one-liner:
+chart.apply_dark_theme(text="#FFFFFF", line="#3A3E5F")
+```
+
+`line_color` is conservative: it skips axes that don't exist (pie /
+doughnut), and never materialises gridlines on axes that don't
+already have them — appearance changes are opt-in.
+
+## Horizontal bar charts: reading order
+
+Horizontal bar (``BAR_*``) charts now default to top-to-bottom reading
+order. Feeding ``["A", "B", "C"]`` renders ``A`` at the top, matching
+natural reading order. Column charts retain left-to-right ordering.
+Override post-creation with:
+
+```python
+chart.category_axis.reverse_order = False   # legacy bottom-up ordering
+```
+
+## End-to-end: branded chart
+
+```python
+chart.apply_palette("modern")
+chart.apply_quick_layout("title_axes_legend_bottom")
+
+# Override the title text
+chart.chart_title.text_frame.text = "ARR & NDR ($M / %)"
+```
+
+## Plot & axis fine-tuning ("go to Excel for this" gaps)
+
+Knobs that previously required hand-editing in Excel:
+
+- **Doughnut hole size** — `plot.hole_size = 65` (int 10–90; default 50).
+- **Smoothed lines** — `plot.smooth = True` on a `LinePlot` curve-fits
+  every series; reads back `True` only when all series are smoothed.
+- **Logarithmic value axis** — `chart.value_axis.log_base = 10` (float
+  2–1000); set `= None` to restore a linear axis.
+
+```python
+plot = chart.plots[0]
+plot.hole_size = 65            # doughnut
+plot.smooth = True            # line chart
+chart.value_axis.log_base = 10
+```
+
+## Trendlines, error bars, dual axis (scientific decks)
+
+```python
+s = chart.series[0]
+s.trendlines.add("linear", show_equation=True, show_r_squared=True)
+s.trendlines.add("poly", order=3)            # polynomial
+s.trendlines.add("movingAvg", period=2)      # moving average
+
+s.error_bars.fixed(0.5)                       # or .percentage(5),
+s.error_bars.standard_deviation(1)            # .standard_error(), .custom(plus, minus)
+
+chart.secondary_value_axis                     # add right-hand value axis
+chart.series[1].axis_group = "secondary"       # move a series onto it
+```
+
+Trendlines / error bars are available on bar, line, scatter, area, and
+bubble series (not pie/radar). New axis ids stay signed-int32, so
+PowerPoint never prompts to repair the file.

pptx2/skill/references/compose.md

@@ -0,0 +1,234 @@
+# Composition: from_spec, import_slide, apply_template (Phase 2 + 7)
+
+The `pptx2.compose` package collects entry points for higher-level
+authoring and cross-presentation operations.
+
+## JSON authoring with `from_spec`
+
+The single entry point for generator scripts (LLM or otherwise). The
+spec dict is validated for known keys and value shapes before
+construction (no JSON Schema is involved):
+
+```python
+from pptx2.compose import from_spec
+
+prs = from_spec({
+    # 16:9 widescreen — the modern default. Other shorthands:
+    # "4:3", "16:10", "a4", "letter". Or pass an (w, h) pair / dict
+    # in inches.
+    "slide_size": "16:9",
+    # Brand tokens. Inline dict / preset / yaml / DesignTokens — all
+    # supported. ``"theme"`` is a friendly alias when ``"tokens"`` is
+    # absent.
+    "tokens": {"preset": "modern_light"},
+    "slides": [
+        {
+            "layout": "title",
+            "title": "Q4 Review",
+            "subtitle": "April 2026",
+            "transition": "morph",
+        },
+        {
+            "layout": "kpi",
+            "title": "Run-rate metrics",
+            "kpis": [
+                {"label": "ARR", "value": "$182M", "delta": +0.27},
+                {"label": "NDR", "value": "131%",  "delta": +0.03},
+            ],
+        },
+        {
+            "layout": "bullets",
+            "title": "Customer impact",
+            "bullets": [
+                "Two flagship customers shipped this week.",
+                "NPS improved 8 points QoQ.",
+            ],
+        },
+    ],
+    "lint": "raise",                       # fail loudly on bad output
+})
+
+prs.save("q4-review.pptx")
+```
+
+When `tokens` is present, the legacy alias names `"title"` and
+`"bullets"` are silently upgraded to the styled recipes
+(`"title_recipe"` / `"bullets_recipe"`); this used to be silent and
+strand the deck on default placeholder styling.  Pass an explicit
+recipe layout name (e.g. `"kpi"`, `"chart"`, `"table"`, `"quote"`)
+to skip the alias step and reach the styled recipe directly.
+
+An unrecognized `"layout"` name raises `ValueError` (with the closest
+valid layout suggested) rather than silently producing a blank slide —
+so a typo like `"titel"` fails loudly. Use `"layout": "blank"`
+explicitly when you actually want a blank slide.
+
+`tokens` accepts five shapes:
+
+- A preset by name: `{"preset": "modern_light"}` (optionally with
+  `"overrides": {...}` to layer brand-specific tweaks on top).
+- A YAML brand file: `{"yaml": "brand.yml"}`.
+- An inline dict matching `DesignTokens.from_dict` (palette,
+  typography, radii, shadows, spacings).
+- A `DesignTokens` instance — handy when the same token bag is
+  reused between imperative recipe calls and `from_spec`.
+- `None` (omitted) — falls through to the placeholder layouts on
+  the host template; the recipe slides render with their built-in
+  defaults.
+
+`slide_size` is optional. With no setting, the bundled template's
+4:3 dimensions (10" × 7.5") are used. The shorthand resolves
+through `_SLIDE_SIZE_PRESETS`; pass an inches pair like
+`(13.333, 7.5)` for any custom dimension.
+
+Layout names map either to Phase-9 design recipes (where supplied) or
+to a small built-in set of layouts using the host presentation's
+master.
+
+The `lint` field accepts `"off"`, `"warn"`, or `"raise"`:
+
+- ``"off"`` (default) — no lint pass.
+- ``"warn"`` — log every issue through the stdlib ``logging`` module.
+- ``"raise"`` — raise ``pptx2.exc.LintError`` if any error-severity
+  issue is found.
+
+`from_spec` runs the lint pass internally; outside of `from_spec`,
+iterate the slides yourself (see `lint.md`).
+
+## Free-standing shapes on a spec slide
+
+Layouts and recipes place their own shapes. When you need something a
+layout doesn't provide, a slide entry may carry a `shapes` list, applied
+*after* the layout runs:
+
+```python
+{
+    "layout": "blank",
+    "shapes": [
+        {"name": "card", "shape": "rounded_rectangle",
+         "left": 1, "top": 1, "width": 4, "height": 2,
+         "layer": "card"},
+        {"name": "badge", "shape": "oval", "text": "NEW",
+         "left": 4.4, "top": 0.7, "width": 1.2, "height": 0.8,
+         "layer_above": "card"},
+    ],
+}
+```
+
+Keys: `left` / `top` / `width` / `height` (required; inches, or a
+`Length`), `name`, `shape` (an `MSO_SHAPE` member name,
+case-insensitive — default `"textbox"`), `text`, and the four
+overlap-intent fields below. Unknown keys are rejected with a
+did-you-mean hint rather than silently ignored.
+
+This is deliberately minimal — geometry, type, text, intent. It is not a
+drawing DSL; reach for the Python API when you need fills, effects, or
+anything structural.
+
+### Declaring intentional overlaps in a spec
+
+An LLM writing a spec can declare *at generation time* that an overlap
+is deliberate, so the built deck lints clean without a manual pass. All
+three mechanisms from `lint.md` are spec-level fields:
+
+```python
+{"name": "badge", ..., "lint_group": "kpi-1"}          # n-ary tag
+{"name": "badge", ..., "allow_overlap_with": "card"}   # one pair
+{"name": "badge", ..., "allow_overlap_with": ["card", "rule"]}
+{"name": "card",  ..., "layer": "card"}                # asserts z-order
+{"name": "badge", ..., "layer_above": "card"}
+```
+
+`allow_overlap_with` names other shapes by their spec `name`, not by
+shape id — ids don't exist until the deck is built. Resolution happens
+after every shape on the slide exists, so a **forward reference works**:
+naming a shape defined later in the same list is fine.
+
+Names must be unique within a slide, and a reference must stay within
+its slide — an allowance is keyed on shape id, and ids are only unique
+per slide. Both mistakes raise a `ValueError` locating the bad entry as
+`slides[i].shapes[j]`.
+
+## Cross-presentation operations
+
+```python
+from pptx2 import Presentation
+from pptx2.compose import import_slide, apply_template
+```
+
+### Importing a slide
+
+```python
+src = Presentation("source.pptx")
+dst = Presentation("destination.pptx")
+
+# Clone src.slides[3] into dst, including its layout reference.
+import_slide(dst, src.slides[3], merge_master="dedupe")
+```
+
+Image-rename collisions, layout references, and master/theme parts are
+handled automatically. Two strategies for masters:
+
+- `merge_master="dedupe"` (default-ish, recommended) reuses an
+  equivalent master in the destination if one matches.
+- `merge_master="clone"` always brings a fresh copy of the source
+  master alongside.
+
+### Applying a template
+
+```python
+apply_template(dst, "brand-template.potx")
+```
+
+Re-points every slide's layout/master/theme at masters from the
+`.potx` (or `.pptx`). Slide content is preserved. Layout matching:
+name → type → first layout. Unreferenced old masters / layouts /
+themes are dropped from the saved package.
+
+## End-to-end pipeline
+
+A typical "we have a master deck and need to bolt on N report slides"
+script:
+
+```python
+from pptx2 import Presentation
+from pptx2.compose import import_slide, apply_template, from_spec
+
+# 1. Generate the body slides from data
+body = from_spec({
+    "slides": [
+        {"layout": "kpi_grid", "title": team["name"], "kpis": team["kpis"]}
+        for team in teams
+    ],
+})
+
+# 2. Open the cover deck and append the body slides
+deck = Presentation("cover.pptx")
+for slide in body.slides:
+    import_slide(deck, slide, merge_master="dedupe")
+
+# 3. Re-skin everything against the latest brand template
+apply_template(deck, "brand-2026.potx")
+
+# 4. Lint and save (or set prs.lint_on_save = "raise" and just save)
+from pptx2.exc import LintError
+
+errors = []
+for slide in deck.slides:
+    slide.lint().auto_fix()
+    errors.extend(
+        i for i in slide.lint().issues if i.severity.value == "error"
+    )
+if errors:
+    raise LintError("; ".join(str(e) for e in errors))
+
+deck.save("final.pptx")
+```
+
+## When NOT to use `from_spec`
+
+`from_spec` is intentionally bounded — small built-in layouts plus the
+recipes from `pptx2.design.recipes`. If you need something the recipe
+library doesn't ship, drop down to direct shape construction (or write
+a recipe and contribute it back). Don't try to express arbitrary
+geometry through the spec dict.