python-pptx2 2.13.0__py3-none-any.whl → 2.15.0__py3-none-any.whl

pptx2/__init__.py

@@ -35,6 +35,7 @@ from pptx2.opc.constants import CONTENT_TYPE as CT
 from pptx2.opc.package import PartFactory
 from pptx2.parts.chart import ChartPart
 from pptx2.parts.coreprops import CorePropertiesPart
+from pptx2.parts.customprops import CustomPropertiesPart
 from pptx2.parts.diagram import (
     DiagramColorsPart,
     DiagramDataPart,
@@ -56,7 +57,7 @@ from pptx2.parts.slide import (
 if TYPE_CHECKING:
     from pptx2.opc.package import Part
 
-__version__ = "2.13.0"
+__version__ = "2.15.0"
 
 sys.modules["pptx2.exceptions"] = exceptions
 del sys
@@ -98,6 +99,7 @@ content_type_to_part_class_map: dict[str, type[Part]] = {
     CT.PML_TEMPLATE_MAIN: PresentationPart,
     CT.PML_SLIDESHOW_MAIN: PresentationPart,
     CT.OPC_CORE_PROPERTIES: CorePropertiesPart,
+    CT.OFC_CUSTOM_PROPERTIES: CustomPropertiesPart,
     CT.PML_NOTES_MASTER: NotesMasterPart,
     CT.PML_NOTES_SLIDE: NotesSlidePart,
     CT.PML_SLIDE: SlidePart,
@@ -136,6 +138,7 @@ PartFactory.part_type_for.update(content_type_to_part_class_map)
 del (
     ChartPart,
     CorePropertiesPart,
+    CustomPropertiesPart,
     DiagramColorsPart,
     DiagramDataPart,
     DiagramLayoutPart,

pptx2/_slide_importer.py

@@ -93,6 +93,37 @@ def import_slide(
     return importer.run()
 
 
+def next_layout_hierarchy_id(prs_part: PresentationPart) -> int:
+    """Return a fresh unique id for a `p:sldMasterId` / `p:sldLayoutId` entry.
+
+    These share one id space starting at 2147483648 (ST_SlideMasterId /
+    ST_SlideLayoutId minimum); duplicates across the presentation are a
+    repair trigger, so scan every master's layout-id list plus the
+    presentation's master-id list for the current maximum. Used both when
+    cloning masters (import_slide) and when adding or cloning slide layouts.
+    """
+    used = [2147483647]
+    prs_element = prs_part._element  # pyright: ignore[reportPrivateUsage]
+    used += [int(v) for v in prs_element.xpath("p:sldMasterIdLst/p:sldMasterId/@id")]
+    for dst_master_part in _iter_master_parts(prs_part):
+        used += [
+            int(v)
+            for v in dst_master_part._element.xpath(  # pyright: ignore[reportPrivateUsage]
+                "p:sldLayoutIdLst/p:sldLayoutId/@id"
+            )
+        ]
+    return max(used) + 1
+
+
+def _iter_master_parts(prs_part: PresentationPart):
+    """Yield each SlideMasterPart referenced from *prs_part*'s `p:sldMasterIdLst`."""
+    prs_element = prs_part._element  # pyright: ignore[reportPrivateUsage]
+    if prs_element.sldMasterIdLst is None:
+        return
+    for entry in prs_element.sldMasterIdLst.sldMasterId_lst:
+        yield prs_part.related_part(entry.rId)
+
+
 # ---------------------------------------------------------------------------
 # Internal implementation
 # ---------------------------------------------------------------------------
@@ -169,13 +200,9 @@ class _SlideImporter:
                 return dst_master_part
         return None
 
-    def _iter_dst_masters(self):  # type: ignore[return]
+    def _iter_dst_masters(self):
         """Yield each SlideMasterPart already in the destination presentation."""
-        prs_element = self._dst_prs_part._element  # pyright: ignore[reportPrivateUsage]
-        if prs_element.sldMasterIdLst is None:
-            return
-        for entry in prs_element.sldMasterIdLst.sldMasterId_lst:
-            yield self._dst_prs_part.related_part(entry.rId)
+        yield from _iter_master_parts(self._dst_prs_part)
 
     def _find_or_clone_layout_in_master(
         self, src_layout_part: SlideLayoutPart, dst_master_part: SlideMasterPart
@@ -325,22 +352,9 @@ class _SlideImporter:
     def _next_hierarchy_id(self) -> int:
         """Return a fresh unique id for a `p:sldMasterId` / `p:sldLayoutId` entry.
 
-        These share one id space starting at 2147483648 (ST_SlideMasterId /
-        ST_SlideLayoutId minimum); duplicates across the presentation are a
-        repair trigger, so scan every master's layout-id list plus the
-        presentation's master-id list for the current maximum.
+        See :func:`next_layout_hierarchy_id`.
         """
-        used = [2147483647]
-        prs_element = self._dst_prs_part._element  # pyright: ignore[reportPrivateUsage]
-        used += [int(v) for v in prs_element.xpath("p:sldMasterIdLst/p:sldMasterId/@id")]
-        for dst_master_part in self._iter_dst_masters():
-            used += [
-                int(v)
-                for v in dst_master_part._element.xpath(  # pyright: ignore[reportPrivateUsage]
-                    "p:sldLayoutIdLst/p:sldLayoutId/@id"
-                )
-            ]
-        return max(used) + 1
+        return next_layout_hierarchy_id(self._dst_prs_part)
 
     # ------------------------------------------------------------------
     # Slide copy

pptx2/api.py

@@ -18,12 +18,14 @@ if TYPE_CHECKING:
     from pptx2.parts.presentation import PresentationPart
 
 
-def Presentation(pptx: str | IO[bytes] | None = None) -> presentation.Presentation:
+def Presentation(
+    pptx: str | os.PathLike[str] | IO[bytes] | None = None,
+) -> presentation.Presentation:
     """
     Return a |Presentation| object loaded from *pptx*, where *pptx* can be
-    either a path to a ``.pptx`` file (a string) or a file-like object. If
-    *pptx* is missing or ``None``, the built-in default presentation
-    "template" is loaded.
+    either a path to a ``.pptx`` file (a string or ``pathlib.Path``) or a
+    file-like object. If *pptx* is missing or ``None``, the built-in default
+    presentation "template" is loaded.
     """
     if pptx is None:
         pptx = _default_pptx_path()
@@ -45,5 +47,9 @@ def _default_pptx_path() -> str:
 
 def _is_pptx_package(prs_part: PresentationPart):
     """Return |True| if *prs_part* is a valid main document part, |False| otherwise."""
-    valid_content_types = (CT.PML_PRESENTATION_MAIN, CT.PML_PRES_MACRO_MAIN)
+    valid_content_types = (
+        CT.PML_PRESENTATION_MAIN,
+        CT.PML_PRES_MACRO_MAIN,
+        CT.PML_TEMPLATE_MAIN,
+    )
     return prs_part.content_type in valid_content_types

pptx2/chart/data.py

@@ -12,6 +12,7 @@ from pptx2.chart.xlsx import (
     XyWorkbookWriter,
 )
 from pptx2.chart.xmlwriter import ChartXmlWriter
+from pptx2.oxml.simpletypes import ST_FirstSliceAng
 from pptx2.util import lazyproperty
 
 
@@ -268,6 +269,8 @@ class CategoryChartData(_BaseChartData):
     The corresponding X value is inferred by its position in the sequence.
     """
 
+    _first_slice_angle = 0
+
     def add_category(self, label):
         """
         Return a newly created |data.Category| object having *label* and
@@ -323,6 +326,20 @@ class CategoryChartData(_BaseChartData):
         """
         return self._workbook_writer.categories_ref
 
+    @property
+    def first_slice_angle(self):
+        """
+        Read/write int in range 0..359 specifying the angle in degrees of
+        the first slice for a doughnut chart created from this chart data,
+        clockwise from 12 o'clock. The default is 0, the PowerPoint default.
+        """
+        return self._first_slice_angle
+
+    @first_slice_angle.setter
+    def first_slice_angle(self, value):
+        ST_FirstSliceAng.validate(value)
+        self._first_slice_angle = int(value)
+
     def values_ref(self, series):
         """
         The Excel worksheet reference to the values for *series* (not

pptx2/chart/plot.py

@@ -220,6 +220,25 @@ class DoughnutPlot(_BasePlot):
         holeSize = self._element.get_or_add_holeSize()
         holeSize.val = value
 
+    @property
+    def first_slice_angle(self):
+        """
+        Read/write int in range 0..359 specifying the angle in degrees of
+        the first slice of this doughnut, clockwise from 12 o'clock. The
+        PowerPoint default for a new doughnut chart is 0, which is what this
+        property reports when no explicit ``<c:firstSliceAng>`` element is
+        present.
+        """
+        firstSliceAng = self._element.firstSliceAng
+        if firstSliceAng is None:
+            return 0
+        return firstSliceAng.val
+
+    @first_slice_angle.setter
+    def first_slice_angle(self, value):
+        firstSliceAng = self._element.get_or_add_firstSliceAng()
+        firstSliceAng.val = value
+
 
 class LinePlot(_BasePlot):
     """

pptx2/chart/xmlwriter.py

@@ -669,7 +669,7 @@ class _DoughnutChartXmlWriter(_BaseChartXmlWriter):
             '          <c:showBubbleSize val="0"/>\n'
             '          <c:showLeaderLines val="1"/>\n'
             "        </c:dLbls>\n"
-            '        <c:firstSliceAng val="0"/>\n'
+            '        <c:firstSliceAng val="{firstSliceAng}"/>\n'
             '        <c:holeSize val="50"/>\n'
             "      </c:doughnutChart>\n"
             "    </c:plotArea>\n"
@@ -693,7 +693,7 @@ class _DoughnutChartXmlWriter(_BaseChartXmlWriter):
             "    </a:p>\n"
             "  </c:txPr>\n"
             "</c:chartSpace>\n"
-        ).format(**{"ser_xml": self._ser_xml})
+        ).format(**{"ser_xml": self._ser_xml, "firstSliceAng": self._firstSliceAng})
 
     @property
     def _explosion_xml(self):
@@ -701,6 +701,15 @@ class _DoughnutChartXmlWriter(_BaseChartXmlWriter):
             return '          <c:explosion val="25"/>\n'
         return ""
 
+    @property
+    def _firstSliceAng(self):
+        """
+        The integer angle in degrees for the ``<c:firstSliceAng>`` element,
+        taken from the chart data object when it specifies one and 0
+        (the PowerPoint default) otherwise.
+        """
+        return getattr(self._chart_data, "first_slice_angle", 0)
+
     @property
     def _ser_xml(self):
         xml = ""

pptx2/enum/text.py

@@ -228,3 +228,75 @@ class PP_PARAGRAPH_ALIGNMENT(BaseXmlEnum):
 
 
 PP_ALIGN = PP_PARAGRAPH_ALIGNMENT
+
+
+class MSO_TEXT_FIELD_TYPE(BaseXmlEnum):
+    """Specifies the kind of value a text field (`a:fld`) displays.
+
+    Used with :meth:`.Paragraph.add_field` to add a run-like field element to a paragraph.
+    The field's displayed text (the actual slide number, the current date, ...) is computed by
+    PowerPoint when the slide is rendered; the `a:t` child element holds only the "cached"
+    placeholder text readers that do not compute fields will show.
+
+    Example::
+
+        from pptx2.enum.text import MSO_TEXT_FIELD_TYPE
+
+        paragraph.add_field(MSO_TEXT_FIELD_TYPE.SLIDE_NUMBER)
+
+    The XML tokens are the ST_TextFieldType values DrawingML defines ("slidenum", "datetime",
+    "datetime1" through "datetime13") plus "datetimeFigureOut", the token PowerPoint writes for
+    an automatically updated date.
+    """
+
+    SLIDE_NUMBER = (1, "slidenum", "The number of the slide the field appears on.")
+    """The number of the slide the field appears on."""
+
+    DATETIME = (2, "datetime", "The date and time in the containing document's default format.")
+    """The date and time in the containing document's default format."""
+
+    DATETIME_1 = (3, "datetime1", "Predefined date/time format 1 (locale-dependent rendering).")
+    """Predefined date/time format 1 (locale-dependent rendering)."""
+
+    DATETIME_2 = (4, "datetime2", "Predefined date/time format 2 (locale-dependent rendering).")
+    """Predefined date/time format 2 (locale-dependent rendering)."""
+
+    DATETIME_3 = (5, "datetime3", "Predefined date/time format 3 (locale-dependent rendering).")
+    """Predefined date/time format 3 (locale-dependent rendering)."""
+
+    DATETIME_4 = (6, "datetime4", "Predefined date/time format 4 (locale-dependent rendering).")
+    """Predefined date/time format 4 (locale-dependent rendering)."""
+
+    DATETIME_5 = (7, "datetime5", "Predefined date/time format 5 (locale-dependent rendering).")
+    """Predefined date/time format 5 (locale-dependent rendering)."""
+
+    DATETIME_6 = (8, "datetime6", "Predefined date/time format 6 (locale-dependent rendering).")
+    """Predefined date/time format 6 (locale-dependent rendering)."""
+
+    DATETIME_7 = (9, "datetime7", "Predefined date/time format 7 (locale-dependent rendering).")
+    """Predefined date/time format 7 (locale-dependent rendering)."""
+
+    DATETIME_8 = (10, "datetime8", "Predefined date/time format 8 (locale-dependent rendering).")
+    """Predefined date/time format 8 (locale-dependent rendering)."""
+
+    DATETIME_9 = (11, "datetime9", "Predefined date/time format 9 (locale-dependent rendering).")
+    """Predefined date/time format 9 (locale-dependent rendering)."""
+
+    DATETIME_10 = (12, "datetime10", "Predefined date/time format 10 (locale-dependent rendering).")
+    """Predefined date/time format 10 (locale-dependent rendering)."""
+
+    DATETIME_11 = (13, "datetime11", "Predefined date/time format 11 (locale-dependent rendering).")
+    """Predefined date/time format 11 (locale-dependent rendering)."""
+
+    DATETIME_12 = (14, "datetime12", "Predefined date/time format 12 (locale-dependent rendering).")
+    """Predefined date/time format 12 (locale-dependent rendering)."""
+
+    DATETIME_13 = (15, "datetime13", "Predefined date/time format 13 (locale-dependent rendering).")
+    """Predefined date/time format 13 (locale-dependent rendering)."""
+
+    DATETIME_FIGURE_OUT = (
+        16,
+        "datetimeFigureOut",
+        "The current date, in the format PowerPoint figures out automatically.",
+    )
+    """The current date, in the format PowerPoint figures out automatically."""

pptx2/math.py

@@ -2,10 +2,11 @@
 
 PowerPoint stores editable equations as Office Math (OMML) wrapped in an
 ``a14:m`` marker inside a DrawingML paragraph. This module does not compile
-LaTeX itself: it calls ``latex2mathml`` then ``mathml2omml`` and wraps the
-result so PowerPoint will open it.
+LaTeX itself: ``latex2mathml`` turns the fragment into MathML and the
+bundled ``pptx2.mathml2omml`` port (from mathml2omml-plus / ECMA-376 §7.1)
+turns that into Office Math.
 
-Install the converters with::
+Install the LaTeX front-end with::
 
     pip install "python-pptx2[math]"
 """
@@ -17,6 +18,7 @@ from typing import TYPE_CHECKING, Any
 
 from lxml import etree
 
+from pptx2.mathml2omml import convert as mathml_to_omml
 from pptx2.oxml import parse_xml
 from pptx2.oxml.ns import nsuri, qn
 
@@ -26,6 +28,8 @@ if TYPE_CHECKING:
 
 A14_NS = nsuri("a14")
 M_NS = nsuri("m")
+W_NS = nsuri("w")
+MC_NS = nsuri("mc")
 
 _WRAPPER_PATTERNS = (
     re.compile(r"^\s*\$\$(.*)\$\$\s*$", re.DOTALL),
@@ -47,9 +51,15 @@ _DISPLAY_JC = {
     "justify": "centerGroup",
 }
 
+_SLD_OPEN_RE = re.compile(
+    r"^(<\?xml[^>]*\?>\s*)?(<p:sld\b)([^>]*)(>)",
+    re.DOTALL,
+)
+_IGNORABLE_RE = re.compile(r'\smc:Ignorable="([^"]*)"')
+
 
 class MathBackendUnavailable(ImportError):
-    """Raised when the optional LaTeX → OMML converters are not installed."""
+    """Raised when the optional LaTeX → MathML converter is not installed."""
 
 
 def strip_math_delimiters(source: str) -> str:
@@ -72,13 +82,13 @@ def latex_to_omml(latex: str) -> str:
     if not fragment:
         raise ValueError("latex must be a non-empty math fragment")
 
-    converter, mathml2omml = _import_math_backends()
+    converter = _import_latex2mathml()
     try:
         mathml = converter.convert(fragment)
     except Exception as exc:
         raise ValueError(f"LaTeX could not be converted to MathML: {exc}") from exc
     try:
-        omml = mathml2omml.convert(mathml)
+        omml = mathml_to_omml(mathml)
     except Exception as exc:
         raise ValueError(f"MathML could not be converted to Office Math: {exc}") from exc
     if not isinstance(omml, str) or not omml.strip():
@@ -94,7 +104,10 @@ def office_math_element(
 ) -> CT_OfficeMathMarker:
     """Return an ``a14:m`` element ready to append to a DrawingML paragraph."""
     payload = _omml_payload(latex_to_omml(latex), display=display, align=align)
-    xml = f'<a14:m xmlns:a14="{A14_NS}" xmlns:m="{M_NS}">{payload}</a14:m>'
+    xml = (
+        f'<a14:m xmlns:a14="{A14_NS}" xmlns:m="{M_NS}" xmlns:w="{W_NS}">'
+        f"{payload}</a14:m>"
+    )
     return parse_xml(xml)
 
 
@@ -105,7 +118,7 @@ def style_office_math(
     color: Any = None,
     font: str | None = None,
 ) -> None:
-    """Write run-level size / color / typeface onto each ``m:r`` inside *marker*."""
+    """Write size / color / typeface onto every ``m:r`` and ``m:ctrlPr``."""
     if size_pt is None and color is None and font is None:
         return
 
@@ -113,32 +126,70 @@ def style_office_math(
 
     sz = None if size_pt is None else str(int(round(float(size_pt) * 100)))
     rgb = None if color is None else str(coerce_color(color))
+    r_pr_xml = _drawing_rpr(sz, rgb, font)
 
     for run in marker.iter(qn("m:r")):
-        rPr = run.find(qn("a:rPr"))
-        if rPr is None:
-            rPr = etree.Element(qn("a:rPr"))
-            text = run.find(qn("m:t"))
-            if text is not None:
-                text.addprevious(rPr)
-            else:
-                run.append(rPr)
-        if sz is not None:
-            rPr.set("sz", sz)
-        if font is not None:
-            latin = rPr.find(qn("a:latin"))
-            if latin is None:
-                latin = etree.SubElement(rPr, qn("a:latin"))
-            latin.set("typeface", font)
-        if rgb is not None:
-            solid = rPr.find(qn("a:solidFill"))
-            if solid is None:
-                solid = etree.Element(qn("a:solidFill"))
-                rPr.insert(0, solid)
-            srgb = solid.find(qn("a:srgbClr"))
-            if srgb is None:
-                srgb = etree.SubElement(solid, qn("a:srgbClr"))
-            srgb.set("val", rgb)
+        _stamp_arpr(run, r_pr_xml, before=qn("m:t"))
+    for ctrl in marker.iter(qn("m:ctrlPr")):
+        _stamp_arpr(ctrl, r_pr_xml, before=None)
+
+
+def prepare_slide_xml_for_math(xml: bytes) -> bytes:
+    """Ensure the ``p:sld`` root declares math host namespaces.
+
+    PowerPoint requires ``xmlns:m``, ``xmlns:a14``, ``xmlns:mc`` and
+    ``mc:Ignorable="a14"`` on the slide (MS-PPTX §2.2.8). Bare ``m:oMath``
+    without ``a14:m`` is stripped on open.
+    """
+    match = _SLD_OPEN_RE.match(xml.decode("utf-8"))
+    if match is None:
+        return xml
+    decl, start, attrs, close = match.group(1) or "", match.group(2), match.group(3), match.group(4)
+    for prefix, uri in (
+        ("xmlns:m", M_NS),
+        ("xmlns:a14", A14_NS),
+        ("xmlns:mc", MC_NS),
+        ("xmlns:w", W_NS),
+    ):
+        if f'{prefix}="' not in attrs:
+            attrs += f' {prefix}="{uri}"'
+    ignorable = _IGNORABLE_RE.search(attrs)
+    if ignorable is None:
+        attrs += ' mc:Ignorable="a14"'
+    else:
+        tokens = ignorable.group(1).split()
+        if "a14" not in tokens:
+            tokens.append("a14")
+            attrs = _IGNORABLE_RE.sub(f' mc:Ignorable="{" ".join(tokens)}"', attrs, count=1)
+    rewritten = decl + start + attrs + close + xml.decode("utf-8")[match.end() :]
+    return rewritten.encode("utf-8")
+
+
+def _drawing_rpr(sz: str | None, rgb: str | None, font: str | None) -> etree._Element:
+    attrs = {"dirty": "0"}
+    if sz is not None:
+        attrs["sz"] = sz
+    r_pr = etree.Element(qn("a:rPr"), attrs)
+    if rgb is not None:
+        solid = etree.SubElement(r_pr, qn("a:solidFill"))
+        etree.SubElement(solid, qn("a:srgbClr")).set("val", rgb)
+    if font is not None:
+        etree.SubElement(r_pr, qn("a:latin")).set("typeface", font)
+    return r_pr
+
+
+def _stamp_arpr(parent: Any, template: etree._Element, before: str | None) -> None:
+    existing = parent.find(qn("a:rPr"))
+    stamped = etree.fromstring(etree.tostring(template))
+    if existing is not None:
+        parent.replace(existing, stamped)
+        return
+    if before is not None:
+        sibling = parent.find(before)
+        if sibling is not None:
+            sibling.addprevious(stamped)
+            return
+    parent.append(stamped)
 
 
 def _omml_payload(omml: str, *, display: bool, align: str | None) -> str:
@@ -156,22 +207,23 @@ def _omml_payload(omml: str, *, display: bool, align: str | None) -> str:
     )
 
 
-def _import_math_backends():
+def _import_latex2mathml():
     try:
         import latex2mathml.converter as latex2mathml_converter
-        import mathml2omml
     except ImportError as exc:
         raise MathBackendUnavailable(
-            "Native PowerPoint equations require the latex2mathml and "
-            "mathml2omml packages. Install with: pip install 'python-pptx2[math]'"
+            "Native PowerPoint equations require latex2mathml. "
+            "Install with: pip install 'python-pptx2[math]'"
         ) from exc
-    return latex2mathml_converter, mathml2omml
+    return latex2mathml_converter
 
 
 __all__ = (
     "MathBackendUnavailable",
     "latex_to_omml",
+    "mathml_to_omml",
     "office_math_element",
+    "prepare_slide_xml_for_math",
     "strip_math_delimiters",
     "style_office_math",
 )