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

pptx/oxml/chart/shared.py

@@ -0,0 +1,219 @@
+"""Shared oxml objects for charts."""
+
+from __future__ import annotations
+
+from pptx.oxml import parse_xml
+from pptx.oxml.ns import nsdecls
+from pptx.oxml.simpletypes import (
+    ST_LayoutMode,
+    XsdBoolean,
+    XsdDouble,
+    XsdString,
+    XsdUnsignedInt,
+)
+from pptx.oxml.xmlchemy import (
+    BaseOxmlElement,
+    OptionalAttribute,
+    RequiredAttribute,
+    ZeroOrOne,
+)
+
+
+class CT_Boolean(BaseOxmlElement):
+    """
+    Common complex type used for elements having a True/False value.
+    """
+
+    val = OptionalAttribute("val", XsdBoolean, default=True)
+
+
+class CT_Boolean_Explicit(BaseOxmlElement):
+    """Always spells out the `val` attribute, e.g. `val=1`.
+
+    At least one boolean element is improperly interpreted by one or more
+    versions of PowerPoint. The `c:overlay` element is interpreted as |False|
+    when no `val` attribute is present, contrary to the behavior described in
+    the schema. A remedy for this is to interpret a missing `val` attribute
+    as |True| (consistent with the spec), but always write the attribute
+    whenever there is occasion for changing the element.
+    """
+
+    _val = OptionalAttribute("val", XsdBoolean, default=True)
+
+    @property
+    def val(self):
+        return self._val
+
+    @val.setter
+    def val(self, value):
+        val_str = "1" if bool(value) is True else "0"
+        self.set("val", val_str)
+
+
+class CT_Double(BaseOxmlElement):
+    """
+    Used for floating point values.
+    """
+
+    val = RequiredAttribute("val", XsdDouble)
+
+
+class CT_Layout(BaseOxmlElement):
+    """
+    ``<c:layout>`` custom element class
+    """
+
+    manualLayout = ZeroOrOne("c:manualLayout", successors=("c:extLst",))
+
+    @property
+    def horz_offset(self):
+        """
+        The float value in ./c:manualLayout/c:x when
+        c:layout/c:manualLayout/c:xMode@val == "factor". 0.0 if that XPath
+        expression finds no match.
+        """
+        manualLayout = self.manualLayout
+        if manualLayout is None:
+            return 0.0
+        return manualLayout.horz_offset
+
+    @horz_offset.setter
+    def horz_offset(self, offset):
+        """
+        Set the value of ./c:manualLayout/c:x@val to *offset* and
+        ./c:manualLayout/c:xMode@val to "factor". Remove ./c:manualLayout if
+        *offset* == 0.
+        """
+        if offset == 0.0:
+            self._remove_manualLayout()
+            return
+        manualLayout = self.get_or_add_manualLayout()
+        manualLayout.horz_offset = offset
+
+
+class CT_LayoutMode(BaseOxmlElement):
+    """
+    Used for ``<c:xMode>``, ``<c:yMode>``, ``<c:wMode>``, and ``<c:hMode>``
+    child elements of CT_ManualLayout.
+    """
+
+    val = OptionalAttribute("val", ST_LayoutMode, default=ST_LayoutMode.FACTOR)
+
+
+class CT_ManualLayout(BaseOxmlElement):
+    """
+    ``<c:manualLayout>`` custom element class
+    """
+
+    _tag_seq = (
+        "c:layoutTarget",
+        "c:xMode",
+        "c:yMode",
+        "c:wMode",
+        "c:hMode",
+        "c:x",
+        "c:y",
+        "c:w",
+        "c:h",
+        "c:extLst",
+    )
+    xMode = ZeroOrOne("c:xMode", successors=_tag_seq[2:])
+    x = ZeroOrOne("c:x", successors=_tag_seq[6:])
+    del _tag_seq
+
+    @property
+    def horz_offset(self):
+        """
+        The float value in ./c:x@val when ./c:xMode@val == "factor". 0.0 when
+        ./c:x is not present or ./c:xMode@val != "factor".
+        """
+        x, xMode = self.x, self.xMode
+        if x is None or xMode is None or xMode.val != ST_LayoutMode.FACTOR:
+            return 0.0
+        return x.val
+
+    @horz_offset.setter
+    def horz_offset(self, offset):
+        """
+        Set the value of ./c:x@val to *offset* and ./c:xMode@val to "factor".
+        """
+        self.get_or_add_xMode().val = ST_LayoutMode.FACTOR
+        self.get_or_add_x().val = offset
+
+
+class CT_NumFmt(BaseOxmlElement):
+    """
+    ``<c:numFmt>`` element specifying the formatting for number labels on a
+    tick mark or data point.
+    """
+
+    formatCode = RequiredAttribute("formatCode", XsdString)
+    sourceLinked = OptionalAttribute("sourceLinked", XsdBoolean)
+
+
+class CT_Title(BaseOxmlElement):
+    """`c:title` custom element class."""
+
+    _tag_seq = ("c:tx", "c:layout", "c:overlay", "c:spPr", "c:txPr", "c:extLst")
+    tx = ZeroOrOne("c:tx", successors=_tag_seq[1:])
+    spPr = ZeroOrOne("c:spPr", successors=_tag_seq[4:])
+    del _tag_seq
+
+    def get_or_add_tx_rich(self):
+        """Return `c:tx/c:rich`, newly created if not present.
+
+        Return the `c:rich` grandchild at `c:tx/c:rich`. Both the `c:tx` and
+        `c:rich` elements are created if not already present. Any
+        `c:tx/c:strRef` element is removed. (Such an element would contain
+        a cell reference for the axis title text in the chart's Excel
+        worksheet.)
+        """
+        tx = self.get_or_add_tx()
+        tx._remove_strRef()
+        return tx.get_or_add_rich()
+
+    @property
+    def tx_rich(self):
+        """Return `c:tx/c:rich` or |None| if not present."""
+        richs = self.xpath("c:tx/c:rich")
+        if not richs:
+            return None
+        return richs[0]
+
+    @staticmethod
+    def new_title():
+        """Return "loose" `c:title` element containing default children."""
+        return parse_xml(
+            "<c:title %s>" "  <c:layout/>" '  <c:overlay val="0"/>' "</c:title>" % nsdecls("c")
+        )
+
+
+class CT_Tx(BaseOxmlElement):
+    """
+    ``<c:tx>`` element containing the text for a label on a data point or
+    other chart item.
+    """
+
+    strRef = ZeroOrOne("c:strRef")
+    rich = ZeroOrOne("c:rich")
+
+    def _new_rich(self):
+        return parse_xml(
+            "<c:rich %s>"
+            "  <a:bodyPr/>"
+            "  <a:lstStyle/>"
+            "  <a:p>"
+            "    <a:pPr>"
+            "      <a:defRPr/>"
+            "    </a:pPr>"
+            "  </a:p>"
+            "</c:rich>" % nsdecls("c", "a")
+        )
+
+
+class CT_UnsignedInt(BaseOxmlElement):
+    """
+    ``<c:idx>`` element and others.
+    """
+
+    val = RequiredAttribute("val", XsdUnsignedInt)

pptx/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 pptx.oxml import parse_xml
+from pptx.oxml.ns import nsdecls, qn
+from pptx.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

pptx/oxml/dml/color.py

@@ -0,0 +1,111 @@
+"""lxml custom element classes for DrawingML-related XML elements."""
+
+from __future__ import annotations
+
+from pptx.enum.dml import MSO_THEME_COLOR
+from pptx.oxml.simpletypes import ST_HexColorRGB, ST_Percentage
+from pptx.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")
+
+    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 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_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.
+    """