python-pptx2 2.13.0__py3-none-any.whl

pptx2/oxml/dml/fill.py

@@ -0,0 +1,316 @@
+"""lxml custom element classes for DrawingML-related XML elements."""
+
+from __future__ import annotations
+
+from pptx2.enum.dml import MSO_PATTERN_TYPE
+from pptx2.oxml import parse_xml
+from pptx2.oxml.ns import nsdecls
+from pptx2.oxml.simpletypes import (
+    ST_FixedPercentage,
+    ST_Percentage,
+    ST_PositiveFixedAngle,
+    ST_PositiveFixedPercentage,
+    ST_RelationshipId,
+)
+from pptx2.oxml.xmlchemy import (
+    BaseOxmlElement,
+    Choice,
+    OneOrMore,
+    OptionalAttribute,
+    RequiredAttribute,
+    ZeroOrOne,
+    ZeroOrOneChoice,
+)
+
+
+class CT_Blip(BaseOxmlElement):
+    """`<a:blip>` element — image reference plus optional per-image effects."""
+
+    # Child tag order follows the OOXML CT_Blip content model.
+    _tag_seq = (
+        "a:alphaBiLevel",
+        "a:alphaCeiling",
+        "a:alphaFloor",
+        "a:alphaInv",
+        "a:alphaMod",
+        "a:alphaModFix",
+        "a:alphaRepl",
+        "a:biLevel",
+        "a:blur",
+        "a:clrChange",
+        "a:clrRepl",
+        "a:duotone",
+        "a:fillOverlay",
+        "a:grayscl",
+        "a:hsl",
+        "a:lum",
+        "a:tint",
+        "a:extLst",
+    )
+    alphaModFix: CT_AlphaModFixEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:alphaModFix", successors=_tag_seq[6:]
+    )
+    biLevel: CT_BiLevelEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:biLevel", successors=_tag_seq[8:]
+    )
+    duotone: CT_DuotoneEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:duotone", successors=_tag_seq[12:]
+    )
+    grayscl: CT_GrayscaleEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:grayscl", successors=_tag_seq[14:]
+    )
+    lum: CT_LuminanceEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:lum", successors=_tag_seq[16:]
+    )
+    del _tag_seq
+
+    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 change_to_kind(self, kind):
+        """Switch the gradient between linear and the non-linear path kinds.
+
+        `kind` is one of ``"linear" | "radial" | "rectangular" | "shape"``.
+        Removes whichever of `<a:lin>`/`<a:path>` is currently present and
+        adds the appropriate child. Returns the newly-added element so
+        callers can set additional attributes on it.
+        """
+        if kind == "linear":
+            self._remove_path()
+            self._remove_lin()
+            return self._add_lin()
+        path_attr = {"radial": "circle", "rectangular": "rect", "shape": "shape"}.get(kind)
+        if path_attr is None:
+            raise ValueError(
+                "gradient kind must be one of 'linear', 'radial', "
+                "'rectangular', 'shape'; got %r" % kind
+            )
+        self._remove_lin()
+        self._remove_path()
+        path_elm = self._add_path()
+        path_elm.path = path_attr
+        return path_elm
+
+    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_AlphaModFixEffect(BaseOxmlElement):
+    """`<a:alphaModFix>` element — scales the alpha (opacity) of an image.
+
+    `amt` is a `ST_PositiveFixedPercentage` where ``1.0`` (100%) means fully
+    opaque and ``0.0`` means fully transparent.  When absent, the element is
+    treated as 100% opaque by PowerPoint.
+    """
+
+    amt = OptionalAttribute("amt", ST_PositiveFixedPercentage, default=1.0)
+
+
+class CT_BiLevelEffect(BaseOxmlElement):
+    """`<a:biLevel>` element — converts the image to a two-color (black/white) palette.
+
+    `thresh` is the luminance threshold: pixels darker than this become black,
+    brighter ones become white.  ``0.5`` (50%) approximates PowerPoint's "Washout" preset.
+
+    `thresh` is **required** by ``CT_BiLevelEffect`` in ISO/IEC 29500. It must be
+    a ``RequiredAttribute``: as an ``OptionalAttribute`` with ``default=0.5``,
+    assigning the (common) value ``0.5`` made the serializer omit the attribute,
+    producing a schema-invalid ``<a:biLevel/>`` that PowerPoint repairs.
+    """
+
+    thresh = RequiredAttribute("thresh", ST_PositiveFixedPercentage)
+
+
+_DUOTONE_COLOR_CHOICES = (
+    Choice("a:scrgbClr"),
+    Choice("a:srgbClr"),
+    Choice("a:hslClr"),
+    Choice("a:sysClr"),
+    Choice("a:schemeClr"),
+    Choice("a:prstClr"),
+)
+
+
+class CT_DuotoneEffect(BaseOxmlElement):
+    """`<a:duotone>` element — maps the image to two-color tone.
+
+    Contains exactly two color-choice child elements (dark tone and light tone).
+    """
+
+
+class CT_GrayscaleEffect(BaseOxmlElement):
+    """`<a:grayscl>` element — converts the image to grayscale.  No attributes."""
+
+
+class CT_LuminanceEffect(BaseOxmlElement):
+    """`<a:lum>` element — adjusts the brightness and contrast of an image.
+
+    Both `bright` and `contrast` are `ST_Percentage` floats in the range
+    ``[-1.0, 1.0]`` where ``0.0`` means no change.
+    """
+
+    bright = OptionalAttribute("bright", ST_FixedPercentage, default=0.0)
+    contrast = OptionalAttribute("contrast", ST_FixedPercentage, 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=(),
+    )

pptx2/oxml/dml/line.py

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

pptx2/oxml/dml/three_d.py

@@ -0,0 +1,110 @@
+"""lxml custom element classes for DrawingML 3-D shape elements."""
+
+from __future__ import annotations
+
+from pptx2.enum.dml import BevelPreset, PresetMaterial
+from pptx2.oxml.simpletypes import ST_PositiveCoordinate, XsdString
+from pptx2.oxml.xmlchemy import (
+    BaseOxmlElement,
+    Choice,
+    OptionalAttribute,
+    RequiredAttribute,
+    ZeroOrOne,
+    ZeroOrOneChoice,
+)
+
+_COLOR_CHOICES = (
+    Choice("a:scrgbClr"),
+    Choice("a:srgbClr"),
+    Choice("a:hslClr"),
+    Choice("a:sysClr"),
+    Choice("a:schemeClr"),
+    Choice("a:prstClr"),
+)
+
+
+class CT_Bevel(BaseOxmlElement):
+    """`<a:bevelT>` / `<a:bevelB>` element — describes a top or bottom bevel on a 3-D shape.
+
+    The ``prst`` attribute selects from a set of preset bevel profiles.  ``w`` and ``h`` control
+    the bevel width and height in EMU.
+    """
+
+    w = OptionalAttribute("w", ST_PositiveCoordinate)
+    h = OptionalAttribute("h", ST_PositiveCoordinate)
+    prst = OptionalAttribute("prst", BevelPreset)
+
+
+class CT_Shape3D(BaseOxmlElement):
+    """`<a:sp3d>` element — describes 3-D properties for a single shape.
+
+    Contains optional top and bottom bevel elements, extrusion and contour colour children,
+    and several sizing / material attributes.
+    """
+
+    _tag_seq = (
+        "a:bevelT",
+        "a:bevelB",
+        "a:extrusionClr",
+        "a:contourClr",
+        "a:extLst",
+    )
+    bevelT = ZeroOrOne("a:bevelT", successors=_tag_seq[1:])
+    bevelB = ZeroOrOne("a:bevelB", successors=_tag_seq[2:])
+    extrusionClr = ZeroOrOne("a:extrusionClr", successors=_tag_seq[3:])
+    contourClr = ZeroOrOne("a:contourClr", successors=_tag_seq[4:])
+    del _tag_seq
+
+    extrusionH = OptionalAttribute("extrusionH", ST_PositiveCoordinate)
+    contourW = OptionalAttribute("contourW", ST_PositiveCoordinate)
+    prstMaterial = OptionalAttribute("prstMaterial", PresetMaterial)
+
+
+class CT_ExtrusionColor(BaseOxmlElement):
+    """`<a:extrusionClr>` element — colour of the 3-D extrusion."""
+
+    eg_colorChoice = ZeroOrOneChoice(_COLOR_CHOICES, successors=())
+
+
+class CT_ContourColor(BaseOxmlElement):
+    """`<a:contourClr>` element — colour of the 3-D contour (edge)."""
+
+    eg_colorChoice = ZeroOrOneChoice(_COLOR_CHOICES, successors=())
+
+
+class CT_Camera(BaseOxmlElement):
+    """`<a:camera>` element — the scene camera within `<a:scene3d>`.
+
+    The ``prst`` attribute (preset camera type, e.g. ``orthographicFront``) is ``use="required"``
+    in the OOXML schema (``CT_Camera``), so it is modelled as a ``RequiredAttribute`` — a plain
+    string so callers / defaults can write any preset name without an exhaustive enum.
+    """
+
+    prst = RequiredAttribute("prst", XsdString)
+
+
+class CT_LightRig(BaseOxmlElement):
+    """`<a:lightRig>` element — the scene light rig within `<a:scene3d>`.
+
+    Both ``rig`` (e.g. ``threePt``) and ``dir`` (e.g. ``t``) are ``use="required"`` in the OOXML
+    schema (``CT_LightRig``), so they are modelled as ``RequiredAttribute`` for the same reason as
+    :class:`CT_Camera`.
+    """
+
+    rig = RequiredAttribute("rig", XsdString)
+    dir = RequiredAttribute("dir", XsdString)
+
+
+class CT_Scene3D(BaseOxmlElement):
+    """`<a:scene3d>` element — scene-level 3-D rendering settings.
+
+    Contains a required ``<a:camera>`` and ``<a:lightRig>`` child (in that order).  PowerPoint
+    rejects a deck whose ``<a:scene3d>`` is empty while a sibling ``<a:sp3d>`` is present, so the
+    creating path (:meth:`pptx2.dml.three_d.ThreeDFormat._get_or_add_sp3d`) always populates
+    both children with safe defaults.
+    """
+
+    _tag_seq = ("a:camera", "a:lightRig", "a:extLst")
+    camera = ZeroOrOne("a:camera", successors=_tag_seq[1:])
+    lightRig = ZeroOrOne("a:lightRig", successors=_tag_seq[2:])
+    del _tag_seq

pptx2/oxml/ns.py

@@ -0,0 +1,135 @@
+"""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",
+    "a14": "http://schemas.microsoft.com/office/drawing/2010/main",
+    "asvg": "http://schemas.microsoft.com/office/drawing/2016/SVG/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/",
+    "dgm": "http://schemas.openxmlformats.org/drawingml/2006/diagram",
+    "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",
+    "p14": "http://schemas.microsoft.com/office/powerpoint/2010/main",
+    "p15": "http://schemas.microsoft.com/office/powerpoint/2012/main",
+    "p159": "http://schemas.microsoft.com/office/powerpoint/2015/09/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