python-pptx2 2.13.0__py3-none-any.whl

pptx2/oxml/coreprops.py

@@ -0,0 +1,288 @@
+"""lxml custom element classes for core properties-related XML elements."""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+from typing import Callable, cast
+
+from lxml.etree import _Element  # pyright: ignore[reportPrivateUsage]
+
+from pptx2.oxml import parse_xml
+from pptx2.oxml.ns import nsdecls, qn
+from pptx2.oxml.xmlchemy import BaseOxmlElement, ZeroOrOne
+
+
+class CT_CoreProperties(BaseOxmlElement):
+    """`cp:coreProperties` element.
+
+    The root element of the Core Properties part stored as `/docProps/core.xml`. Implements many
+    of the Dublin Core document metadata elements. String elements resolve to an empty string ('')
+    if the element is not present in the XML. String elements are limited in length to 255 unicode
+    characters.
+    """
+
+    get_or_add_revision: Callable[[], _Element]
+
+    category = ZeroOrOne("cp:category", successors=())
+    contentStatus = ZeroOrOne("cp:contentStatus", successors=())
+    created = ZeroOrOne("dcterms:created", successors=())
+    creator = ZeroOrOne("dc:creator", successors=())
+    description = ZeroOrOne("dc:description", successors=())
+    identifier = ZeroOrOne("dc:identifier", successors=())
+    keywords = ZeroOrOne("cp:keywords", successors=())
+    language = ZeroOrOne("dc:language", successors=())
+    lastModifiedBy = ZeroOrOne("cp:lastModifiedBy", successors=())
+    lastPrinted = ZeroOrOne("cp:lastPrinted", successors=())
+    modified = ZeroOrOne("dcterms:modified", successors=())
+    revision: _Element | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "cp:revision", successors=()
+    )
+    subject = ZeroOrOne("dc:subject", successors=())
+    title = ZeroOrOne("dc:title", successors=())
+    version = ZeroOrOne("cp:version", successors=())
+
+    _coreProperties_tmpl = "<cp:coreProperties %s/>\n" % nsdecls("cp", "dc", "dcterms")
+
+    @staticmethod
+    def new_coreProperties() -> CT_CoreProperties:
+        """Return a new `cp:coreProperties` element"""
+        return cast(CT_CoreProperties, parse_xml(CT_CoreProperties._coreProperties_tmpl))
+
+    @property
+    def author_text(self) -> str:
+        return self._text_of_element("creator")
+
+    @author_text.setter
+    def author_text(self, value: str):
+        self._set_element_text("creator", value)
+
+    @property
+    def category_text(self) -> str:
+        return self._text_of_element("category")
+
+    @category_text.setter
+    def category_text(self, value: str):
+        self._set_element_text("category", value)
+
+    @property
+    def comments_text(self) -> str:
+        return self._text_of_element("description")
+
+    @comments_text.setter
+    def comments_text(self, value: str):
+        self._set_element_text("description", value)
+
+    @property
+    def contentStatus_text(self) -> str:
+        return self._text_of_element("contentStatus")
+
+    @contentStatus_text.setter
+    def contentStatus_text(self, value: str):
+        self._set_element_text("contentStatus", value)
+
+    @property
+    def created_datetime(self):
+        return self._datetime_of_element("created")
+
+    @created_datetime.setter
+    def created_datetime(self, value: dt.datetime):
+        self._set_element_datetime("created", value)
+
+    @property
+    def identifier_text(self) -> str:
+        return self._text_of_element("identifier")
+
+    @identifier_text.setter
+    def identifier_text(self, value: str):
+        self._set_element_text("identifier", value)
+
+    @property
+    def keywords_text(self) -> str:
+        return self._text_of_element("keywords")
+
+    @keywords_text.setter
+    def keywords_text(self, value: str):
+        self._set_element_text("keywords", value)
+
+    @property
+    def language_text(self) -> str:
+        return self._text_of_element("language")
+
+    @language_text.setter
+    def language_text(self, value: str):
+        self._set_element_text("language", value)
+
+    @property
+    def lastModifiedBy_text(self) -> str:
+        return self._text_of_element("lastModifiedBy")
+
+    @lastModifiedBy_text.setter
+    def lastModifiedBy_text(self, value: str):
+        self._set_element_text("lastModifiedBy", value)
+
+    @property
+    def lastPrinted_datetime(self):
+        return self._datetime_of_element("lastPrinted")
+
+    @lastPrinted_datetime.setter
+    def lastPrinted_datetime(self, value: dt.datetime):
+        self._set_element_datetime("lastPrinted", value)
+
+    @property
+    def modified_datetime(self):
+        return self._datetime_of_element("modified")
+
+    @modified_datetime.setter
+    def modified_datetime(self, value: dt.datetime):
+        self._set_element_datetime("modified", value)
+
+    @property
+    def revision_number(self) -> int:
+        """Integer value of revision property."""
+        revision = self.revision
+        if revision is None:
+            return 0
+        revision_str = revision.text
+        if revision_str is None:
+            return 0
+        try:
+            revision = int(revision_str)
+        except ValueError:
+            # -- non-integer revision strings also resolve to 0 --
+            return 0
+        # -- as do negative integers --
+        if revision < 0:
+            return 0
+        return revision
+
+    @revision_number.setter
+    def revision_number(self, value: int):
+        """Set revision property to string value of integer `value`."""
+        if not isinstance(value, int) or value < 1:  # pyright: ignore[reportUnnecessaryIsInstance]
+            tmpl = "revision property requires positive int, got '%s'"
+            raise ValueError(tmpl % value)
+        revision = self.get_or_add_revision()
+        revision.text = str(value)
+
+    @property
+    def subject_text(self) -> str:
+        return self._text_of_element("subject")
+
+    @subject_text.setter
+    def subject_text(self, value: str):
+        self._set_element_text("subject", value)
+
+    @property
+    def title_text(self) -> str:
+        return self._text_of_element("title")
+
+    @title_text.setter
+    def title_text(self, value: str):
+        self._set_element_text("title", value)
+
+    @property
+    def version_text(self) -> str:
+        return self._text_of_element("version")
+
+    @version_text.setter
+    def version_text(self, value: str):
+        self._set_element_text("version", value)
+
+    def _datetime_of_element(self, property_name: str) -> dt.datetime | None:
+        element = cast("_Element | None", getattr(self, property_name))
+        if element is None:
+            return None
+        datetime_str = element.text
+        if datetime_str is None:
+            return None
+        try:
+            return self._parse_W3CDTF_to_datetime(datetime_str)
+        except ValueError:
+            # invalid datetime strings are ignored
+            return None
+
+    def _get_or_add(self, prop_name: str):
+        """Return element returned by 'get_or_add_' method for `prop_name`."""
+        get_or_add_method_name = "get_or_add_%s" % prop_name
+        get_or_add_method = getattr(self, get_or_add_method_name)
+        element = get_or_add_method()
+        return element
+
+    @classmethod
+    def _offset_dt(cls, datetime: dt.datetime, offset_str: str):
+        """Return |datetime| instance offset from `datetime` by offset specified in `offset_str`.
+
+        `offset_str` is a string like `'-07:00'`.
+        """
+        match = cls._offset_pattern.match(offset_str)
+        if match is None:
+            raise ValueError(f"{repr(offset_str)} is not a valid offset string")
+        sign, hours_str, minutes_str = match.groups()
+        sign_factor = -1 if sign == "+" else 1
+        hours = int(hours_str) * sign_factor
+        minutes = int(minutes_str) * sign_factor
+        td = dt.timedelta(hours=hours, minutes=minutes)
+        return datetime + td
+
+    _offset_pattern = re.compile(r"([+-])(\d\d):(\d\d)")
+
+    @classmethod
+    def _parse_W3CDTF_to_datetime(cls, w3cdtf_str: str) -> dt.datetime:
+        # valid W3CDTF date cases:
+        # yyyy e.g. '2003'
+        # yyyy-mm e.g. '2003-12'
+        # yyyy-mm-dd e.g. '2003-12-31'
+        # UTC timezone e.g. '2003-12-31T10:14:55Z'
+        # numeric timezone e.g. '2003-12-31T10:14:55-08:00'
+        templates = ("%Y-%m-%dT%H:%M:%S", "%Y-%m-%d", "%Y-%m", "%Y")
+        # strptime isn't smart enough to parse literal timezone offsets like
+        # '-07:30', so we have to do it ourselves
+        parseable_part = w3cdtf_str[:19]
+        offset_str = w3cdtf_str[19:]
+        timestamp = None
+        for tmpl in templates:
+            try:
+                timestamp = dt.datetime.strptime(parseable_part, tmpl)
+            except ValueError:
+                continue
+        if timestamp is None:
+            tmpl = "could not parse W3CDTF datetime string '%s'"
+            raise ValueError(tmpl % w3cdtf_str)
+        if len(offset_str) == 6:
+            return cls._offset_dt(timestamp, offset_str)
+        return timestamp
+
+    def _set_element_datetime(self, prop_name: str, value: dt.datetime) -> None:
+        """Set date/time value of child element having `prop_name` to `value`."""
+        if not isinstance(value, dt.datetime):  # pyright: ignore[reportUnnecessaryIsInstance]
+            tmpl = "property requires <type 'datetime.datetime'> object, got %s"
+            raise ValueError(tmpl % type(value))
+        element = self._get_or_add(prop_name)
+        dt_str = value.strftime("%Y-%m-%dT%H:%M:%SZ")
+        element.text = dt_str
+        if prop_name in ("created", "modified"):
+            # These two require an explicit 'xsi:type="dcterms:W3CDTF"'
+            # attribute. The first and last line are a hack required to add
+            # the xsi namespace to the root element rather than each child
+            # element in which it is referenced
+            self.set(qn("xsi:foo"), "bar")
+            element.set(qn("xsi:type"), "dcterms:W3CDTF")
+            del self.attrib[qn("xsi:foo")]
+
+    def _set_element_text(self, prop_name: str, value: str) -> None:
+        """Set string value of `name` property to `value`."""
+        value = str(value)
+        if len(value) > 255:
+            tmpl = "exceeded 255 char limit for property, got:\n\n'%s'"
+            raise ValueError(tmpl % value)
+        element = self._get_or_add(prop_name)
+        element.text = value
+
+    def _text_of_element(self, property_name: str) -> str:
+        element = getattr(self, property_name)
+        if element is None:
+            return ""
+        if element.text is None:
+            return ""
+        return element.text

pptx2/oxml/dml/color.py

@@ -0,0 +1,135 @@
+"""lxml custom element classes for DrawingML-related XML elements."""
+
+from __future__ import annotations
+
+from pptx2.enum.dml import MSO_THEME_COLOR
+from pptx2.oxml.simpletypes import ST_HexColorRGB, ST_Percentage, ST_PositiveFixedPercentage
+from pptx2.oxml.xmlchemy import (
+    BaseOxmlElement,
+    Choice,
+    RequiredAttribute,
+    ZeroOrOne,
+    ZeroOrOneChoice,
+)
+
+
+class _BaseColorElement(BaseOxmlElement):
+    """
+    Base class for <a:srgbClr> and <a:schemeClr> elements.
+    """
+
+    lumMod = ZeroOrOne("a:lumMod")
+    lumOff = ZeroOrOne("a:lumOff")
+    alpha = ZeroOrOne("a:alpha")
+
+    def add_lumMod(self, value):
+        """
+        Return a newly added <a:lumMod> child element.
+        """
+        lumMod = self._add_lumMod()
+        lumMod.val = value
+        return lumMod
+
+    def add_lumOff(self, value):
+        """
+        Return a newly added <a:lumOff> child element.
+        """
+        lumOff = self._add_lumOff()
+        lumOff.val = value
+        return lumOff
+
+    def add_alpha(self, value):
+        """Return a newly added `<a:alpha>` child element with `val` attribute set to `value`.
+
+        `value` is a float in the range [0.0, 1.0] where 1.0 is fully opaque.
+        """
+        alpha = self._add_alpha()
+        alpha.val = value
+        return alpha
+
+    def clear_alpha(self):
+        """Return self after removing any `<a:alpha>` child element."""
+        self._remove_alpha()
+        return self
+
+    def clear_lum(self):
+        """
+        Return self after removing any <a:lumMod> and <a:lumOff> child
+        elements.
+        """
+        self._remove_lumMod()
+        self._remove_lumOff()
+        return self
+
+
+class CT_Color(BaseOxmlElement):
+    """Custom element class for `a:fgClr`, `a:bgClr` and perhaps others."""
+
+    eg_colorChoice = ZeroOrOneChoice(
+        (
+            Choice("a:scrgbClr"),
+            Choice("a:srgbClr"),
+            Choice("a:hslClr"),
+            Choice("a:sysClr"),
+            Choice("a:schemeClr"),
+            Choice("a:prstClr"),
+        ),
+        successors=(),
+    )
+
+
+class CT_HslColor(_BaseColorElement):
+    """
+    Custom element class for <a:hslClr> element.
+    """
+
+
+class CT_Percentage(BaseOxmlElement):
+    """
+    Custom element class for <a:lumMod> and <a:lumOff> elements.
+    """
+
+    val = RequiredAttribute("val", ST_Percentage)
+
+
+class CT_PositiveFixedPercentage(BaseOxmlElement):
+    """Custom element class for `<a:alpha>` element.
+
+    `val` is a float in the closed interval [0.0, 1.0] where 1.0 is fully opaque.
+    """
+
+    val = RequiredAttribute("val", ST_PositiveFixedPercentage)
+
+
+class CT_PresetColor(_BaseColorElement):
+    """
+    Custom element class for <a:prstClr> element.
+    """
+
+
+class CT_SchemeColor(_BaseColorElement):
+    """
+    Custom element class for <a:schemeClr> element.
+    """
+
+    val = RequiredAttribute("val", MSO_THEME_COLOR)
+
+
+class CT_ScRgbColor(_BaseColorElement):
+    """
+    Custom element class for <a:scrgbClr> element.
+    """
+
+
+class CT_SRgbColor(_BaseColorElement):
+    """
+    Custom element class for <a:srgbClr> element.
+    """
+
+    val = RequiredAttribute("val", ST_HexColorRGB)
+
+
+class CT_SystemColor(_BaseColorElement):
+    """
+    Custom element class for <a:sysClr> element.
+    """

pptx2/oxml/dml/effect.py

@@ -0,0 +1,213 @@
+"""lxml custom element classes for DrawingML visual-effect elements."""
+
+from __future__ import annotations
+
+from pptx2.enum.dml import MSO_PRESET_SHADOW
+from pptx2.oxml.ns import qn
+from pptx2.oxml.simpletypes import (
+    ST_FixedAngle,
+    ST_Percentage,
+    ST_PositiveCoordinate,
+    ST_PositiveFixedAngle,
+    ST_PositiveFixedPercentage,
+    XsdBoolean,
+    XsdStringEnumeration,
+)
+from pptx2.oxml.xmlchemy import (
+    BaseOxmlElement,
+    Choice,
+    OptionalAttribute,
+    RequiredAttribute,
+    ZeroOrOne,
+    ZeroOrOneChoice,
+)
+
+
+class ST_RectAlignment(XsdStringEnumeration):
+    """Valid values for `a:reflection@algn`.
+
+    The nine-point alignment used by the reflection effect to anchor its
+    bounding box relative to the source shape.
+    """
+
+    TL = "tl"
+    T = "t"
+    TR = "tr"
+    L = "l"
+    CTR = "ctr"
+    R = "r"
+    BL = "bl"
+    B = "b"
+    BR = "br"
+
+    _members = (TL, T, TR, L, CTR, R, BL, B, BR)
+
+
+_COLOR_TAGS = frozenset(
+    qn(t)
+    for t in (
+        "a:scrgbClr",
+        "a:srgbClr",
+        "a:hslClr",
+        "a:sysClr",
+        "a:schemeClr",
+        "a:prstClr",
+    )
+)
+
+_COLOR_CHOICES = (
+    Choice("a:scrgbClr"),
+    Choice("a:srgbClr"),
+    Choice("a:hslClr"),
+    Choice("a:sysClr"),
+    Choice("a:schemeClr"),
+    Choice("a:prstClr"),
+)
+
+
+class CT_EffectList(BaseOxmlElement):
+    """`<a:effectLst>` custom element class — container for shape visual effects."""
+
+    _tag_seq = (
+        "a:blur",
+        "a:fillOverlay",
+        "a:glow",
+        "a:innerShdw",
+        "a:outerShdw",
+        "a:prstShdw",
+        "a:reflection",
+        "a:softEdge",
+    )
+    blur: CT_BlurEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:blur", successors=_tag_seq[1:]
+    )
+    glow: CT_GlowEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:glow", successors=_tag_seq[3:]
+    )
+    innerShdw: CT_InnerShadowEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:innerShdw", successors=_tag_seq[4:]
+    )
+    outerShdw: CT_OuterShadowEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:outerShdw", successors=_tag_seq[5:]
+    )
+    prstShdw: CT_PresetShadowEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:prstShdw", successors=_tag_seq[6:]
+    )
+    reflection: CT_ReflectionEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:reflection", successors=_tag_seq[7:]
+    )
+    softEdge: CT_SoftEdgesEffect | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:softEdge", successors=_tag_seq[8:]
+    )
+    del _tag_seq
+
+
+class CT_GlowEffect(BaseOxmlElement):
+    """`<a:glow>` custom element class.
+
+    Specifies a glow effect around the shape edges.  `rad` is the glow radius in EMU.
+    """
+
+    eg_colorChoice = ZeroOrOneChoice(_COLOR_CHOICES, successors=())
+    rad = OptionalAttribute("rad", ST_PositiveCoordinate)
+
+
+class CT_OuterShadowEffect(BaseOxmlElement):
+    """`<a:outerShdw>` custom element class.
+
+    Outer shadow effect. All read attributes return None when the attribute is
+    absent; writes are non-mutating only when the value is explicitly None.
+    """
+
+    eg_colorChoice = ZeroOrOneChoice(_COLOR_CHOICES, successors=())
+    blurRad = OptionalAttribute("blurRad", ST_PositiveCoordinate)
+    dist = OptionalAttribute("dist", ST_PositiveCoordinate)
+    dir = OptionalAttribute("dir", ST_PositiveFixedAngle)
+    rotWithShape = OptionalAttribute("rotWithShape", XsdBoolean)
+
+
+class CT_SoftEdgesEffect(BaseOxmlElement):
+    """`<a:softEdge>` custom element class.
+
+    Specifies a soft-edge blur at the shape perimeter.  `rad` is the blur radius in EMU.
+    """
+
+    rad = OptionalAttribute("rad", ST_PositiveCoordinate)
+
+
+class CT_BlurEffect(BaseOxmlElement):
+    """`<a:blur>` custom element class.
+
+    Applies a Gaussian blur to the entire shape.  `rad` is the blur radius in
+    EMU; `grow` controls whether the bounding box expands to accommodate the
+    blur (default True per the OOXML schema).
+    """
+
+    rad = OptionalAttribute("rad", ST_PositiveCoordinate)
+    grow = OptionalAttribute("grow", XsdBoolean)
+
+
+class CT_InnerShadowEffect(BaseOxmlElement):
+    """`<a:innerShdw>` custom element class.
+
+    Inner shadow effect.  Mirrors the attribute set of the outer-shadow
+    element minus the outer-only `rotWithShape` flag.  All read attributes
+    return None when the underlying attribute is absent.
+    """
+
+    eg_colorChoice = ZeroOrOneChoice(_COLOR_CHOICES, successors=())
+    blurRad = OptionalAttribute("blurRad", ST_PositiveCoordinate)
+    dist = OptionalAttribute("dist", ST_PositiveCoordinate)
+    dir = OptionalAttribute("dir", ST_PositiveFixedAngle)
+
+
+class CT_PresetShadowEffect(BaseOxmlElement):
+    """`<a:prstShdw>` custom element class.
+
+    Preset shadow effect.  The ``prst`` attribute (one of ``shdw1`` ..
+    ``shdw20``) is *required* by the OOXML schema, so it is declared as a
+    ``RequiredAttribute`` — omitting it (or writing the element without it)
+    makes PowerPoint flag the deck as broken.  ``dist`` / ``dir`` are optional
+    and a single ``EG_ColorChoice`` child is required.
+    """
+
+    eg_colorChoice = ZeroOrOneChoice(_COLOR_CHOICES, successors=())
+    prst = RequiredAttribute("prst", MSO_PRESET_SHADOW)
+    dist = OptionalAttribute("dist", ST_PositiveCoordinate)
+    dir = OptionalAttribute("dir", ST_PositiveFixedAngle)
+
+
+class CT_ReflectionEffect(BaseOxmlElement):
+    """`<a:reflection>` custom element class.
+
+    Reflection effect placed beneath the shape.  Exposes the attributes most
+    users actually want — blur radius, offset distance, direction, start/end
+    alpha, and alignment.  Attributes are optional; reads return None when
+    absent so theme inheritance is preserved.
+    """
+
+    blurRad = OptionalAttribute("blurRad", ST_PositiveCoordinate)
+    stA = OptionalAttribute("stA", ST_PositiveFixedPercentage)
+    stPos = OptionalAttribute("stPos", ST_PositiveFixedPercentage)
+    endA = OptionalAttribute("endA", ST_PositiveFixedPercentage)
+    endPos = OptionalAttribute("endPos", ST_PositiveFixedPercentage)
+    dist = OptionalAttribute("dist", ST_PositiveCoordinate)
+    dir = OptionalAttribute("dir", ST_PositiveFixedAngle)
+    fadeDir = OptionalAttribute("fadeDir", ST_PositiveFixedAngle)
+    sx = OptionalAttribute("sx", ST_Percentage)
+    sy = OptionalAttribute("sy", ST_Percentage)
+    kx = OptionalAttribute("kx", ST_FixedAngle)
+    ky = OptionalAttribute("ky", ST_FixedAngle)
+    algn = OptionalAttribute("algn", ST_RectAlignment)
+    rotWithShape = OptionalAttribute("rotWithShape", XsdBoolean)
+
+
+# `<a:prstShdw>` is a post-fork addition; register its custom element class here
+# (rather than in `pptx2.oxml.__init__`) so the lxml parser maps the tag to
+# `CT_PresetShadowEffect` and the `CT_EffectList.prstShdw` accessor returns a
+# typed element with a working `prst` attribute.  `register_element_cls` is
+# defined before this module is imported by `pptx2.oxml.__init__`, so this
+# is safe despite the partial-import ordering.
+from pptx2.oxml import register_element_cls  # noqa: E402
+
+register_element_cls("a:prstShdw", CT_PresetShadowEffect)