python-pptx2 2.13.0__py3-none-any.whl

pptx2/skill/references/design.md

@@ -0,0 +1,366 @@
+# Design system layer (Phase 9)
+
+The `pptx2.design` package turns the low-level API into something where
+the *default* output looks good. Nothing here adds new XML — it's all
+built on top of the foundations from earlier phases.
+
+## Design tokens
+
+`DesignTokens` is a source-agnostic container for brand tokens:
+palette, typography, radii, shadows, spacings.
+
+> **Reads return rich objects, not strings.** `tokens.palette[k]` returns
+> an `RGBColor`, `tokens.typography[k]` returns a `TypographyToken`,
+> `tokens.radii[k]` / `tokens.spacings[k]` return `Length`. Every public
+> setter accepts the rich form, so usually you just pass the lookup
+> through — no `RGBColor.from_hex(...)` round-trip required:
+>
+> ```python
+> shape.fill.fore_color.rgb = tokens.palette["primary"]   # ✓ pass RGBColor
+> shape.fill.fore_color.rgb = "#4F9DFF"                    # ✓ hex string
+> # Don't:
+> shape.fill.fore_color.rgb = RGBColor.from_hex(tokens.palette["primary"])
+> # 'RGBColor' object has no attribute 'startswith'
+> ```
+
+```python
+from pptx2.design.tokens import DesignTokens
+
+tokens = DesignTokens.from_dict({
+    "palette": {
+        "primary":    "#4F9DFF",
+        "neutral":    "#1F2937",
+        "background": "#FFFFFF",
+        "positive":   "#10B981",
+        "negative":   "#EF4444",
+        "on_primary": "#FFFFFF",
+    },
+    "typography": {
+        # Recipes look up the keys "heading" and "body". Other keys are
+        # available for your own use. Bare floats are treated as POINTS;
+        # bare ints are EMU. Use floats unless you know what you're doing.
+        "heading":  {"family": "Inter", "size": 44.0, "bold": True},
+        "body":     {"family": "Inter", "size": 18.0},
+        "caption":  {"family": "Inter", "size": 12.0, "italic": True},
+    },
+    "shadows": {
+        # 'blur' / 'distance' are bare-float points too.
+        "card": {"blur": 18.0, "distance": 4.0, "alpha": 0.18},
+    },
+    "radii":    {"card": 12.0, "button": 6.0},
+    "spacings": {"sm": 8.0, "md": 16.0, "lg": 32.0},
+})
+```
+
+### Other constructors
+
+```python
+# Optional pyyaml dependency
+tokens = DesignTokens.from_yaml("brand.yml")
+
+# Extracts the six accent slots, dk1/dk2/lt1/lt2, hyperlink slots, and
+# major/minor fonts from a deck or template
+tokens = DesignTokens.from_pptx("template.pptx")
+
+# Layer brand-spec overrides on top of a template-extracted base
+tokens = DesignTokens.from_pptx("template.pptx").merge(
+    DesignTokens.from_dict({"palette": {"accent": "#FF6600"}})
+)
+```
+
+## Per-slide appearance overrides
+
+A slide can depart from its master without you editing the master:
+
+```python
+slide.color_variant = "dark"            # swap bg/tx against the same theme
+slide.color_variant = "light"           # the master's default mapping
+slide.color_variant = None              # drop the override entirely
+
+# Backgrounds: give the slide its own and inheritance breaks itself.
+slide.background.fill.solid()
+slide.background.fill.fore_color.rgb = "#102030"
+slide.follow_master_background          # now False (read-only)
+```
+
+`color_variant` takes `"light"` / `"dark"` / `None` — **not** an index.
+`"dark"` swaps backgrounds and text (`bg1=dk1`, `tx1=lt1`, …) so one
+slide reads dark without touching the deck theme. Reading it back
+returns `None` when the slide carries a custom mapping matching neither
+named variant. For any other mapping use `set_clr_map_override(...)`.
+
+`slide.design_group("kpi-card")` is a context manager that tags every
+shape created inside it with the same `lint_group`, so a cluster of
+deliberately-overlapping shapes is declared once rather than per shape:
+
+```python
+with slide.design_group("kpi-card-1"):
+    card = slide.shapes.add_shape(...)
+    label = slide.shapes.add_textbox(...)   # both tagged "kpi-card-1"
+```
+
+There are two adjacent spellings — `slide.shapes.lint_group_scope(name=...)`
+is the same idea on the shape tree, and `slide.lint_group_overlaps(*shapes)`
+tags shapes you already made. Reach for `design_group` while building,
+`lint_group_overlaps` after the fact.
+
+
+## Token-resolving shape style
+
+Every shape exposes a `ShapeStyle` facade. Setters fan assignments out
+to the low-level proxies:
+
+```python
+shape.style.fill        = tokens.palette["primary"]
+shape.style.line        = tokens.palette["primary"]
+shape.style.shadow      = tokens.shadows["card"]
+shape.style.text_color  = tokens.palette["on_primary"]
+shape.style.font        = tokens.typography["body"]
+```
+
+Partial `ShadowToken` assignments leave unset fields untouched, so
+overrides are non-destructive. To clear an effect entirely:
+
+```python
+shape.style.shadow = None
+```
+
+## Layout primitives
+
+Pure build-time geometry — no XML is read or mutated until `place()`.
+
+### Grid
+
+```python
+from pptx2.design.layout import Grid
+from pptx2.util import Pt
+
+grid = Grid(slide, cols=12, rows=6, gutter=Pt(12), margin=Pt(48))
+
+# Place a shape that spans columns 0..5, rows 0..3
+grid.place(card1, col=0, row=0, col_span=6, row_span=4)
+grid.place(card2, col=6, row=0, col_span=6, row_span=4)
+
+# Or compute a Box without placing
+box = grid.cell(col=0, row=4, col_span=12, row_span=2)
+```
+
+A grid doesn't have to span the whole slide — `Grid.from_box` puts one
+over any region (a `BBox`, a `Box`, or a plain `(left, top, width,
+height)` tuple), so a panel can carry its own grid with no slide
+reference:
+
+```python
+from pptx2 import BBox
+
+panel = BBox.from_inches(0.75, 2.4, 11.8, 3.6)
+grid = Grid.from_box(panel, cols=5, rows=2, gutter=Pt(12))
+grid.place(card, col=2, row=1)
+```
+
+For the plain "n equal boxes across this region" case, `panel.columns(5,
+gap=Pt(12))` / `panel.rows(2, ...)` from `BBox` are shorter — reach for
+`Grid` when you need column spans.
+
+### Stack
+
+```python
+from pptx2.design.layout import Stack
+
+stack = Stack(direction="vertical", gap=Pt(8),
+              left=Pt(48), top=Pt(48), width=Pt(600))
+
+stack.place(title,    height=Pt(64))
+stack.place(subtitle, height=Pt(28))
+stack.place(body,     height=Pt(280))
+
+stack.reset()                              # rewind cursor
+```
+
+`direction="horizontal"` walks left-to-right with `gap` between items.
+
+## Slide recipes
+
+Opinionated parameterized slide constructors. Each takes the host
+`Presentation`, recipe-specific kwargs, an optional `DesignTokens`,
+and an optional `transition=` name:
+
+```python
+from pptx2.design.recipes import (
+    title_slide, bullet_slide, kpi_slide,
+    quote_slide, image_hero_slide,
+)
+
+title_slide(
+    prs,
+    title="Q4 Review",
+    subtitle="April 2026",
+    tokens=tokens,
+    transition="morph",
+)
+
+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,
+)
+
+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,
+)
+
+quote_slide(
+    prs,
+    quote="The new dashboards saved my team a week per sprint.",
+    attribution="Director of Eng, Flagship Customer",
+    tokens=tokens,
+)
+
+image_hero_slide(
+    prs,
+    title="Q4 2026",
+    image="hero.jpg",                    # path or binary file-like
+    tokens=tokens,
+)
+```
+
+Recipes use the `Blank` layout and place every shape themselves so the
+rendered geometry doesn't depend on the host template's master.
+
+`kpi_slide` honours `palette["positive"]` / `palette["negative"]` when
+tinting deltas (falls back to green/red when unset). It applies
+`tokens.shadows["card"]` to each card when present.
+
+`image_hero_slide` uses `palette["on_primary"]` for overlay text and
+tints the bottom band with `palette["primary"]` at 55% alpha.
+
+## Shape-level building blocks
+
+For mixed layouts where the slide-level recipes don't fit, reach for
+the shape-level components in `pptx2.design.components`. Both
+honour the deck's `DesignTokens` and return small dataclasses
+exposing the constituent shapes, so callers can compose them into
+custom layouts without re-implementing the styling:
+
+```python
+from pptx2 import add_kpi_card, add_progress_bar
+from pptx2.util import Inches
+
+kpi = add_kpi_card(
+    slide,
+    left=Inches(1), top=Inches(1),
+    width=Inches(2.5), height=Inches(1.9),
+    label="ARR",
+    value="$182M",
+    delta={"delta": +0.27},
+    tokens=tokens,
+)
+# kpi.card / kpi.value_box / kpi.label_box / kpi.delta_box are
+# accessible for further per-deck tweaks.
+
+bar = add_progress_bar(
+    slide,
+    left=Inches(1), top=Inches(3),
+    width=Inches(6), height=Inches(0.3),
+    fraction=0.42,         # 0..1 — clamped if you go over
+    tokens=tokens,
+    fill_color="#4F9DFF",  # optional override
+)
+# bar.track / bar.fill — animate or restyle either independently.
+```
+
+All shape-level components tag their stacked shapes with
+`lint_group` so the linter doesn't flag the intentional overlap
+(label-on-card, fill-on-track) as a collision.
+
+Other components in the same module:
+
+```python
+from pptx2 import (
+    add_gauge,         # progress bar with optional target tick
+    add_status_pill,   # coloured pill + centred label, e.g. "LIVE"
+    add_stat_strip,    # n KPI tiles laid out across a strip with gutter
+    add_article_card,  # title + blurb + optional CTA pill
+)
+
+add_gauge(slide, left=Inches(1), top=Inches(2), width=Inches(4),
+          height=Inches(0.3), fraction=0.62, target=0.80, tokens=tokens)
+
+add_stat_strip(slide, left=Inches(0.5), top=Inches(1.5),
+               width=Inches(12), height=Inches(1.9),
+               items=[{"label": "ARR", "value": "$182M"},
+                      {"label": "NDR", "value": "131%", "delta": +0.03},
+                      {"label": "CAC payback", "value": "8 mo"}],
+               tokens=tokens)
+```
+
+## Starter pack
+
+`examples/starter_pack/` ships three example token sets — `modern`,
+`classic`, and `editorial` — each exporting both a raw `SPEC` dict and
+a ready-to-use `TOKENS`:
+
+```python
+from examples.starter_pack import modern, classic, editorial
+
+prs = Presentation()
+title_slide(prs, title="Hello", subtitle="World", tokens=modern.TOKENS)
+prs.save("modern.pptx")
+```
+
+Run `python -m examples.starter_pack.build_preview` to render one
+preview deck per set into `examples/starter_pack/_out/`.
+
+## End-to-end branded deck
+
+```python
+from pptx2 import Presentation
+from pptx2.design.tokens import DesignTokens
+from pptx2.design.recipes import (
+    title_slide, bullet_slide, kpi_slide, quote_slide,
+)
+
+tokens = DesignTokens.from_dict({
+    "palette": {
+        "primary":   "#4F9DFF",
+        "neutral":   "#1F2937",
+        "positive":  "#10B981",
+        "negative":  "#EF4444",
+        "on_primary": "#FFFFFF",
+    },
+    "typography": {
+        # Recipes look up "heading" and "body". Floats = points, ints = 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}},
+})
+
+prs = Presentation()
+title_slide(prs, title="Q4 Review", subtitle="April 2026",
+            tokens=tokens, transition="morph")
+kpi_slide(prs, title="Run-rate metrics", kpis=[
+    {"label": "ARR", "value": "$182M", "delta": +0.27},
+    {"label": "NDR", "value": "131%",  "delta": +0.03},
+], tokens=tokens)
+bullet_slide(prs, title="Customer impact", bullets=[
+    "Two flagship customers shipped this week.",
+    "NPS improved 8 points QoQ.",
+], tokens=tokens)
+quote_slide(prs, quote="The new dashboards saved my team a week per sprint.",
+            attribution="Director of Eng", tokens=tokens)
+
+prs.save("q4-review.pptx")
+```

pptx2/skill/references/effects.md

@@ -0,0 +1,249 @@
+# Fills and visual effects (Phase 3 + Phase 6)
+
+**This is the canonical reference for fills, colour alpha, gradients,
+and effects.** Other files link here rather than repeat it.
+
+Every shape in `python-pptx2` exposes non-mutating effect proxies. Reads
+return `None` when nothing is set; writes lazily create the underlying
+`<a:effectLst>` / `<a:ln>` element.
+
+Contents: outer shadow · removing a shadow · glow · soft edges · blur ·
+reflection · the card look · corner radius · alpha-tinted fills ·
+gradient fills · line ends/caps/joins.
+
+## Outer shadow
+
+```python
+from pptx2.util import Pt
+from pptx2.dml.color import RGBColor
+
+shadow = card.shadow
+shadow.blur_radius = Pt(8)
+shadow.distance    = Pt(4)
+shadow.direction   = 90.0          # degrees, 90 = down
+shadow.color.rgb   = RGBColor(0, 0, 0)
+shadow.color.alpha = 0.35          # 35% opacity
+```
+
+To restore inheritance, assign `None` to each property — the
+`<a:outerShdw>` element is dropped when the last attribute goes away.
+
+### Removing a shadow entirely: `shadow.clear()`
+
+Restoring inheritance is **not** the same as having no shadow. Auto
+shapes created by `add_shape` carry a `<p:style>` with
+`<a:effectRef idx="2"/>`, which resolves against the theme's effect
+styles — a soft drop shadow in most themes. Clear the explicit
+properties and that inherited shadow is what you're left with: the
+"phantom shadow I never asked for".
+
+```python
+card = slide.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, *box)
+card.shadow.clear()          # flat card, guaranteed
+```
+
+`clear()` drops every explicit shadow element (outer, inner, preset),
+writes the empty `<a:effectLst/>` that overrides inherited effects, and
+re-points `<a:effectRef>` at the theme's empty slot (`idx="0"`). Other
+effects written on the shape — glow, soft edges, blur, reflection — are
+kept. Theme-derived ones are not: `effectRef` names one whole entry in
+the theme's effect-style list, so if a custom theme pairs its shadow
+with a glow, that glow goes too — re-apply it explicitly on the shape.
+Stock Office themes reference shadow-only styles, so this rarely bites.
+It's idempotent and safe on shapes that never had a shadow, including
+text boxes and pictures (which have no `<p:style>` to re-point). On a
+shape imported with an `<a:effectDag>` (an effect tree rather than a
+flat list) the shadow nodes are pruned from that tree instead — the two
+are mutually exclusive in the schema, so writing a list alongside one
+would produce a deck PowerPoint offers to repair.
+
+> ⚠ `shadow.inherit` (read or write) emits a `DeprecationWarning` in
+> 1.1+. Read individual properties for `None`; use `clear()` to remove.
+> `inherit = False` only writes the empty `<a:effectLst/>` — it stays
+> symmetric with `inherit = True` and so cannot touch the theme effect
+> reference. It does **not** remove an inherited shadow; `clear()` does.
+
+## Glow
+
+```python
+card.glow.radius   = Pt(6)
+card.glow.color.rgb = RGBColor(0x4F, 0x9D, 0xFF)
+```
+
+## Soft edges
+
+```python
+card.soft_edges.radius = Pt(3)
+```
+
+## Blur
+
+```python
+card.blur.radius = Pt(4)
+card.blur.grow   = True            # grow with the shape
+```
+
+## Reflection
+
+```python
+card.reflection.blur_radius = Pt(2)
+card.reflection.distance    = Pt(1)
+card.reflection.start_alpha = 0.5
+card.reflection.end_alpha   = 0.0
+```
+
+## Combining for a "card" look
+
+```python
+from pptx2.enum.shapes import MSO_SHAPE
+from pptx2.util import Inches, Pt
+from pptx2.dml.color import RGBColor
+
+card = slide.shapes.add_shape(
+    MSO_SHAPE.ROUNDED_RECTANGLE,
+    Inches(1), Inches(1.5), Inches(4), Inches(2.5),
+)
+card.fill.solid()
+card.fill.fore_color.rgb = RGBColor(0xFF, 0xFF, 0xFF)
+card.line.fill.background()                       # no border
+
+card.corner_radius      = Pt(6)                   # not adjustments[0]
+
+card.shadow.blur_radius = Pt(18)
+card.shadow.distance    = Pt(4)
+card.shadow.direction   = 90.0
+card.shadow.color.rgb   = RGBColor(0, 0, 0)
+card.shadow.color.alpha = 0.18
+
+card.soft_edges.radius  = Pt(1)
+```
+
+For a **flat** card, swap the four shadow lines for `card.shadow.clear()`
+— see above; assigning `None` to them is not equivalent.
+
+### Corner radius in points
+
+`shape.corner_radius` reads and writes a rounded rectangle's radius as a
+length, converting to and from the fraction-of-the-shorter-side that
+OOXML stores in `adjustments[0]`:
+
+```python
+card.corner_radius = Pt(6)
+card.corner_radius.pt        # -> 6.0
+```
+
+Defined for `ROUNDED_RECTANGLE`, `ROUND_1_RECTANGLE`,
+`ROUND_2_SAME_RECTANGLE`, and `ROUND_2_DIAG_RECTANGLE` (the two-radius
+geometries keep their second corner pair on `adjustments[1]`). Raises
+rather than silently clipping when the radius exceeds half the shorter
+side.
+
+## Alpha-tinted fills
+
+```python
+card.fill.solid()
+card.fill.fore_color.rgb   = RGBColor(0x4F, 0x9D, 0xFF)
+card.fill.fore_color.alpha = 0.55                 # glassy
+```
+
+`alpha` is also available on the lazy proxy returned by `Font.color`
+and `LineFormat.color`:
+
+```python
+title_run.font.color.rgb   = RGBColor(0x1F, 0x29, 0x37)
+title_run.font.color.alpha = 0.9
+```
+
+## Gradient fills
+
+The two-liner most decks want — a multi-stop linear gradient at an
+angle:
+
+```python
+bar.fill.linear_gradient("#06D6FE", "#B14AED", angle=90)   # top→bottom
+bar.fill.linear_gradient(
+    [("#06D6FE", 0.0), ("#FFFFFF", 0.5), ("#B14AED", 1.0)],
+    angle=45,
+)
+```
+
+`angle` follows the OOXML convention: `0` is left→right, `90` is
+top→bottom, `180` is right→left, `270` is bottom→top.
+
+### Other kinds, and mutable stops
+
+```python
+fill = card.fill
+fill.gradient(kind="radial")          # also "linear", "rectangular", "shape"
+fill.gradient_kind                    # → "radial"
+
+stops = fill.gradient_stops
+stops.replace([
+    (0.0,  "#0F2D6B"),                # hex with or without leading '#'
+    (0.55, RGBColor(0x4F, 0x9D, 0xFF)),
+    (1.0,  (255, 255, 255)),          # plain RGB tuple also accepted
+])
+
+# Add or remove individual stops
+stops.append(0.85, "#A8C0FF")
+del stops[1]
+```
+
+OOXML enforces a 2-stop minimum; the helper raises if you try to drop
+below that.
+
+## Line ends, caps, joins, compound lines
+
+```python
+from pptx2.enum.dml import (
+    MSO_LINE_CAP_STYLE,
+    MSO_LINE_COMPOUND_STYLE,
+    MSO_LINE_JOIN_STYLE,
+    MSO_LINE_END_TYPE,
+    MSO_LINE_END_SIZE,
+)
+
+line = arrow.line
+line.head_end.type   = MSO_LINE_END_TYPE.TRIANGLE
+line.head_end.width  = MSO_LINE_END_SIZE.MEDIUM
+line.head_end.length = MSO_LINE_END_SIZE.LARGE
+line.tail_end.type   = MSO_LINE_END_TYPE.OVAL
+line.cap             = MSO_LINE_CAP_STYLE.ROUND
+line.compound        = MSO_LINE_COMPOUND_STYLE.DOUBLE
+line.join            = MSO_LINE_JOIN_STYLE.BEVEL
+```
+
+Reads on an unset attribute return `None` — assigning `None` clears
+just that attribute. When the last attribute on a head/tail end goes
+away the `<a:headEnd>` / `<a:tailEnd>` element is dropped so theme
+inheritance is preserved.
+
+## Reading effects without mutating
+
+Always safe to inspect:
+
+```python
+if card.shadow.blur_radius is None:
+    print("no explicit shadow")
+else:
+    print("blur:", card.shadow.blur_radius.pt)
+```
+
+No `<a:effectLst>` is written by the read.
+
+## Inner & preset shadows
+
+Besides `shape.shadow` (outer), shapes expose two sibling shadow effects:
+
+```python
+shape.inner_shadow.blur_radius = Pt(4)    # shadow cast INTO the shape
+shape.inner_shadow.distance = Pt(3)
+shape.inner_shadow.direction = 45.0
+shape.inner_shadow.color.rgb = "112233"
+
+shape.preset_shadow.preset = "shdw5"      # or MSO_PRESET_SHADOW.SHADOW_5
+shape.preset_shadow.color.rgb = "aabbcc"  # one of shdw1..shdw20
+```
+
+A colour child and the required `prst` are written automatically, so
+geometry-only shadows stay schema-valid.