python-pptx2 2.16.0__tar.gz → 2.17.0__tar.gz

{python_pptx2-2.16.0 → python_pptx2-2.17.0}/HISTORY.rst

@@ -15,6 +15,28 @@ can sit beside both ``python-pptx`` (``pptx``) and ``power-pptx``
 .. _`scanny/python-pptx`: https://github.com/scanny/python-pptx
 
 
+2.17.0 (2026-08-30)
++++++++++++++++++++
+
+Added
+.....
+
+* ``add_text()`` / ``add_equation()`` accept ``font_family`` and
+  ``valign`` as aliases for ``font`` and ``anchor`` (with ``"mid"``
+  now a valid anchor token). Code generators trained on matplotlib
+  habitually reach for the longer spellings and died with
+  ``TypeError: unexpected keyword argument 'font_family'``; passing
+  both an alias and its canonical with *different* values still
+  raises.
+
+* The audit font-warning safe-list now recognizes the **Aptos**
+  family — the Microsoft 365 default theme fonts since 2024 — and
+  merges the ``PPTX2_SAFE_FONTS`` environment variable (comma- or
+  semicolon-separated) into the safe-list on every ``audit()`` call,
+  so a rendering environment can declare its font inventory once
+  instead of every caller passing ``extra_safe_fonts``.
+
+
 2.16.0 (2026-08-30)
 +++++++++++++++++++
 

{python_pptx2-2.16.0/src/python_pptx2.egg-info → python_pptx2-2.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-pptx2
-Version: 2.16.0
+Version: 2.17.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.16.0 → python_pptx2-2.17.0}/src/pptx2/__init__.py

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

{python_pptx2-2.16.0 → python_pptx2-2.17.0}/src/pptx2/_textstyle.py

@@ -28,6 +28,7 @@ ALIGN_MAP = {
 ANCHOR_MAP = {
     "top": MSO_VERTICAL_ANCHOR.TOP,
     "middle": MSO_VERTICAL_ANCHOR.MIDDLE,
+    "mid": MSO_VERTICAL_ANCHOR.MIDDLE,
     "center": MSO_VERTICAL_ANCHOR.MIDDLE,
     "centre": MSO_VERTICAL_ANCHOR.MIDDLE,
     "bottom": MSO_VERTICAL_ANCHOR.BOTTOM,

{python_pptx2-2.16.0 → python_pptx2-2.17.0}/src/pptx2/audit.py

@@ -41,7 +41,8 @@ __all__ = ["AuditReport", "audit"]
 
 
 # Fonts that ship with stock Windows / macOS / Office installs.  Used as
-# a (very conservative) safe-list for the font_warnings probe.
+# a (very conservative) safe-list for the font_warnings probe.  Aptos and
+# family are the Microsoft 365 default theme fonts since 2024.
 _COMMON_FONTS = frozenset(
     name.lower()
     for name in (
@@ -51,9 +52,17 @@ _COMMON_FONTS = frozenset(
         "Lucida Console", "Palatino", "Palatino Linotype", "Symbol",
         "Wingdings", "Wingdings 2", "Wingdings 3", "Webdings",
         "Inter", "Roboto", "Open Sans", "Lato", "Noto Sans",
+        "Aptos", "Aptos Display", "Aptos Narrow", "Aptos Serif", "Aptos Mono",
+        "Aptos Symbols",
     )
 )
 
+# Environment variable merged into the safe-list on every audit() call, so
+# rendering environments (sandboxes, CI) can declare their font inventory
+# once instead of every caller passing ``extra_safe_fonts``.  Comma- or
+# semicolon-separated font names.
+_SAFE_FONTS_ENV_VAR = "PPTX2_SAFE_FONTS"
+
 
 @dataclass
 class AuditReport:
@@ -188,12 +197,24 @@ def audit(
     environment genuinely ships the font — e.g. ``DejaVu Sans`` in a
     sandbox whose font policy standardizes on it, or a corporate font
     you embed in every deck.
+
+    The ``PPTX2_SAFE_FONTS`` environment variable (comma- or
+    semicolon-separated font names) is merged into the safe-list on
+    every call, so an environment can declare its font inventory once
+    for all callers.
     """
+    import os
+
     from pptx2.shapes.picture import Picture
 
     safe_fonts = _COMMON_FONTS
-    if extra_safe_fonts is not None:
-        safe_fonts = _COMMON_FONTS | frozenset(f.lower() for f in extra_safe_fonts)
+    extra_names = list(extra_safe_fonts) if extra_safe_fonts else []
+    for env_raw in os.environ.get(_SAFE_FONTS_ENV_VAR, "").replace(";", ",").split(","):
+        env_name = env_raw.strip()
+        if env_name:
+            extra_names.append(env_name)
+    if extra_names:
+        safe_fonts = _COMMON_FONTS | frozenset(f.lower() for f in extra_names)
 
     report = AuditReport()
     slides = list(prs.slides)

{python_pptx2-2.16.0 → python_pptx2-2.17.0}/src/pptx2/shapes/shapetree.py

@@ -557,6 +557,24 @@ 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."""
 
@@ -900,12 +918,14 @@ 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,
     ) -> Shape:
@@ -922,14 +942,17 @@ class _BaseGroupShapes(_BaseShapes):
         Keyword args:
 
         * ``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.
         * ``bold`` / ``italic`` — ``True``/``False``/``None``.
         * ``color`` — any "color-like" (``"#RRGGBB"``, ``RGBColor``,
           ``(r, g, b)``).
         * ``align`` — ``"left"`` / ``"center"`` / ``"right"`` /
           ``"justify"``; ``None`` inherits.
-        * ``anchor`` — vertical anchor: ``"top"`` / ``"middle"`` /
-          ``"bottom"``; ``None`` inherits.
+        * ``anchor`` — vertical anchor: ``"top"`` / ``"middle"`` (also
+          ``"mid"`` / ``"center"``) / ``"bottom"``; ``None`` inherits.
+          ``valign`` is accepted as an alias.
         * ``margin_pt`` — uniform margin in points, or a 4-tuple
           ``(top, right, bottom, left)``.
         * ``word_wrap`` — defaults to ``True``.
@@ -940,6 +963,9 @@ class _BaseGroupShapes(_BaseShapes):
         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 len(bbox_or_positional) == 1 and isinstance(bbox_or_positional[0], BBox):
             box = bbox_or_positional[0]
             left, top, width, height = box.left, box.top, box.width, box.height
@@ -986,10 +1012,12 @@ class _BaseGroupShapes(_BaseShapes):
         latex: str,
         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,
     ) -> Shape:
         """Add a text box containing a native PowerPoint equation from LaTeX.
@@ -1008,13 +1036,17 @@ class _BaseGroupShapes(_BaseShapes):
         equation editor.
 
         Keyword args match :meth:`add_text` for *font* / *size_pt* /
-        *color* / *align* / *anchor* / *margin_pt*. *display* (default
+        *color* / *align* / *anchor* / *margin_pt* (including the
+        ``font_family`` / ``valign`` aliases). *display* (default
         |True|) emits a display-math paragraph; set |False| for inline
         OMML.
         """
         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 len(bbox_or_positional) == 1 and isinstance(bbox_or_positional[0], BBox):
             box = bbox_or_positional[0]
             left, top, width, height = box.left, box.top, box.width, box.height

{python_pptx2-2.16.0 → python_pptx2-2.17.0}/src/pptx2/skill/references/lint.md

@@ -187,6 +187,13 @@ drown in noise:
 report = audit(prs, extra_safe_fonts=["DejaVu Sans", "Noto Sans CJK JP"])
 ```
 
+Or declare the inventory once for every caller via the environment
+(merged into the safe-list on each `audit()`):
+
+```bash
+export PPTX2_SAFE_FONTS="DejaVu Sans; Noto Sans CJK JP"
+```
+
 ## Save-time hooks (via `from_spec`)
 
 If you build the deck through `pptx2.compose.from_spec`, the spec dict

{python_pptx2-2.16.0 → python_pptx2-2.17.0/src/python_pptx2.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-pptx2
-Version: 2.16.0
+Version: 2.17.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.16.0 → python_pptx2-2.17.0}/tests/test_audit.py

@@ -78,6 +78,37 @@ class DescribeAudit:
                    for _, font in report.font_warnings)
         assert not any(font == "DejaVu Sans" for _, font in report.font_warnings)
 
+    def it_treats_aptos_the_m365_default_as_safe(self, prs):
+        slide = prs.slides.add_slide(prs.slide_layouts[6])
+        for variant in ("Aptos", "Aptos Display", "Aptos Serif", "Aptos Mono"):
+            slide.shapes.add_text(
+                BBox.from_inches(1, 1, 4, 0.6),
+                text="Hi",
+                font=variant,
+            )
+        report = audit(prs)
+        assert report.font_warnings == []
+
+    def it_merges_the_safe_fonts_environment_variable(self, prs, monkeypatch):
+        slide = prs.slides.add_slide(prs.slide_layouts[6])
+        slide.shapes.add_text(
+            BBox.from_inches(1, 1, 4, 1), text="Hi", font="DejaVu Sans"
+        )
+        slide.shapes.add_text(
+            BBox.from_inches(1, 2.5, 4, 1), text="Ho", font="Corporate Brand Face"
+        )
+        monkeypatch.setenv(
+            "PPTX2_SAFE_FONTS", "DejaVu Sans ; Corporate Brand Face"
+        )
+        report = audit(prs)
+        assert report.font_warnings == []
+        # -- the parameter still stacks on top of the environment --
+        slide.shapes.add_text(
+            BBox.from_inches(1, 4, 4, 1), text="Hmm", font="One More Face"
+        )
+        report = audit(prs, extra_safe_fonts=["One More Face"])
+        assert report.font_warnings == []
+
     def it_treats_full_bleed_only_slide_as_empty(self, prs):
         # A slide whose only shape is a slide-spanning background rect
         # should be reported as empty (it has no content).

{python_pptx2-2.16.0 → python_pptx2-2.17.0}/tests/test_shape_helpers.py

@@ -86,6 +86,35 @@ class DescribeAddText:
         with pytest.raises(ValueError):
             slide.shapes.add_text(BBox.from_inches(0, 0, 4, 1), text="x", align="diagonal")
 
+    def it_accepts_font_family_as_an_alias_for_font(self, slide):
+        # -- matplotlib-trained generators habitually write font_family= --
+        tx = slide.shapes.add_text(BBox.from_inches(1, 1, 4, 1), text="Hi", font_family="Inter")
+        assert tx.text_frame.paragraphs[0].runs[0].font.name == "Inter"
+
+    def it_accepts_identical_font_and_font_family(self, slide):
+        tx = slide.shapes.add_text(
+            BBox.from_inches(1, 1, 4, 1), text="Hi", font="Inter", font_family="Inter"
+        )
+        assert tx.text_frame.paragraphs[0].runs[0].font.name == "Inter"
+
+    def it_rejects_conflicting_font_and_font_family(self, slide):
+        with pytest.raises(TypeError, match="font"):
+            slide.shapes.add_text(
+                BBox.from_inches(1, 1, 4, 1), text="Hi", font="Inter", font_family="Roboto"
+            )
+
+    def it_accepts_valign_mid_as_an_alias_for_anchor(self, slide):
+        from pptx2.enum.text import MSO_VERTICAL_ANCHOR
+
+        tx = slide.shapes.add_text(BBox.from_inches(0, 0, 4, 1), text="x", valign="mid")
+        assert tx.text_frame.vertical_anchor == MSO_VERTICAL_ANCHOR.MIDDLE
+
+    def it_rejects_conflicting_anchor_and_valign(self, slide):
+        with pytest.raises(TypeError, match="anchor"):
+            slide.shapes.add_text(
+                BBox.from_inches(0, 0, 4, 1), text="x", anchor="top", valign="bottom"
+            )
+
 
 class DescribeSetTextPreservingFormat:
     def it_preserves_font_attributes_across_replacement(self, slide):