ps-python-docx 1.3.0__py3-none-any.whl

docx/oxml/__init__.py

@@ -0,0 +1,261 @@
+# ruff: noqa: E402, I001
+
+"""Initializes oxml sub-package.
+
+This including registering custom element classes corresponding to Open XML elements.
+"""
+
+from __future__ import annotations
+
+from docx.oxml.drawing import CT_Drawing
+from docx.oxml.parser import OxmlElement, parse_xml, register_element_cls
+from docx.oxml.shape import (
+    CT_Anchor,
+    CT_Blip,
+    CT_BlipFillProperties,
+    CT_GraphicalObject,
+    CT_GraphicalObjectData,
+    CT_Inline,
+    CT_NonVisualDrawingProps,
+    CT_Picture,
+    CT_PictureNonVisual,
+    CT_Point2D,
+    CT_PositiveSize2D,
+    CT_ShapeProperties,
+    CT_Transform2D,
+)
+from docx.oxml.shared import CT_DecimalNumber, CT_OnOff, CT_String
+from docx.oxml.text.hyperlink import CT_Hyperlink
+from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
+from docx.oxml.text.run import (
+    CT_R,
+    CT_Br,
+    CT_Cr,
+    CT_NoBreakHyphen,
+    CT_PTab,
+    CT_Text,
+)
+
+# -- `OxmlElement` and `parse_xml()` are not used in this module but several downstream
+# -- "extension" packages expect to find them here and there's no compelling reason
+# -- not to republish them here so those keep working.
+__all__ = ["OxmlElement", "parse_xml"]
+
+# ---------------------------------------------------------------------------
+# DrawingML-related elements
+
+register_element_cls("a:blip", CT_Blip)
+register_element_cls("a:ext", CT_PositiveSize2D)
+register_element_cls("a:graphic", CT_GraphicalObject)
+register_element_cls("a:graphicData", CT_GraphicalObjectData)
+register_element_cls("a:off", CT_Point2D)
+register_element_cls("a:xfrm", CT_Transform2D)
+register_element_cls("pic:blipFill", CT_BlipFillProperties)
+register_element_cls("pic:cNvPr", CT_NonVisualDrawingProps)
+register_element_cls("pic:nvPicPr", CT_PictureNonVisual)
+register_element_cls("pic:pic", CT_Picture)
+register_element_cls("pic:spPr", CT_ShapeProperties)
+register_element_cls("w:drawing", CT_Drawing)
+register_element_cls("wp:anchor", CT_Anchor)
+register_element_cls("wp:docPr", CT_NonVisualDrawingProps)
+register_element_cls("wp:extent", CT_PositiveSize2D)
+register_element_cls("wp:inline", CT_Inline)
+
+# ---------------------------------------------------------------------------
+# hyperlink-related elements
+
+register_element_cls("w:hyperlink", CT_Hyperlink)
+
+# ---------------------------------------------------------------------------
+# text-related elements
+
+register_element_cls("w:br", CT_Br)
+register_element_cls("w:cr", CT_Cr)
+register_element_cls("w:lastRenderedPageBreak", CT_LastRenderedPageBreak)
+register_element_cls("w:noBreakHyphen", CT_NoBreakHyphen)
+register_element_cls("w:ptab", CT_PTab)
+register_element_cls("w:r", CT_R)
+register_element_cls("w:t", CT_Text)
+
+# ---------------------------------------------------------------------------
+# header/footer-related mappings
+
+register_element_cls("w:evenAndOddHeaders", CT_OnOff)
+register_element_cls("w:titlePg", CT_OnOff)
+
+# ---------------------------------------------------------------------------
+# other custom element class mappings
+
+from .comments import CT_Comments, CT_Comment
+
+register_element_cls("w:comments", CT_Comments)
+register_element_cls("w:comment", CT_Comment)
+
+from .coreprops import CT_CoreProperties
+
+register_element_cls("cp:coreProperties", CT_CoreProperties)
+
+from .document import CT_Body, CT_Document
+
+register_element_cls("w:body", CT_Body)
+register_element_cls("w:document", CT_Document)
+
+from .numbering import CT_Num, CT_Numbering, CT_NumLvl, CT_NumPr
+
+register_element_cls("w:abstractNumId", CT_DecimalNumber)
+register_element_cls("w:ilvl", CT_DecimalNumber)
+register_element_cls("w:lvlOverride", CT_NumLvl)
+register_element_cls("w:num", CT_Num)
+register_element_cls("w:numId", CT_DecimalNumber)
+register_element_cls("w:numPr", CT_NumPr)
+register_element_cls("w:numbering", CT_Numbering)
+register_element_cls("w:startOverride", CT_DecimalNumber)
+
+from .section import (
+    CT_HdrFtr,
+    CT_HdrFtrRef,
+    CT_PageMar,
+    CT_PageSz,
+    CT_SectPr,
+    CT_SectType,
+)
+
+register_element_cls("w:footerReference", CT_HdrFtrRef)
+register_element_cls("w:ftr", CT_HdrFtr)
+register_element_cls("w:hdr", CT_HdrFtr)
+register_element_cls("w:headerReference", CT_HdrFtrRef)
+register_element_cls("w:pgMar", CT_PageMar)
+register_element_cls("w:pgSz", CT_PageSz)
+register_element_cls("w:sectPr", CT_SectPr)
+register_element_cls("w:type", CT_SectType)
+
+from .settings import CT_Settings
+
+register_element_cls("w:settings", CT_Settings)
+
+from .styles import (
+    CT_DocDefaults,
+    CT_LatentStyles,
+    CT_LsdException,
+    CT_RPrDefault,
+    CT_Style,
+    CT_Styles,
+)
+
+register_element_cls("w:docDefaults", CT_DocDefaults)
+register_element_cls("w:rPrDefault", CT_RPrDefault)
+register_element_cls("w:link", CT_String)
+register_element_cls("w:basedOn", CT_String)
+register_element_cls("w:latentStyles", CT_LatentStyles)
+register_element_cls("w:locked", CT_OnOff)
+register_element_cls("w:lsdException", CT_LsdException)
+register_element_cls("w:name", CT_String)
+register_element_cls("w:next", CT_String)
+register_element_cls("w:qFormat", CT_OnOff)
+register_element_cls("w:semiHidden", CT_OnOff)
+register_element_cls("w:style", CT_Style)
+register_element_cls("w:styles", CT_Styles)
+register_element_cls("w:uiPriority", CT_DecimalNumber)
+register_element_cls("w:unhideWhenUsed", CT_OnOff)
+
+from .table import (
+    CT_Height,
+    CT_Row,
+    CT_Tbl,
+    CT_TblGrid,
+    CT_TblGridCol,
+    CT_TblLayoutType,
+    CT_TblPr,
+    CT_TblPrEx,
+    CT_TblWidth,
+    CT_Tc,
+    CT_TcPr,
+    CT_TrPr,
+    CT_VMerge,
+    CT_VerticalJc,
+)
+
+register_element_cls("w:bidiVisual", CT_OnOff)
+register_element_cls("w:gridAfter", CT_DecimalNumber)
+register_element_cls("w:gridBefore", CT_DecimalNumber)
+register_element_cls("w:gridCol", CT_TblGridCol)
+register_element_cls("w:gridSpan", CT_DecimalNumber)
+register_element_cls("w:tbl", CT_Tbl)
+register_element_cls("w:tblGrid", CT_TblGrid)
+register_element_cls("w:tblLayout", CT_TblLayoutType)
+register_element_cls("w:tblPr", CT_TblPr)
+register_element_cls("w:tblPrEx", CT_TblPrEx)
+register_element_cls("w:tblStyle", CT_String)
+register_element_cls("w:tc", CT_Tc)
+register_element_cls("w:tcPr", CT_TcPr)
+register_element_cls("w:tcW", CT_TblWidth)
+register_element_cls("w:tr", CT_Row)
+register_element_cls("w:trHeight", CT_Height)
+register_element_cls("w:trPr", CT_TrPr)
+register_element_cls("w:vAlign", CT_VerticalJc)
+register_element_cls("w:vMerge", CT_VMerge)
+
+from .text.font import (
+    CT_Color,
+    CT_Fonts,
+    CT_Highlight,
+    CT_HpsMeasure,
+    CT_RPr,
+    CT_Underline,
+    CT_VerticalAlignRun,
+)
+
+register_element_cls("w:b", CT_OnOff)
+register_element_cls("w:bCs", CT_OnOff)
+register_element_cls("w:caps", CT_OnOff)
+register_element_cls("w:color", CT_Color)
+register_element_cls("w:cs", CT_OnOff)
+register_element_cls("w:dstrike", CT_OnOff)
+register_element_cls("w:emboss", CT_OnOff)
+register_element_cls("w:highlight", CT_Highlight)
+register_element_cls("w:i", CT_OnOff)
+register_element_cls("w:iCs", CT_OnOff)
+register_element_cls("w:imprint", CT_OnOff)
+register_element_cls("w:noProof", CT_OnOff)
+register_element_cls("w:oMath", CT_OnOff)
+register_element_cls("w:outline", CT_OnOff)
+register_element_cls("w:rFonts", CT_Fonts)
+register_element_cls("w:rPr", CT_RPr)
+register_element_cls("w:rStyle", CT_String)
+register_element_cls("w:rtl", CT_OnOff)
+register_element_cls("w:shadow", CT_OnOff)
+register_element_cls("w:smallCaps", CT_OnOff)
+register_element_cls("w:snapToGrid", CT_OnOff)
+register_element_cls("w:specVanish", CT_OnOff)
+register_element_cls("w:strike", CT_OnOff)
+register_element_cls("w:sz", CT_HpsMeasure)
+register_element_cls("w:u", CT_Underline)
+register_element_cls("w:vanish", CT_OnOff)
+register_element_cls("w:vertAlign", CT_VerticalAlignRun)
+register_element_cls("w:webHidden", CT_OnOff)
+
+from .text.paragraph import CT_P
+
+register_element_cls("w:p", CT_P)
+
+from .text.parfmt import (
+    CT_Ind,
+    CT_Jc,
+    CT_PPr,
+    CT_Spacing,
+    CT_TabStop,
+    CT_TabStops,
+)
+
+register_element_cls("w:ind", CT_Ind)
+register_element_cls("w:jc", CT_Jc)
+register_element_cls("w:keepLines", CT_OnOff)
+register_element_cls("w:keepNext", CT_OnOff)
+register_element_cls("w:outlineLvl", CT_DecimalNumber)
+register_element_cls("w:pageBreakBefore", CT_OnOff)
+register_element_cls("w:pPr", CT_PPr)
+register_element_cls("w:pStyle", CT_String)
+register_element_cls("w:spacing", CT_Spacing)
+register_element_cls("w:tab", CT_TabStop)
+register_element_cls("w:tabs", CT_TabStops)
+register_element_cls("w:widowControl", CT_OnOff)

docx/oxml/comments.py

@@ -0,0 +1,124 @@
+"""Custom element classes related to document comments."""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import TYPE_CHECKING, Callable, cast
+
+from docx.oxml.ns import nsdecls
+from docx.oxml.parser import parse_xml
+from docx.oxml.simpletypes import ST_DateTime, ST_DecimalNumber, ST_String
+from docx.oxml.xmlchemy import BaseOxmlElement, OptionalAttribute, RequiredAttribute, ZeroOrMore
+
+if TYPE_CHECKING:
+    from docx.oxml.table import CT_Tbl
+    from docx.oxml.text.paragraph import CT_P
+
+
+class CT_Comments(BaseOxmlElement):
+    """`w:comments` element, the root element for the comments part.
+
+    Simply contains a collection of `w:comment` elements, each representing a single comment. Each
+    contained comment is identified by a unique `w:id` attribute, used to reference the comment
+    from the document text. The offset of the comment in this collection is arbitrary; it is
+    essentially a _set_ implemented as a list.
+    """
+
+    # -- type-declarations to fill in the gaps for metaclass-added methods --
+    comment_lst: list[CT_Comment]
+
+    comment = ZeroOrMore("w:comment")
+
+    def add_comment(self) -> CT_Comment:
+        """Return newly added `w:comment` child of this `w:comments`.
+
+        The returned `w:comment` element is the minimum valid value, having a `w:id` value unique
+        within the existing comments and the required `w:author` attribute present but set to the
+        empty string. It's content is limited to a single run containing the necessary annotation
+        reference but no text. Content is added by adding runs to this first paragraph and by
+        adding additional paragraphs as needed.
+        """
+        next_id = self._next_available_comment_id()
+        comment = cast(
+            CT_Comment,
+            parse_xml(
+                f'<w:comment {nsdecls("w")} w:id="{next_id}" w:author="">'
+                f"  <w:p>"
+                f"    <w:pPr>"
+                f'      <w:pStyle w:val="CommentText"/>'
+                f"    </w:pPr>"
+                f"    <w:r>"
+                f"      <w:rPr>"
+                f'        <w:rStyle w:val="CommentReference"/>'
+                f"      </w:rPr>"
+                f"      <w:annotationRef/>"
+                f"    </w:r>"
+                f"  </w:p>"
+                f"</w:comment>"
+            ),
+        )
+        self.append(comment)
+        return comment
+
+    def get_comment_by_id(self, comment_id: int) -> CT_Comment | None:
+        """Return the `w:comment` element identified by `comment_id`, or |None| if not found."""
+        comment_elms = self.xpath(f"(./w:comment[@w:id='{comment_id}'])[1]")
+        return comment_elms[0] if comment_elms else None
+
+    def _next_available_comment_id(self) -> int:
+        """The next available comment id.
+
+        According to the schema, this can be any positive integer, as big as you like, and the
+        default mechanism is to use `max() + 1`. However, if that yields a value larger than will
+        fit in a 32-bit signed integer, we take a more deliberate approach to use the first
+        ununsed integer starting from 0.
+        """
+        used_ids = [int(x) for x in self.xpath("./w:comment/@w:id")]
+
+        next_id = max(used_ids, default=-1) + 1
+
+        if next_id <= 2**31 - 1:
+            return next_id
+
+        # -- fall-back to enumerating all used ids to find the first unused one --
+        for expected, actual in enumerate(sorted(used_ids)):
+            if expected != actual:
+                return expected
+
+        return len(used_ids)
+
+
+class CT_Comment(BaseOxmlElement):
+    """`w:comment` element, representing a single comment.
+
+    A comment is a so-called "story" and can contain paragraphs and tables much like a table-cell.
+    While probably most often used for a single sentence or phrase, a comment can contain rich
+    content, including multiple rich-text paragraphs, hyperlinks, images, and tables.
+    """
+
+    # -- attributes on `w:comment` --
+    id: int = RequiredAttribute("w:id", ST_DecimalNumber)  # pyright: ignore[reportAssignmentType]
+    author: str = RequiredAttribute("w:author", ST_String)  # pyright: ignore[reportAssignmentType]
+    initials: str | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
+        "w:initials", ST_String
+    )
+    date: dt.datetime | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
+        "w:date", ST_DateTime
+    )
+
+    # -- children --
+
+    p = ZeroOrMore("w:p", successors=())
+    tbl = ZeroOrMore("w:tbl", successors=())
+
+    # -- type-declarations for methods added by metaclass --
+
+    add_p: Callable[[], CT_P]
+    p_lst: list[CT_P]
+    tbl_lst: list[CT_Tbl]
+    _insert_tbl: Callable[[CT_Tbl], CT_Tbl]
+
+    @property
+    def inner_content_elements(self) -> list[CT_P | CT_Tbl]:
+        """Generate all `w:p` and `w:tbl` elements in this comment."""
+        return self.xpath("./w:p | ./w:tbl")

docx/oxml/coreprops.py

@@ -0,0 +1,298 @@
+"""Custom element classes for core properties-related XML elements."""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+from typing import TYPE_CHECKING, Any, Callable, cast
+
+from docx.oxml.ns import nsdecls, qn
+from docx.oxml.parser import parse_xml
+from docx.oxml.xmlchemy import BaseOxmlElement, ZeroOrOne
+
+if TYPE_CHECKING:
+    from lxml.etree import _Element as etree_Element  # pyright: ignore[reportPrivateUsage]
+
+
+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[[], etree_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: etree_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")
+
+    @classmethod
+    def new(cls) -> CT_CoreProperties:
+        """Return a new `<cp:coreProperties>` element."""
+        xml = cls._coreProperties_tmpl
+        coreProperties = cast(CT_CoreProperties, parse_xml(xml))
+        return coreProperties
+
+    @property
+    def author_text(self) -> str:
+        """The text in the `dc:creator` child element."""
+        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) -> dt.datetime | None:
+        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) -> dt.datetime | None:
+        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) -> dt.datetime | None:
+        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 = str(revision.text)
+        try:
+            revision = int(revision_str)
+        except ValueError:
+            # non-integer revision strings also resolve to 0
+            revision = 0
+        # as do negative integers
+        if revision < 0:
+            revision = 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 = getattr(self, property_name)
+        if element is None:
+            return None
+        datetime_str = element.text
+        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) -> BaseOxmlElement:
+        """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, dt_: dt.datetime, offset_str: str) -> dt.datetime:
+        """A |datetime| instance offset from `dt_` by timezone offset in `offset_str`.
+
+        `offset_str` is like `"-07:00"`.
+        """
+        match = cls._offset_pattern.match(offset_str)
+        if match is None:
+            raise ValueError("'%s' is not a valid offset string" % offset_str)
+        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 dt_ + 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:]
+        dt_ = None
+        for tmpl in templates:
+            try:
+                dt_ = dt.datetime.strptime(parseable_part, tmpl)
+            except ValueError:
+                continue
+        if dt_ is None:
+            tmpl = "could not parse W3CDTF datetime string '%s'"
+            raise ValueError(tmpl % w3cdtf_str)
+        if len(offset_str) == 6:
+            dt_ = cls._offset_dt(dt_, offset_str)
+        return dt_.replace(tzinfo=dt.timezone.utc)
+
+    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: Any) -> None:
+        """Set string value of `name` property to `value`."""
+        if not isinstance(value, str):
+            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:
+        """The text in the element matching `property_name`.
+
+        The empty string if the element is not present or contains no text.
+        """
+        element = getattr(self, property_name)
+        if element is None:
+            return ""
+        if element.text is None:
+            return ""
+        return element.text