ps-python-pptx 1.1.0__py3-none-any.whl

pptx/oxml/dml/fill.py

@@ -0,0 +1,197 @@
+"""lxml custom element classes for DrawingML-related XML elements."""
+
+from __future__ import annotations
+
+from pptx.enum.dml import MSO_PATTERN_TYPE
+from pptx.oxml import parse_xml
+from pptx.oxml.ns import nsdecls
+from pptx.oxml.simpletypes import (
+    ST_Percentage,
+    ST_PositiveFixedAngle,
+    ST_PositiveFixedPercentage,
+    ST_RelationshipId,
+)
+from pptx.oxml.xmlchemy import (
+    BaseOxmlElement,
+    Choice,
+    OneOrMore,
+    OptionalAttribute,
+    RequiredAttribute,
+    ZeroOrOne,
+    ZeroOrOneChoice,
+)
+
+
+class CT_Blip(BaseOxmlElement):
+    """
+    <a:blip> element
+    """
+
+    rEmbed = OptionalAttribute("r:embed", ST_RelationshipId)
+
+
+class CT_BlipFillProperties(BaseOxmlElement):
+    """
+    Custom element class for <a:blipFill> element.
+    """
+
+    _tag_seq = ("a:blip", "a:srcRect", "a:tile", "a:stretch")
+    blip = ZeroOrOne("a:blip", successors=_tag_seq[1:])
+    srcRect = ZeroOrOne("a:srcRect", successors=_tag_seq[2:])
+    del _tag_seq
+
+    def crop(self, cropping):
+        """
+        Set `a:srcRect` child to crop according to *cropping* values.
+        """
+        srcRect = self._add_srcRect()
+        srcRect.l, srcRect.t, srcRect.r, srcRect.b = cropping
+
+
+class CT_GradientFillProperties(BaseOxmlElement):
+    """`a:gradFill` custom element class."""
+
+    _tag_seq = ("a:gsLst", "a:lin", "a:path", "a:tileRect")
+    gsLst = ZeroOrOne("a:gsLst", successors=_tag_seq[1:])
+    lin = ZeroOrOne("a:lin", successors=_tag_seq[2:])
+    path = ZeroOrOne("a:path", successors=_tag_seq[3:])
+    del _tag_seq
+
+    @classmethod
+    def new_gradFill(cls):
+        """Return newly-created "loose" default gradient subtree."""
+        return parse_xml(
+            '<a:gradFill %s rotWithShape="1">\n'
+            "  <a:gsLst>\n"
+            '    <a:gs pos="0">\n'
+            '      <a:schemeClr val="accent1">\n'
+            '        <a:tint val="100000"/>\n'
+            '        <a:shade val="100000"/>\n'
+            '        <a:satMod val="130000"/>\n'
+            "      </a:schemeClr>\n"
+            "    </a:gs>\n"
+            '    <a:gs pos="100000">\n'
+            '      <a:schemeClr val="accent1">\n'
+            '        <a:tint val="50000"/>\n'
+            '        <a:shade val="100000"/>\n'
+            '        <a:satMod val="350000"/>\n'
+            "      </a:schemeClr>\n"
+            "    </a:gs>\n"
+            "  </a:gsLst>\n"
+            '  <a:lin scaled="0"/>\n'
+            "</a:gradFill>\n" % nsdecls("a")
+        )
+
+    def _new_gsLst(self):
+        """Override default to add minimum subtree."""
+        return CT_GradientStopList.new_gsLst()
+
+
+class CT_GradientStop(BaseOxmlElement):
+    """`a:gs` custom element class."""
+
+    eg_colorChoice = ZeroOrOneChoice(
+        (
+            Choice("a:scrgbClr"),
+            Choice("a:srgbClr"),
+            Choice("a:hslClr"),
+            Choice("a:sysClr"),
+            Choice("a:schemeClr"),
+            Choice("a:prstClr"),
+        ),
+        successors=(),
+    )
+    pos = RequiredAttribute("pos", ST_PositiveFixedPercentage)
+
+
+class CT_GradientStopList(BaseOxmlElement):
+    """`a:gsLst` custom element class."""
+
+    gs = OneOrMore("a:gs")
+
+    @classmethod
+    def new_gsLst(cls):
+        """Return newly-created "loose" default stop-list subtree.
+
+        An `a:gsLst` element must have at least two `a:gs` children. These
+        are the default from the PowerPoint built-in "White" template.
+        """
+        return parse_xml(
+            "<a:gsLst %s>\n"
+            '  <a:gs pos="0">\n'
+            '    <a:schemeClr val="accent1">\n'
+            '      <a:tint val="100000"/>\n'
+            '      <a:shade val="100000"/>\n'
+            '      <a:satMod val="130000"/>\n'
+            "    </a:schemeClr>\n"
+            "  </a:gs>\n"
+            '  <a:gs pos="100000">\n'
+            '    <a:schemeClr val="accent1">\n'
+            '      <a:tint val="50000"/>\n'
+            '      <a:shade val="100000"/>\n'
+            '      <a:satMod val="350000"/>\n'
+            "    </a:schemeClr>\n"
+            "  </a:gs>\n"
+            "</a:gsLst>\n" % nsdecls("a")
+        )
+
+
+class CT_GroupFillProperties(BaseOxmlElement):
+    """`a:grpFill` custom element class"""
+
+
+class CT_LinearShadeProperties(BaseOxmlElement):
+    """`a:lin` custom element class"""
+
+    ang = OptionalAttribute("ang", ST_PositiveFixedAngle)
+
+
+class CT_NoFillProperties(BaseOxmlElement):
+    """`a:noFill` custom element class"""
+
+
+class CT_PatternFillProperties(BaseOxmlElement):
+    """`a:pattFill` custom element class"""
+
+    _tag_seq = ("a:fgClr", "a:bgClr")
+    fgClr = ZeroOrOne("a:fgClr", successors=_tag_seq[1:])
+    bgClr = ZeroOrOne("a:bgClr", successors=_tag_seq[2:])
+    del _tag_seq
+    prst = OptionalAttribute("prst", MSO_PATTERN_TYPE)
+
+    def _new_bgClr(self):
+        """Override default to add minimum subtree."""
+        xml = ("<a:bgClr %s>\n" ' <a:srgbClr val="FFFFFF"/>\n' "</a:bgClr>\n") % nsdecls("a")
+        bgClr = parse_xml(xml)
+        return bgClr
+
+    def _new_fgClr(self):
+        """Override default to add minimum subtree."""
+        xml = ("<a:fgClr %s>\n" ' <a:srgbClr val="000000"/>\n' "</a:fgClr>\n") % nsdecls("a")
+        fgClr = parse_xml(xml)
+        return fgClr
+
+
+class CT_RelativeRect(BaseOxmlElement):
+    """`a:srcRect` element and perhaps others."""
+
+    l = OptionalAttribute("l", ST_Percentage, default=0.0)  # noqa
+    t = OptionalAttribute("t", ST_Percentage, default=0.0)
+    r = OptionalAttribute("r", ST_Percentage, default=0.0)
+    b = OptionalAttribute("b", ST_Percentage, default=0.0)
+
+
+class CT_SolidColorFillProperties(BaseOxmlElement):
+    """`a:solidFill` custom element class."""
+
+    eg_colorChoice = ZeroOrOneChoice(
+        (
+            Choice("a:scrgbClr"),
+            Choice("a:srgbClr"),
+            Choice("a:hslClr"),
+            Choice("a:sysClr"),
+            Choice("a:schemeClr"),
+            Choice("a:prstClr"),
+        ),
+        successors=(),
+    )

pptx/oxml/dml/line.py

@@ -0,0 +1,12 @@
+"""lxml custom element classes for DrawingML line-related XML elements."""
+
+from __future__ import annotations
+
+from pptx.enum.dml import MSO_LINE_DASH_STYLE
+from pptx.oxml.xmlchemy import BaseOxmlElement, OptionalAttribute
+
+
+class CT_PresetLineDashProperties(BaseOxmlElement):
+    """`a:prstDash` custom element class"""
+
+    val = OptionalAttribute("val", MSO_LINE_DASH_STYLE)

pptx/oxml/ns.py

@@ -0,0 +1,129 @@
+"""Namespace related objects."""
+
+from __future__ import annotations
+
+
+# -- Maps namespace prefix to namespace name for all known PowerPoint XML namespaces --
+_nsmap = {
+    "a": "http://schemas.openxmlformats.org/drawingml/2006/main",
+    "c": "http://schemas.openxmlformats.org/drawingml/2006/chart",
+    "cp": "http://schemas.openxmlformats.org/package/2006/metadata/core-properties",
+    "ct": "http://schemas.openxmlformats.org/package/2006/content-types",
+    "dc": "http://purl.org/dc/elements/1.1/",
+    "dcmitype": "http://purl.org/dc/dcmitype/",
+    "dcterms": "http://purl.org/dc/terms/",
+    "ep": "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties",
+    "i": "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image",
+    "m": "http://schemas.openxmlformats.org/officeDocument/2006/math",
+    "mo": "http://schemas.microsoft.com/office/mac/office/2008/main",
+    "mv": "urn:schemas-microsoft-com:mac:vml",
+    "o": "urn:schemas-microsoft-com:office:office",
+    "p": "http://schemas.openxmlformats.org/presentationml/2006/main",
+    "pd": "http://schemas.openxmlformats.org/drawingml/2006/presentationDrawing",
+    "pic": "http://schemas.openxmlformats.org/drawingml/2006/picture",
+    "pr": "http://schemas.openxmlformats.org/package/2006/relationships",
+    "r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+    "sl": "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout",
+    "v": "urn:schemas-microsoft-com:vml",
+    "ve": "http://schemas.openxmlformats.org/markup-compatibility/2006",
+    "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
+    "w10": "urn:schemas-microsoft-com:office:word",
+    "wne": "http://schemas.microsoft.com/office/word/2006/wordml",
+    "wp": "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing",
+    "xsi": "http://www.w3.org/2001/XMLSchema-instance",
+}
+
+pfxmap = {value: key for key, value in _nsmap.items()}
+
+
+class NamespacePrefixedTag(str):
+    """Value object that knows the semantics of an XML tag having a namespace prefix."""
+
+    def __new__(cls, nstag: str):
+        return super(NamespacePrefixedTag, cls).__new__(cls, nstag)
+
+    def __init__(self, nstag: str):
+        self._pfx, self._local_part = nstag.split(":")
+        self._ns_uri = _nsmap[self._pfx]
+
+    @classmethod
+    def from_clark_name(cls, clark_name: str) -> NamespacePrefixedTag:
+        nsuri, local_name = clark_name[1:].split("}")
+        nstag = "%s:%s" % (pfxmap[nsuri], local_name)
+        return cls(nstag)
+
+    @property
+    def clark_name(self):
+        return "{%s}%s" % (self._ns_uri, self._local_part)
+
+    @property
+    def local_part(self):
+        """
+        Return the local part of the tag as a string. E.g. 'foobar' is
+        returned for tag 'f:foobar'.
+        """
+        return self._local_part
+
+    @property
+    def nsmap(self):
+        """
+        Return a dict having a single member, mapping the namespace prefix of
+        this tag to it's namespace name (e.g. {'f': 'http://foo/bar'}). This
+        is handy for passing to xpath calls and other uses.
+        """
+        return {self._pfx: self._ns_uri}
+
+    @property
+    def nspfx(self):
+        """
+        Return the string namespace prefix for the tag, e.g. 'f' is returned
+        for tag 'f:foobar'.
+        """
+        return self._pfx
+
+    @property
+    def nsuri(self):
+        """
+        Return the namespace URI for the tag, e.g. 'http://foo/bar' would be
+        returned for tag 'f:foobar' if the 'f' prefix maps to
+        'http://foo/bar' in _nsmap.
+        """
+        return self._ns_uri
+
+
+def namespaces(*prefixes: str):
+    """Return a dict containing the subset namespace prefix mappings specified by *prefixes*.
+
+    Any number of namespace prefixes can be supplied, e.g. namespaces('a', 'r', 'p').
+    """
+    return {pfx: _nsmap[pfx] for pfx in prefixes}
+
+
+nsmap = namespaces  # alias for more compact use with Element()
+
+
+def nsdecls(*prefixes: str):
+    return " ".join(['xmlns:%s="%s"' % (pfx, _nsmap[pfx]) for pfx in prefixes])
+
+
+def nsuri(nspfx: str):
+    """Return the namespace URI corresponding to `nspfx`.
+
+    Example:
+
+        >>> nsuri("p")
+        "http://schemas.openxmlformats.org/presentationml/2006/main"
+    """
+    return _nsmap[nspfx]
+
+
+def qn(namespace_prefixed_tag: str) -> str:
+    """Return a Clark-notation qualified tag name corresponding to `namespace_prefixed_tag`.
+
+    `namespace_prefixed_tag` is a string like 'p:body'. 'qn' stands for `qualified name`.
+
+    As an example, `qn("p:cSld")` returns:
+        `"{http://schemas.openxmlformats.org/drawingml/2006/main}cSld"`.
+    """
+    nsptag = NamespacePrefixedTag(namespace_prefixed_tag)
+    return nsptag.clark_name

pptx/oxml/presentation.py

@@ -0,0 +1,130 @@
+"""Custom element classes for presentation-related XML elements."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable, cast
+
+from pptx.oxml.simpletypes import ST_SlideId, ST_SlideSizeCoordinate, XsdString
+from pptx.oxml.xmlchemy import BaseOxmlElement, RequiredAttribute, ZeroOrMore, ZeroOrOne
+
+if TYPE_CHECKING:
+    from pptx.util import Length
+
+
+class CT_Presentation(BaseOxmlElement):
+    """`p:presentation` element, root of the Presentation part stored as `/ppt/presentation.xml`."""
+
+    get_or_add_sldSz: Callable[[], CT_SlideSize]
+    get_or_add_sldIdLst: Callable[[], CT_SlideIdList]
+    get_or_add_sldMasterIdLst: Callable[[], CT_SlideMasterIdList]
+
+    sldMasterIdLst: CT_SlideMasterIdList | None = (
+        ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+            "p:sldMasterIdLst",
+            successors=(
+                "p:notesMasterIdLst",
+                "p:handoutMasterIdLst",
+                "p:sldIdLst",
+                "p:sldSz",
+                "p:notesSz",
+            ),
+        )
+    )
+    sldIdLst: CT_SlideIdList | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "p:sldIdLst", successors=("p:sldSz", "p:notesSz")
+    )
+    sldSz: CT_SlideSize | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "p:sldSz", successors=("p:notesSz",)
+    )
+
+
+class CT_SlideId(BaseOxmlElement):
+    """`p:sldId` element.
+
+    Direct child of `p:sldIdLst` that contains an `rId` reference to a slide in the presentation.
+    """
+
+    id: int = RequiredAttribute("id", ST_SlideId)  # pyright: ignore[reportAssignmentType]
+    rId: str = RequiredAttribute("r:id", XsdString)  # pyright: ignore[reportAssignmentType]
+
+
+class CT_SlideIdList(BaseOxmlElement):
+    """`p:sldIdLst` element.
+
+    Direct child of <p:presentation> that contains a list of the slide parts in the presentation.
+    """
+
+    sldId_lst: list[CT_SlideId]
+
+    _add_sldId: Callable[..., CT_SlideId]
+    sldId = ZeroOrMore("p:sldId")
+
+    def add_sldId(self, rId: str) -> CT_SlideId:
+        """Create and return a reference to a new `p:sldId` child element.
+
+        The new `p:sldId` element has its r:id attribute set to `rId`.
+        """
+        return self._add_sldId(id=self._next_id, rId=rId)
+
+    @property
+    def _next_id(self) -> int:
+        """The next available slide ID as an `int`.
+
+        Valid slide IDs start at 256. The next integer value greater than the max value in use is
+        chosen, which minimizes that chance of reusing the id of a deleted slide.
+        """
+        MIN_SLIDE_ID = 256
+        MAX_SLIDE_ID = 2147483647
+
+        used_ids = [int(s) for s in cast("list[str]", self.xpath("./p:sldId/@id"))]
+        simple_next = max([MIN_SLIDE_ID - 1] + used_ids) + 1
+        if simple_next <= MAX_SLIDE_ID:
+            return simple_next
+
+        # -- fall back to search for next unused from bottom --
+        valid_used_ids = sorted(id for id in used_ids if (MIN_SLIDE_ID <= id <= MAX_SLIDE_ID))
+        return (
+            next(
+                candidate_id
+                for candidate_id, used_id in enumerate(valid_used_ids, start=MIN_SLIDE_ID)
+                if candidate_id != used_id
+            )
+            if valid_used_ids
+            else 256
+        )
+
+
+class CT_SlideMasterIdList(BaseOxmlElement):
+    """`p:sldMasterIdLst` element.
+
+    Child of `p:presentation` containing references to the slide masters that belong to the
+    presentation.
+    """
+
+    sldMasterId_lst: list[CT_SlideMasterIdListEntry]
+
+    sldMasterId = ZeroOrMore("p:sldMasterId")
+
+
+class CT_SlideMasterIdListEntry(BaseOxmlElement):
+    """
+    ``<p:sldMasterId>`` element, child of ``<p:sldMasterIdLst>`` containing
+    a reference to a slide master.
+    """
+
+    rId: str = RequiredAttribute("r:id", XsdString)  # pyright: ignore[reportAssignmentType]
+
+
+class CT_SlideSize(BaseOxmlElement):
+    """`p:sldSz` element.
+
+    Direct child of <p:presentation> that contains the width and height of slides in the
+    presentation.
+    """
+
+    cx: Length = RequiredAttribute(  # pyright: ignore[reportAssignmentType]
+        "cx", ST_SlideSizeCoordinate
+    )
+    cy: Length = RequiredAttribute(  # pyright: ignore[reportAssignmentType]
+        "cy", ST_SlideSizeCoordinate
+    )

pptx/oxml/shapes/__init__.py

@@ -0,0 +1,19 @@
+"""Base shape-related objects such as BaseShape."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import TypeAlias
+
+    from pptx.oxml.shapes.autoshape import CT_Shape
+    from pptx.oxml.shapes.connector import CT_Connector
+    from pptx.oxml.shapes.graphfrm import CT_GraphicalObjectFrame
+    from pptx.oxml.shapes.groupshape import CT_GroupShape
+    from pptx.oxml.shapes.picture import CT_Picture
+
+
+ShapeElement: TypeAlias = (
+    "CT_Connector | CT_GraphicalObjectFrame |  CT_GroupShape | CT_Picture | CT_Shape"
+)