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

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

@@ -15,6 +15,43 @@ 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)
++++++++++++++++++++
+
+Added
+.....
+
+* ``audit(..., extra_safe_fonts=[...])`` — the font-warning probe now
+  accepts additional fonts to treat as safe (case-insensitive), on top
+  of the built-in common Windows/macOS/Office list. For rendering
+  environments that genuinely ship a font the built-in list doesn't
+  know — e.g. a Linux sandbox whose font policy standardizes on
+  ``DejaVu Sans`` — this keeps the audit signal instead of drowning it
+  in per-slide warnings.
+
+
 2.15.0 (2026-08-30)
 +++++++++++++++++++
 

{python_pptx2-2.15.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.15.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.15.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.15.0"
+__version__ = "2.17.0"
 
 sys.modules["pptx2.exceptions"] = exceptions
 del sys

{python_pptx2-2.15.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.15.0 → python_pptx2-2.17.0}/src/pptx2/audit.py

@@ -30,7 +30,7 @@ The audit is read-only — it never mutates the deck.
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Iterable
 
 if TYPE_CHECKING:
     from pptx2.api import Presentation
@@ -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:
@@ -174,15 +183,39 @@ def audit(
     *,
     size_warn_bytes: int = 2_000_000,
     check_fonts: bool = True,
+    extra_safe_fonts: "Iterable[str] | None" = None,
 ) -> AuditReport:
     """Walk the deck and return an :class:`AuditReport` summary.
 
     Read-only — never mutates the presentation.  Each slide is linted
     in passing-defaults mode; per-slide overrides should be supplied
     via the slide-level ``slide.lint(...)`` API directly.
+
+    *extra_safe_fonts* names additional fonts to treat as safe for the
+    font-warning probe, on top of the common Windows/macOS/Office set
+    (matching is case-insensitive).  Use it where the rendering
+    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
+    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)
     report.total_slides = len(slides)
@@ -249,7 +282,7 @@ def audit(
                 for para in tf.paragraphs:
                     for run in para.runs:
                         name = run.font.name
-                        if name and name.lower() not in _COMMON_FONTS:
+                        if name and name.lower() not in safe_fonts:
                             report.font_warnings.append((idx, name))
 
         if content_shapes == 0:

{python_pptx2-2.15.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.15.0 → python_pptx2-2.17.0}/src/pptx2/skill/references/lint.md

@@ -178,6 +178,22 @@ if data["has_errors"]:
     ...                        # hand `data` straight to the model to fix
 ```
 
+`audit()` also warns on fonts outside the common Windows/macOS/Office
+safe-list. When the rendering environment genuinely ships a font (e.g.
+DejaVu Sans in a Linux sandbox), pass it instead of letting the deck
+drown in noise:
+
+```python
+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.15.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.15.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.15.0 → python_pptx2-2.17.0}/tests/schema/oxml_schema_validator.py

@@ -130,6 +130,68 @@ def _resolve_mce(doc):
     return doc
 
 
+def _strip_mce_ignorables(doc):
+    """Drop markup an ISO-pure processor must ignore, in place.
+
+    ISO/IEC 29500-3 (Markup Compatibility): a processor that does not
+    understand a namespace listed in ``mc:Ignorable`` MUST ignore every
+    element and attribute in that namespace — and the ``mc:*`` compatibility
+    attributes themselves are outside the base schemas.  The bundled XSDs are
+    exactly such an "MCE-unaware" consumer, so before strict validation this
+    removes:
+
+    * every attribute in the ``mc`` compatibility namespace (``mc:Ignorable``,
+      ``mc:MustUnderstand``, ``mc:ProcessConflicts``, ``mc:PreserveIgnorable``);
+    * every element and attribute in any namespace declared ignorable via
+      ``mc:Ignorable`` (e.g. the ``a14`` equation host namespace 2.14.0+
+      slides declare so PowerPoint tolerates their ``a14:m`` runs).
+
+    Without this, every generated slide fails validation on the
+    ``mc:Ignorable`` attribute alone, deafening the gate to real violations.
+    """
+    # -- 1. collect the namespaces declared ignorable anywhere in the part --
+    ignorable_ns = set()
+    for el in doc.iter():
+        declared = el.get("{%s}Ignorable" % _MC_NS)
+        if not declared:
+            continue
+        for prefix in declared.split():
+            # nsmap is the full in-scope prefix map at this element, so it
+            # resolves prefixes declared on ancestors as well.
+            uri = el.nsmap.get(prefix)
+            if uri is not None:
+                ignorable_ns.add(uri)
+
+    # -- 2. drop elements in ignorable namespaces (root cannot be ignorable:
+    # --    a part whose root is outside the base schema has no schema here) --
+    if ignorable_ns:
+        root = doc.getroottree().getroot()
+        for el in list(doc.iter()):
+            if el is root:
+                continue
+            if etree.QName(el).namespace in ignorable_ns:
+                parent = el.getparent()
+                if parent is not None:
+                    parent.remove(el)
+
+    # -- 3. drop mc:* compatibility attributes and ignorable-ns attributes --
+    mc_attrs = [
+        "{%s}Ignorable" % _MC_NS,
+        "{%s}MustUnderstand" % _MC_NS,
+        "{%s}ProcessConflicts" % _MC_NS,
+        "{%s}PreserveIgnorable" % _MC_NS,
+    ]
+    for el in doc.iter():
+        for attr in list(el.attrib):
+            if attr in mc_attrs:
+                del el.attrib[attr]
+                continue
+            brace = attr.find("}")
+            if brace != -1 and attr[1:brace] in ignorable_ns:
+                del el.attrib[attr]
+    return doc
+
+
 def _should_check(partname: str) -> bool:
     return partname in _CHECKED_EXACT or partname.startswith(_CHECKED_PREFIXES)
 
@@ -440,6 +502,7 @@ def iter_schema_violations(
             schema = _schema_for_namespace(etree.QName(doc).namespace)
             if schema is None:
                 continue
+            _strip_mce_ignorables(doc)
             _resolve_mce(doc)
             if not schema.validate(doc):
                 for err in schema.error_log:  # type: ignore[attr-defined]

{python_pptx2-2.15.0 → python_pptx2-2.17.0}/tests/test_audit.py

@@ -54,6 +54,61 @@ class DescribeAudit:
         assert any(font == "Definitely-Not-A-Real-Font-Name"
                    for _, font in report.font_warnings)
 
+    def it_accepts_extra_safe_fonts(self, prs):
+        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",
+        )
+        # -- without the override the sandbox font is flagged --
+        report = audit(prs)
+        assert any(font == "DejaVu Sans" for _, font in report.font_warnings)
+        # -- and with it (case-insensitively) the warning disappears --
+        report = audit(prs, extra_safe_fonts=["DEJAVU SANS"])
+        assert not any(font == "DejaVu Sans" for _, font in report.font_warnings)
+        # -- other unknown fonts are still flagged alongside the override --
+        slide.shapes.add_text(
+            BBox.from_inches(1, 2.5, 4, 1),
+            text="Also hi",
+            font="Definitely-Not-A-Real-Font-Name",
+        )
+        report = audit(prs, extra_safe_fonts=["DejaVu Sans"])
+        assert any(font == "Definitely-Not-A-Real-Font-Name"
+                   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.15.0 → python_pptx2-2.17.0}/tests/test_files/minimal_slide.xml

@@ -1,4 +1,4 @@
-<p:sld xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+<p:sld xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math" xmlns:a14="http://schemas.microsoft.com/office/drawing/2010/main" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" mc:Ignorable="a14">
   <p:cSld>
     <p:spTree>
       <p:nvGrpSpPr>

{python_pptx2-2.15.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):