python-pptx2 2.17.0__py3-none-any.whl → 2.19.0__py3-none-any.whl

pptx2/__init__.py

@@ -57,7 +57,7 @@ from pptx2.parts.slide import (
 if TYPE_CHECKING:
     from pptx2.opc.package import Part
 
-__version__ = "2.17.0"
+__version__ = "2.19.0"
 
 sys.modules["pptx2.exceptions"] = exceptions
 del sys

pptx2/_agent_friendly.py

@@ -0,0 +1,210 @@
+"""Agent-friendly kwarg normalization for the one-call shape helpers.
+
+Code generators (LLM-trained models among them) reliably spell keyword
+arguments the way *other* libraries spell them — matplotlib's
+``fontfamily``/``fontsize``/``ha``/``va``, CSS-flavored ``text-align``,
+``colour`` — and die on ``TypeError: unexpected keyword argument``.  This
+module absorbs that whole error class for the ergonomic helpers
+(``add_text`` / ``add_equation`` / ``add_arrow``) in three layers:
+
+1.  **Synonyms** — a fixed map from common spellings onto each canonical
+    argument (``halign`` → ``align``, ``font_size`` → ``size_pt`` …).
+2.  **Fuzzy matching** — a near-miss kwarg (``algn``, ``colr``) is resolved
+    to its closest canonical or synonym when unambiguous.
+3.  **Didactic errors** — anything still unknown raises a ``TypeError``
+    that names the closest candidate and lists every accepted kwarg, so a
+    model reading the traceback self-corrects in one step.
+
+An alias may *substitute* for its canonical but never contradict it:
+passing two different values for the same logical argument is a genuine
+caller bug and still raises.
+"""
+
+from __future__ import annotations
+
+import difflib
+import functools
+import inspect
+
+# Canonical kwarg -> spellings other ecosystems use for the same thing.
+SYNONYMS: dict[str, tuple[str, ...]] = {
+    "text": ("txt", "string", "content", "label", "caption", "value"),
+    "font": (
+        "font_family", "fontfamily", "font_name", "fontname", "typeface", "family", "face",
+    ),
+    "size_pt": ("size", "font_size", "fontsize", "pt_size", "point_size"),
+    "align": ("halign", "ha", "horizontal_align", "horizontal_alignment", "text_align", "text_alignment"),
+    "anchor": ("valign", "va", "vertical_align", "vertical_alignment", "v_align"),
+    "color": (
+        "colour", "font_color", "font_colour", "text_color", "text_colour",
+        "fg_color", "line_color", "stroke_color",
+    ),
+    "weight_pt": ("weight", "line_weight", "width_pt", "stroke_width"),
+    "bold": ("font_bold", "is_bold"),
+    "italic": ("font_italic", "is_italic", "oblique"),
+    "word_wrap": ("wrap", "wrap_text", "text_wrap"),
+    "margin_pt": ("margin", "padding", "padding_pt", "inset", "inset_pt"),
+    "latex": ("tex", "formula", "equation", "expression", "math"),
+    "left": ("x",),
+    "top": ("y",),
+    "width": ("w",),
+    "height": ("h",),
+    "start": ("begin", "start_point", "start_shape", "from", "source"),
+    "end": ("to", "end_point", "end_shape", "target"),
+    "image_file": ("image", "img", "path", "file", "filename", "image_path", "file_path"),
+    "steps": ("items", "stages", "nodes", "boxes"),
+}
+
+_ALIAS_TO_CANONICAL: dict[str, str] = {
+    alias: canonical
+    for canonical, aliases in SYNONYMS.items()
+    for alias in aliases
+}
+
+_FUZZY_CUTOFF = 0.85
+
+
+def _did_you_mean(name: str, candidates: list[str], known: "list[str] | tuple[str, ...]") -> str | None:
+    """Return the canonical arg *name* points at, or None.
+
+    Near-misses that hit both a canonical and one of its own aliases
+    (``algn`` → ``align`` and ``halign``) are NOT ambiguous — they agree —
+    so candidates are collapsed to their canonical form before the
+    ambiguity check.
+    """
+    if not candidates:
+        return None
+    matches = difflib.get_close_matches(name, candidates, n=3, cutoff=_FUZZY_CUTOFF)
+    distinct = set()
+    for m in matches:
+        canonical = m if m in known else _ALIAS_TO_CANONICAL.get(m)
+        if canonical in known:
+            distinct.add(canonical)
+    if len(distinct) == 1:
+        return distinct.pop()
+    return None
+
+
+def absorb_agent_kwargs(
+    method: str,
+    kwargs: dict,
+    canonical_names: "list[str] | tuple[str, ...]",
+    extra_synonyms: "dict[str, tuple[str, ...]] | None" = None,
+    pass_through_unknown: bool = False,
+) -> dict:
+    """Map alias / near-miss *kwargs* onto canonical names; raise else.
+
+    *canonical_names* lists the kwargs the method actually understands
+    (including any already-bound explicit parameters).  *extra_synonyms*
+    adds call-site-specific spellings (e.g. ``{"cx": ("width", "w")}``
+    for ``add_chart``).  Returns a dict containing only canonical names
+    — unless *pass_through_unknown* is set (for functions that accept
+    ``**kwargs`` themselves), in which case unabsorbable names are
+    passed through verbatim.  A synonym that matches a canonical the
+    caller already supplied with a *different* value raises
+    ``TypeError``; equal values are fine.
+    """
+    known = list(canonical_names)
+    alias_map = dict(_ALIAS_TO_CANONICAL)
+    if extra_synonyms:
+        for canonical, aliases in extra_synonyms.items():
+            for alias in aliases:
+                alias_map[alias] = canonical
+    alias_space = [a for a in alias_map if a not in known]
+    candidates = known + alias_space
+
+    resolved: dict = {}
+    for name, value in kwargs.items():
+        if name in known or name in resolved:
+            if name in resolved and resolved[name] != value:
+                raise TypeError(
+                    f"{method}(): got {name!r} twice with different values "
+                    f"({resolved[name]!r} vs {value!r})"
+                )
+            resolved[name] = value
+            continue
+        canonical = alias_map.get(name)
+        if canonical is not None and canonical not in known:
+            # The alias resolves to an argument this method doesn't take
+            # (e.g. ``to=`` on add_text); fall through to the fuzzy/error
+            # path rather than silently dropping the value.
+            canonical = None
+        if canonical is None:
+            canonical = _did_you_mean(name, candidates, known)
+            if canonical is None:
+                if pass_through_unknown:
+                    resolved[name] = value
+                    continue
+                raise TypeError(
+                    f"{method}(): got an unexpected keyword argument {name!r}. "
+                    f"Accepted: {', '.join(sorted(known))} "
+                    f"(synonyms like font_family/halign/valign/colour are fine)"
+                )
+        if canonical in resolved and resolved[canonical] != value:
+            raise TypeError(
+                f"{method}(): {name!r} and the value already given for "
+                f"{canonical!r} disagree ({value!r} vs {resolved[canonical]!r}); "
+                f"pass one spelling only"
+            )
+        resolved[canonical] = value
+    return resolved
+
+
+def agent_friendly(extra_synonyms=None):
+    """Decorator: make a method/function absorb alias and fuzzy kwargs.
+
+    Wrap any public helper so its keyword arguments get the full
+    treatment from :func:`absorb_agent_kwargs` — global synonyms,
+    per-call *extra_synonyms*, fuzzy near-misses, and didactic errors —
+    without touching its body.  Usable bare (``@agent_friendly``) or
+    with per-method synonyms.  A keyword that repeats a value already
+    bound positionally (through a synonym or exact name) is dropped when
+    equal and raises ``TypeError`` when it contradicts::
+
+        @agent_friendly({"cx": ("width", "w"), "cy": ("height", "h")})
+        def add_chart(self, x, y, cx, cy, chart_type, chart_data): ...
+    """
+    if callable(extra_synonyms):  # used bare: @agent_friendly above def
+        return _decorate_friendly(extra_synonyms, None)
+
+    def decorator(func):
+        return _decorate_friendly(func, extra_synonyms)
+
+    return decorator
+
+
+def _decorate_friendly(func, extra_synonyms):
+    sig = inspect.signature(func)
+    has_self = bool(sig.parameters) and next(iter(sig.parameters)) in ("self", "cls")
+    param_list = [
+        p
+        for p in sig.parameters.values()
+        if p.kind not in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD)
+        and p.name not in ("self", "cls")
+    ]
+    known = tuple(p.name for p in param_list)
+    takes_var_kw = any(
+        p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+    )
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        if kwargs:
+            kwargs = absorb_agent_kwargs(
+                func.__name__, kwargs, known, extra_synonyms,
+                pass_through_unknown=takes_var_kw,
+            )
+            offset = 1 if has_self else 0
+            for i, p in enumerate(param_list[: len(args) - offset]):
+                if p.name in kwargs:
+                    if kwargs[p.name] != args[offset + i]:
+                        raise TypeError(
+                            f"{func.__name__}(): {p.name} given positionally "
+                            f"({args[offset + i]!r}) and by keyword "
+                            f"({kwargs[p.name]!r}) with different values"
+                        )
+                    del kwargs[p.name]
+        return func(*args, **kwargs)
+
+    return wrapper
+

pptx2/diagrams.py

@@ -32,6 +32,7 @@ import math
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Sequence
 
+from pptx2._agent_friendly import agent_friendly
 from pptx2.enum.shapes import MSO_SHAPE
 from pptx2.geometry import BBox
 from pptx2.util import Emu, Inches, Pt
@@ -245,6 +246,14 @@ def _card(
 # ----------------------------------------------------------------------------- pipelines
 
 
+@agent_friendly(
+    {
+        "text_color": ("color", "colour", "fg_color", "text_colour"),
+        "accent": ("accent_color", "primary", "primary_color"),
+        "fill": ("fill_color", "background", "bg"),
+    }
+
+)
 def horizontal_pipeline(
     slide,
     bbox: BBox,
@@ -312,6 +321,14 @@ def horizontal_pipeline(
     return PipelineResult(cards=cards, arrows=arrows)
 
 
+@agent_friendly(
+    {
+        "text_color": ("color", "colour", "fg_color", "text_colour"),
+        "accent": ("accent_color", "primary", "primary_color"),
+        "fill": ("fill_color", "background", "bg"),
+    }
+
+)
 def vertical_pipeline(
     slide,
     bbox: BBox,
@@ -371,6 +388,15 @@ def vertical_pipeline(
 # ----------------------------------------------------------------------------- hub
 
 
+@agent_friendly(
+    {
+        "text_color": ("color", "colour", "fg_color", "text_colour"),
+        "accent": ("accent_color", "primary", "primary_color"),
+        "fill": ("fill_color", "background", "bg"),
+        "spokes": ("items", "stages", "nodes"),
+        "centre": ("center", "hub", "hub_label", "title"),
+    }
+)
 def hub_and_spoke(
     slide,
     bbox: BBox,
@@ -479,6 +505,14 @@ def hub_and_spoke(
 # ----------------------------------------------------------------------------- cycle
 
 
+@agent_friendly(
+    {
+        "text_color": ("color", "colour", "fg_color", "text_colour"),
+        "accent": ("accent_color", "primary", "primary_color"),
+        "fill": ("fill_color", "background", "bg"),
+    }
+
+)
 def cycle(
     slide,
     bbox: BBox,
@@ -553,6 +587,15 @@ def cycle(
 # ----------------------------------------------------------------------------- decision tree
 
 
+@agent_friendly(
+    {
+        "text_color": ("color", "colour", "fg_color", "text_colour"),
+        "accent": ("accent_color", "primary", "primary_color"),
+        "fill": ("fill_color", "background", "bg"),
+        "branches": ("items", "nodes", "children", "steps"),
+        "root": ("root_label", "title", "center"),
+    }
+)
 def decision_tree(
     slide,
     bbox: BBox,
@@ -675,6 +718,14 @@ def decision_tree(
 # ----------------------------------------------------------------------------- columns
 
 
+@agent_friendly(
+    {
+        "text_color": ("color", "colour", "fg_color", "text_colour"),
+        "accent": ("accent_color", "primary", "primary_color"),
+        "fill": ("fill_color", "background", "bg"),
+        "columns": ("items", "cols", "sections"),
+    }
+)
 def comparison_columns(
     slide,
     bbox: BBox,

pptx2/shapes/shapetree.py

@@ -34,6 +34,7 @@ from pptx2.shapes.placeholder import (
     TablePlaceholder,
 )
 from pptx2.shared import ParentedElementProxy
+from pptx2._agent_friendly import agent_friendly
 from pptx2.util import Emu, _coerce_emu, lazyproperty
 
 if TYPE_CHECKING:
@@ -557,24 +558,6 @@ class _BaseShapes(ParentedElementProxy):
         return BaseShapeFactory(shape_elm, self)
 
 
-def _resolve_alias(method: str, arg: str, canonical, alias):
-    """Return *canonical*, falling back to its *alias* kwarg (both nullable).
-
-    Code generators (matplotlib-trained models among them) habitually spell
-    ``font`` as ``font_family`` and ``anchor`` as ``valign``; accepting the
-    alias removes a whole class of one-keyword-away TypeErrors. Passing
-    both with different values is a genuine caller bug and still raises.
-    """
-    if canonical is not None:
-        if alias is not None and alias != canonical:
-            raise TypeError(
-                f"{method}(): pass either {arg}= or its alias, not two "
-                f"different values ({canonical!r} vs {alias!r})"
-            )
-        return canonical
-    return alias
-
-
 class _BaseGroupShapes(_BaseShapes):
     """Base class for shape-trees that can add shapes."""
 
@@ -585,6 +568,7 @@ class _BaseGroupShapes(_BaseShapes):
         super(_BaseGroupShapes, self).__init__(grpSp, parent)
         self._grpSp = grpSp
 
+    @agent_friendly({"cx": ("width", "w"), "cy": ("height", "h"), "chart_data": ("data", "chartdata"), "chart_type": ("type", "charttype")})
     def add_chart(
         self,
         chart_type: XL_CHART_TYPE,
@@ -619,6 +603,7 @@ class _BaseGroupShapes(_BaseShapes):
         _apply_horizontal_bar_default(shape, chart_type)
         return cast("Chart", shape)
 
+    @agent_friendly({"connector_type": ("type", "kind", "connector"), "begin_x": ("x1", "start_x"), "begin_y": ("y1", "start_y"), "end_x": ("x2", "to_x"), "end_y": ("y2", "to_y")})
     def add_connector(
         self,
         connector_type: MSO_CONNECTOR_TYPE,
@@ -639,6 +624,7 @@ class _BaseGroupShapes(_BaseShapes):
         self._recalculate_extents()
         return cast(Connector, self._shape_factory(cxnSp))
 
+    @agent_friendly({"shapes": ("items", "members")})
     def add_group_shape(self, shapes: Iterable[BaseShape] = ()) -> GroupShape:
         """Return a |GroupShape| object newly appended to this shape tree.
 
@@ -657,6 +643,7 @@ class _BaseGroupShapes(_BaseShapes):
             grpSp.recalculate_extents()
         return cast(GroupShape, self._shape_factory(grpSp))
 
+    @agent_friendly
     def add_ole_object(
         self,
         object_file: str | IO[bytes],
@@ -718,6 +705,7 @@ class _BaseGroupShapes(_BaseShapes):
         self._recalculate_extents()
         return cast(GraphicFrame, self._shape_factory(graphicFrame))
 
+    @agent_friendly
     def add_picture(
         self,
         image_file: str | os.PathLike[str] | IO[bytes],
@@ -780,6 +768,7 @@ class _BaseGroupShapes(_BaseShapes):
             picture.top = Emu(ct + new_top)
         return picture
 
+    @agent_friendly({"svg_file": ("svg", "svg_path", "svg_source")})
     def add_svg_picture(
         self,
         svg_file,
@@ -843,6 +832,7 @@ class _BaseGroupShapes(_BaseShapes):
         self._recalculate_extents()
         return cast(Picture, self._shape_factory(pic))
 
+    @agent_friendly({"autoshape_type_id": ("shape_type", "autoshape_type", "shape", "preset_shape")})
     def add_shape(
         self,
         autoshape_type_id: MSO_SHAPE,
@@ -881,6 +871,7 @@ class _BaseGroupShapes(_BaseShapes):
             shape.top = Emu(ct + new_top)
         return shape
 
+    @agent_friendly
     def add_textbox(
         self,
         left: Length,
@@ -918,53 +909,115 @@ class _BaseGroupShapes(_BaseShapes):
         *bbox_or_positional,
         text: str = "",
         font: str | None = None,
-        font_family: str | None = None,
         size_pt: float | None = None,
         bold: bool | None = None,
         italic: bool | None = None,
         color=None,
         align: str | None = None,
         anchor: str | None = None,
-        valign: str | None = None,
         margin_pt: float | tuple[float, float, float, float] | None = None,
         word_wrap: bool | None = True,
+        **kwargs,
     ) -> Shape:
         """Add a textbox carrying *text* with one-call styling.
 
-        Accepts either a :class:`~pptx2.geometry.BBox` positionally
-        or the four ``(left, top, width, height)`` lengths::
+        Accepts either a :class:`~pptx2.geometry.BBox` positionally, the
+        four ``(left, top, width, height)`` lengths positionally, *or* the
+        same four as keyword arguments (``x`` / ``y`` / ``w`` / ``h``
+        synonyms included)::
 
             slide.shapes.add_text(bbox, text="Hello", size_pt=24, bold=True,
                                   color="#0B5CFF", align="center")
             slide.shapes.add_text(Inches(1), Inches(2), Inches(4), Inches(1),
                                   text="Hello")
+            slide.shapes.add_text(x=Inches(1), y=Inches(2), w=Inches(4),
+                                  h=Inches(1), text="Hello")
 
         Keyword args:
 
+        * ``text`` — the string (``label`` / ``content`` synonyms work).
         * ``font`` — typeface name (e.g. ``"Inter"``); ``None`` inherits.
-          ``font_family`` is accepted as an alias (matplotlib habits die
-          hard).
-        * ``size_pt`` — font size in points; ``None`` inherits.
+        * ``size_pt`` — font size in points (synonyms: ``size``,
+          ``font_size``, ``fontsize``).
         * ``bold`` / ``italic`` — ``True``/``False``/``None``.
         * ``color`` — any "color-like" (``"#RRGGBB"``, ``RGBColor``,
-          ``(r, g, b)``).
+          ``(r, g, b)``); ``colour`` / ``text_color`` synonyms work.
         * ``align`` — ``"left"`` / ``"center"`` / ``"right"`` /
-          ``"justify"``; ``None`` inherits.
+          ``"justify"``; ``halign`` is a synonym.
         * ``anchor`` — vertical anchor: ``"top"`` / ``"middle"`` (also
-          ``"mid"`` / ``"center"``) / ``"bottom"``; ``None`` inherits.
-          ``valign`` is accepted as an alias.
+          ``"mid"`` / ``"center"``) / ``"bottom"``; ``valign`` is a
+          synonym.
         * ``margin_pt`` — uniform margin in points, or a 4-tuple
           ``(top, right, bottom, left)``.
         * ``word_wrap`` — defaults to ``True``.
 
+        Misspelled or cross-library kwargs are absorbed when unambiguous
+        (``font_family`` → ``font``, ``fontsize`` → ``size_pt``, ``algn``
+        → ``align`` …); anything unrecognizable raises a ``TypeError``
+        naming the accepted arguments.
+
         Returns the textbox :class:`Shape` so further mutation works as
         normal.
         """
+        from pptx2._agent_friendly import absorb_agent_kwargs
         from pptx2._textstyle import apply_margins, apply_text_style, coerce_anchor
         from pptx2.geometry import BBox
 
-        font = _resolve_alias("add_text", "font", font, font_family)
-        anchor = _resolve_alias("add_text", "anchor", anchor, valign)
+        if kwargs:
+            kwargs = absorb_agent_kwargs(
+                "add_text",
+                kwargs,
+                (
+                    "text", "font", "size_pt", "bold", "italic", "color",
+                    "align", "anchor", "margin_pt", "word_wrap",
+                    "left", "top", "width", "height",
+                ),
+            )
+            geo_names = ("left", "top", "width", "height")
+            if any(g in kwargs for g in geo_names):
+                if bbox_or_positional:
+                    raise TypeError(
+                        "add_text(): got both positional geometry and geometry "
+                        "keyword arguments; pass one form only"
+                    )
+                if not all(g in kwargs for g in geo_names):
+                    missing = [g for g in geo_names if g not in kwargs]
+                    raise TypeError(
+                        "add_text(): geometry keywords need all of "
+                        f"left/top/width/height; missing {', '.join(missing)}"
+                    )
+                bbox_or_positional = tuple(kwargs[g] for g in geo_names)
+            defaults = {
+                "text": "", "font": None, "size_pt": None, "bold": None,
+                "italic": None, "color": None, "align": None, "anchor": None,
+                "margin_pt": None, "word_wrap": True,
+            }
+            given = {
+                "text": text, "font": font, "size_pt": size_pt, "bold": bold,
+                "italic": italic, "color": color, "align": align,
+                "anchor": anchor, "margin_pt": margin_pt,
+                "word_wrap": word_wrap,
+            }
+            for name in defaults:
+                if name not in kwargs:
+                    continue
+                value = kwargs[name]
+                if given[name] != defaults[name] and given[name] != value:
+                    raise TypeError(
+                        f"add_text(): {name!r} given twice with different "
+                        f"values ({given[name]!r} vs {value!r})"
+                    )
+                given[name] = value
+            text = given["text"]
+            font = given["font"]
+            size_pt = given["size_pt"]
+            bold = given["bold"]
+            italic = given["italic"]
+            color = given["color"]
+            align = given["align"]
+            anchor = given["anchor"]
+            margin_pt = given["margin_pt"]
+            word_wrap = given["word_wrap"]
 
         if len(bbox_or_positional) == 1 and isinstance(bbox_or_positional[0], BBox):
             box = bbox_or_positional[0]
@@ -1009,21 +1062,21 @@ class _BaseGroupShapes(_BaseShapes):
     def add_equation(
         self,
         *bbox_or_positional,
-        latex: str,
+        latex: str | None = None,
         display: bool = True,
         font: str | None = None,
-        font_family: str | None = None,
         size_pt: float | None = None,
         color=None,
         align: str | None = "center",
         anchor: str | None = "middle",
-        valign: str | None = None,
         margin_pt: float | tuple[float, float, float, float] | None = None,
+        **kwargs,
     ) -> Shape:
         """Add a text box containing a native PowerPoint equation from LaTeX.
 
-        Accepts either a :class:`~pptx2.geometry.BBox` or
-        ``(left, top, width, height)``::
+        Accepts either a :class:`~pptx2.geometry.BBox`, the four
+        ``(left, top, width, height)`` lengths positionally, or the same
+        four as keyword arguments (``x`` / ``y`` / ``w`` / ``h`` included)::
 
             slide.shapes.add_equation(bbox, latex=r"\\frac{a}{b}", size_pt=28)
             slide.shapes.add_equation(
@@ -1036,16 +1089,74 @@ class _BaseGroupShapes(_BaseShapes):
         equation editor.
 
         Keyword args match :meth:`add_text` for *font* / *size_pt* /
-        *color* / *align* / *anchor* / *margin_pt* (including the
-        ``font_family`` / ``valign`` aliases). *display* (default
-        |True|) emits a display-math paragraph; set |False| for inline
-        OMML.
+        *color* / *align* / *anchor* / *margin_pt*, and *latex* accepts
+        the ``tex`` / ``formula`` / ``equation`` synonyms. Misspelled or
+        cross-library kwargs are absorbed when unambiguous (see
+        :meth:`add_text`). *display* (default |True|) emits a display-math
+        paragraph; set |False| for inline OMML.
         """
+        from pptx2._agent_friendly import absorb_agent_kwargs
         from pptx2._textstyle import apply_margins, coerce_align, coerce_anchor
         from pptx2.geometry import BBox
 
-        font = _resolve_alias("add_equation", "font", font, font_family)
-        anchor = _resolve_alias("add_equation", "anchor", anchor, valign)
+        if kwargs:
+            kwargs = absorb_agent_kwargs(
+                "add_equation",
+                kwargs,
+                (
+                    "latex", "display", "font", "size_pt", "color", "align",
+                    "anchor", "margin_pt", "left", "top", "width", "height",
+                ),
+            )
+            geo_names = ("left", "top", "width", "height")
+            if any(g in kwargs for g in geo_names):
+                if bbox_or_positional:
+                    raise TypeError(
+                        "add_equation(): got both positional geometry and "
+                        "geometry keyword arguments; pass one form only"
+                    )
+                if not all(g in kwargs for g in geo_names):
+                    missing = [g for g in geo_names if g not in kwargs]
+                    raise TypeError(
+                        "add_equation(): geometry keywords need all of "
+                        f"left/top/width/height; missing {', '.join(missing)}"
+                    )
+                bbox_or_positional = tuple(kwargs[g] for g in geo_names)
+            defaults = {
+                "latex": None, "display": True, "font": None, "size_pt": None,
+                "color": None, "align": "center", "anchor": "middle",
+                "margin_pt": None,
+            }
+            given = {
+                "latex": latex, "display": display, "font": font,
+                "size_pt": size_pt, "color": color, "align": align,
+                "anchor": anchor, "margin_pt": margin_pt,
+            }
+            for name in defaults:
+                if name not in kwargs:
+                    continue
+                value = kwargs[name]
+                if given[name] != defaults[name] and given[name] != value:
+                    raise TypeError(
+                        f"add_equation(): {name!r} given twice with different "
+                        f"values ({given[name]!r} vs {value!r})"
+                    )
+                given[name] = value
+            latex = given["latex"]
+            display = given["display"]
+            font = given["font"]
+            size_pt = given["size_pt"]
+            color = given["color"]
+            align = given["align"]
+            anchor = given["anchor"]
+            margin_pt = given["margin_pt"]
+
+        if latex is None:
+            raise TypeError(
+                "add_equation() missing required argument: 'latex' "
+                "(synonyms 'tex' / 'formula' / 'equation' accepted)"
+            )
+
 
         if len(bbox_or_positional) == 1 and isinstance(bbox_or_positional[0], BBox):
             box = bbox_or_positional[0]
@@ -1080,8 +1191,8 @@ class _BaseGroupShapes(_BaseShapes):
 
     def add_arrow(
         self,
-        start,
-        end,
+        start=None,
+        end=None,
         *,
         head: str | None = "triangle",
         tail: str | None = None,
@@ -1094,6 +1205,7 @@ class _BaseGroupShapes(_BaseShapes):
         inset_pt: float = 0.0,
         end_side: str = "auto",
         start_side: str = "auto",
+        **kwargs,
     ) -> Connector:
         """Add an arrow connector with proper arrowhead and inset routing.
 
@@ -1116,12 +1228,18 @@ class _BaseGroupShapes(_BaseShapes):
 
         ``style`` is ``"solid"`` / ``"dashed"`` / ``"dotted"``.
 
-        ``route`` is ``"straight"`` (default), ``"elbow"``, or
-        ``"curved"`` — picks the underlying
+        ``route`` is ``"straight"`` (default), ``"elbow"``, or ``"curved"``
+        — picks the underlying
         :class:`~pptx2.enum.shapes.MSO_CONNECTOR_TYPE`.
 
+        Keyword synonyms are absorbed: ``begin`` / ``from`` / ``source``
+        for ``start``, ``to`` / ``target`` for ``end``, ``stroke_color`` /
+        ``colour`` for ``color``, ``weight`` / ``line_weight`` for
+        ``weight_pt`` — see :meth:`add_text` for the full aliasing story.
+
         Returns the :class:`Connector` so callers can tweak further.
         """
+        from pptx2._agent_friendly import absorb_agent_kwargs
         from pptx2._color import coerce_color
         from pptx2.enum.dml import (
             MSO_LINE_DASH_STYLE,
@@ -1131,6 +1249,64 @@ class _BaseGroupShapes(_BaseShapes):
         from pptx2.enum.shapes import MSO_CONNECTOR_TYPE
         from pptx2.util import Pt
 
+        if kwargs:
+            kwargs = absorb_agent_kwargs(
+                "add_arrow",
+                kwargs,
+                (
+                    "start", "end", "head", "tail", "head_size", "tail_size",
+                    "color", "weight_pt", "style", "route", "inset_pt",
+                    "end_side", "start_side",
+                ),
+            )
+            defaults = {
+                "head": "triangle", "tail": None, "head_size": "medium",
+                "tail_size": "medium", "color": None, "weight_pt": 1.5,
+                "style": "solid", "route": "straight", "inset_pt": 0.0,
+                "end_side": "auto", "start_side": "auto",
+            }
+            given = {
+                "head": head, "tail": tail, "head_size": head_size,
+                "tail_size": tail_size, "color": color, "weight_pt": weight_pt,
+                "style": style, "route": route, "inset_pt": inset_pt,
+                "end_side": end_side, "start_side": start_side,
+            }
+            for name in defaults:
+                if name not in kwargs:
+                    continue
+                value = kwargs[name]
+                if given[name] != defaults[name] and given[name] != value:
+                    raise TypeError(
+                        f"add_arrow(): {name!r} given twice with different "
+                        f"values ({given[name]!r} vs {value!r})"
+                    )
+                given[name] = value
+            head = given["head"]
+            tail = given["tail"]
+            head_size = given["head_size"]
+            tail_size = given["tail_size"]
+            color = given["color"]
+            weight_pt = given["weight_pt"]
+            style = given["style"]
+            route = given["route"]
+            inset_pt = given["inset_pt"]
+            end_side = given["end_side"]
+            start_side = given["start_side"]
+            # start/end synonyms (from=/to=/begin=/source=/target=)
+            if "start" in kwargs:
+                start = kwargs["start"]
+            if "end" in kwargs:
+                end = kwargs["end"]
+        if start is None or end is None:
+            raise TypeError(
+                "add_arrow() missing required argument(s): "
+                + ", ".join(
+                    name for name, value in (("start", start), ("end", end))
+                    if value is None
+                )
+                + " (synonyms begin/from/source and to/target accepted)"
+            )
+
         _CONNECTOR = {
             "straight": MSO_CONNECTOR_TYPE.STRAIGHT,
             "elbow": MSO_CONNECTOR_TYPE.ELBOW,
@@ -1331,6 +1507,7 @@ class _BaseGroupShapes(_BaseShapes):
         sp = self._spTree.add_textbox(id_, name, x, y, cx, cy)
         return sp
 
+    @agent_friendly({"cols": ("columns", "num_cols", "col_count"), "rows": ("num_rows", "row_count")})
     def add_table(
         self,
         rows: int,
@@ -1382,6 +1559,7 @@ class _BaseGroupShapes(_BaseShapes):
             tbl.vert_banding = False
         return shape
 
+    @agent_friendly({"movie_file": ("video", "video_file", "movie", "path", "file")})
     def add_movie(
         self,
         movie_file: str | IO[bytes],

pptx2/skill/references/basics.md

@@ -449,3 +449,16 @@ print(slide.notes)                # "" when the slide has no notes
 `start_slide_index` claims every slide from that position to the deck
 end. `move` raises `IndexError` out of range; `reorder` raises
 `ValueError` unless given a clean permutation.
+
+### Forgiving keyword arguments
+
+Every shape helper (`add_text`, `add_shape`, `add_picture`,
+`add_table`, `add_chart`, `add_textbox`, `add_connector`, `add_movie`,
+`add_arrow`, `add_equation`, ...) and the diagram recipes
+(`horizontal_pipeline`, `hub_and_spoke`, ...) absorb cross-library and
+near-miss kwargs: `font_family=`, `halign=`/`valign=`, `fontsize=`,
+`colour`, `x,y,w,h` geometry keywords, `shape_type=`, `image=`,
+`columns=`, `data=`, `begin=`/`to=`, `items=`/`nodes=` ... Synonyms
+substitute, never contradict (two different values for the same
+logical argument still raise), and a truly unknown kwarg raises a
+`TypeError` listing every accepted name.

{python_pptx2-2.17.0.dist-info → python_pptx2-2.19.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-pptx2
-Version: 2.17.0
+Version: 2.19.0
 Summary: Create, read, and update PowerPoint 2007+ (.pptx) files. Fork of power-pptx / python-pptx, published as python-pptx2.
 Author: Matěj Štágl
 Author-email: stagl@wattlescript.org

{python_pptx2-2.17.0.dist-info → python_pptx2-2.19.0.dist-info}/RECORD

@@ -1,4 +1,5 @@
-pptx2/__init__.py,sha256=lLf03V_PykqZkDfLk7wwFUMFnN9JnqDoW3ziwibWXfE,4076
+pptx2/__init__.py,sha256=SyJ-yjsqXoYHIjHWLRvKdyYTilNWX5KpkyHWIepB8HA,4076
+pptx2/_agent_friendly.py,sha256=wYh9LmVuZMVlwOxzyd1mw0NmtPKQ2cTC21Y1Ww8ehO8,8834
 pptx2/_color.py,sha256=Ureg4dSEdHbwpVZ5eJIyt0kLx_W3mGftmznejth_oLQ,2889
 pptx2/_slide_importer.py,sha256=Ot3lW20eS7fMKsaGaeqPyeS9zVzt5D1WkovwozWwbYY,27033
 pptx2/_svg.py,sha256=pMURsUQaJ9-dqRl4nEZKt1VECNpA8Ghp4EwNRWcBG-c,5973
@@ -9,7 +10,7 @@ pptx2/action.py,sha256=BiDtM80P6oFsNOtLIT1nX82LXEvaGOg4Usaf5CA7kNY,9648
 pptx2/animation.py,sha256=g0OxAkCoGu0QEx3QB9Yu4BOnGLjD3tcLpKoYBAtUW6s,83756
 pptx2/api.py,sha256=n98a5qUhVxSwZ_yG_aXxtDCxtnEp37LPsSIsYsbwsfA,1841
 pptx2/audit.py,sha256=xg1QAs-ByW3xwBEcJ-Y9ptYe2WHKmVuVWAgRKQZfcr8,11276
-pptx2/diagrams.py,sha256=5NqGg-CMj6ZYoEsI9pBD1UHmwQhSAK8oAFYD89NPsVg,24654
+pptx2/diagrams.py,sha256=4NmdFBg367hRjfFh7pQCVivScspmyvPnp94IyncJgCc,26277
 pptx2/exc.py,sha256=k6p-e9h5cKal09-sAv3E1QTXmVDuF8FqewW1CKFQmfw,1276
 pptx2/formats.py,sha256=w0b8YXBjBbPhDu1UV9-1iUJdL62d9_gcQSp9sHKVr_s,5081
 pptx2/geometry.py,sha256=X1tzwqTxXCMPPRpZhHSax6PKGy_-64MAudMI9h3ILJk,15221
@@ -136,12 +137,12 @@ pptx2/shapes/graphfrm.py,sha256=mwA9Wb4WRKBy6sA7KzOZFl3aHlpN-TmWRcE-kiMoqRI,1189
 pptx2/shapes/group.py,sha256=xlcGi3MAzBHX2IM16IATxRgw8NwsPFzTMVbRPYQ7OKg,11036
 pptx2/shapes/picture.py,sha256=U7rwiy7OXn0RgFSEdh07bdhIplWsI82OjFk-mt975J0,14938
 pptx2/shapes/placeholder.py,sha256=9tIeNscnV46hWyMr8ZSiZO3TZr-tt4kZgx6BRB0tCvc,17838
-pptx2/shapes/shapetree.py,sha256=bbrwutelMOcRX8pT88qRLvPyE3x6avIhripnUGalH1I,82851
+pptx2/shapes/shapetree.py,sha256=ZXO1mE2-sMF8Era-EA4mT61Mcj2Hfsr8v-7xOZM_oBw,91287
 pptx2/skill/SKILL.md,sha256=6w7sWflZvhYYIzBsXLjx2uVKqB0793ZTvoZ_SUfzQxg,23668
 pptx2/skill/__init__.py,sha256=bUkfMETwf3K6J7GSE-tLQjdNziS_JceunComLiLIeGI,2665
 pptx2/skill/__main__.py,sha256=ohMLGy1jbjKV5_FqY6aGj4tm_isJ6fznvqUKiE1H6s8,1777
 pptx2/skill/references/animations.md,sha256=ca02l5XCtOQpD-uSCItQixGaW0yONIY0P55yy-T-J1Q,5875
-pptx2/skill/references/basics.md,sha256=jqg6YgXaP2qqpwQoLWPm2OTnECmJEfxuorNXVXY5sm4,14141
+pptx2/skill/references/basics.md,sha256=O2ODa85fIK6mkom4aK2ehb2laEsogmtQ31RF5ckh6B0,14806
 pptx2/skill/references/charts.md,sha256=skCS4Kn1j49mlIQJYDAkcu2VHc3S1mzwqkGT3ZE94wg,8119
 pptx2/skill/references/compose.md,sha256=AfFwqAyQ9ggR140laqRDIUE3OcmTtXpIZH1oPcTOunA,8088
 pptx2/skill/references/design.md,sha256=ne3xVyIwqpkhEkd8XK74QEija040eHve5zBHBx9LeNo,11706
@@ -170,9 +171,9 @@ pptx2/text/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pptx2/text/fonts.py,sha256=ECa9HuBfeTqOi-uJTz_bu7eurC7e1_64RTwDatxmkpk,16498
 pptx2/text/layout.py,sha256=k8bqod6GyshHJtfoqFtH9W-eHTI43IB0e6SLT1ibSUU,12815
 pptx2/text/text.py,sha256=LPqF1B4GSQNSnSlVMm1v7pgtHCymOJPTUG_Kdt5_ou4,55039
-python_pptx2-2.17.0.dist-info/licenses/LICENSE,sha256=hLdud18ZPS9iSG3kBCBLiGYzj4A6zedCHiDejIDBXNg,1230
-python_pptx2-2.17.0.dist-info/METADATA,sha256=mx9AhEC2xmYL-p2zCSn6iHbmj4GaBnNVBBg81sHNg88,14374
-python_pptx2-2.17.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_pptx2-2.17.0.dist-info/entry_points.txt,sha256=UpD1_pA-2BPeN0iDeD-u4NZ_yC78TvBdWu3V1xLsSRE,105
-python_pptx2-2.17.0.dist-info/top_level.txt,sha256=NDdhJ4rOySlDU-cw4g-bQMoZCiy41WszlRXmIiReSRs,6
-python_pptx2-2.17.0.dist-info/RECORD,,
+python_pptx2-2.19.0.dist-info/licenses/LICENSE,sha256=hLdud18ZPS9iSG3kBCBLiGYzj4A6zedCHiDejIDBXNg,1230
+python_pptx2-2.19.0.dist-info/METADATA,sha256=ttj2GNUUnqaxdWQqPvqwfN4lOn6KcRzMWtcBt1UnnCA,14374
+python_pptx2-2.19.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_pptx2-2.19.0.dist-info/entry_points.txt,sha256=UpD1_pA-2BPeN0iDeD-u4NZ_yC78TvBdWu3V1xLsSRE,105
+python_pptx2-2.19.0.dist-info/top_level.txt,sha256=NDdhJ4rOySlDU-cw4g-bQMoZCiy41WszlRXmIiReSRs,6
+python_pptx2-2.19.0.dist-info/RECORD,,