python-docx-oss 0.1.0__py3-none-any.whl

docx/oxml/customprops.py

@@ -0,0 +1,141 @@
+"""
+lxml custom element classes for core properties-related XML elements.
+"""
+import re
+from datetime import datetime, timedelta
+
+from . import parse_xml
+from .ns import nsdecls, qn
+from .xmlchemy import BaseOxmlElement
+
+
+class CT_CustomProperties(BaseOxmlElement):
+    """
+    ``<Properties>`` element, the root element of the Custom Properties
+    part stored as ``/docProps/custom.xml``. String elements are
+    limited in length to 255 unicode characters.
+    """
+
+    _customProperties_tmpl = (
+        '<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/custom-properties" %s/>\n'
+        % nsdecls("vt")
+    )
+
+    @classmethod
+    def new(cls):
+        """
+        Return a new ``<property>`` element
+        """
+        xml = cls._customProperties_tmpl
+        return parse_xml(xml)
+
+    def _datetime_of_element(self, property_name):
+        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):
+        """
+        Return element returned by 'get_or_add_' method for *prop_name*.
+        """
+        get_or_add_method_name = f"get_or_add_{prop_name}"
+        get_or_add_method = getattr(self, get_or_add_method_name)
+        return get_or_add_method()
+
+    @classmethod
+    def _offset_dt(cls, dt, offset_str):
+        """
+        Return a |datetime| instance that is offset from datetime *dt* by
+        the timezone offset specified in *offset_str*, a string 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 = 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):
+        # 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 = 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:
+            return cls._offset_dt(dt, offset_str)
+        return dt
+
+    def _set_element_datetime(self, prop_name, value):
+        """
+        Set date/time value of child element having *prop_name* to *value*.
+        """
+        if not isinstance(value, datetime):
+            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, value):
+        """
+        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):
+        """
+        Return the text in the element matching *property_name*, or an 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

docx/oxml/dml/CT_ExtensionList.py

@@ -0,0 +1,48 @@
+# pyright: reportPrivateUsage=false
+
+"""This module is for elements which has extLst child."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, 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 docx.oxml.shape import CT_Extension
+
+
+class CT_ExtensionList(BaseOxmlElement):
+    """Base class for `extLst` element in DrawingML."""
+
+    ext: CT_Extension = ZeroOrOne("a:ext")
+    _add_ext: Any
+
+    @classmethod
+    def new(cls):
+        """Return a new `extLst` element."""
+        extLst = cast(
+            CT_ExtensionList,
+            parse_xml(f"<a:extLst {nsdecls('a')}/>"),
+        )
+        extLst._add_ext()
+        return extLst
+
+
+class CT_Extension(BaseOxmlElement):
+    """
+    `<a:ext>` element in `extLst`, which can hold a `svgBlip` element.
+    """
+
+    @property
+    def svgBlip(self) -> "CT_Transform2D":
+        from docx.oxml.shape import CT_Transform2D
+
+        return self.xpath("./asvg:svgBlip")[0]
+
+    @classmethod
+    def new(cls):
+        """Return a new `ext` element."""
+        return cast(CT_Extension, parse_xml(f"<a:ext {nsdecls('a')}/>"))

docx/oxml/document.py

@@ -0,0 +1,88 @@
+"""Custom element classes that correspond to the document part, e.g. <w:document>."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable, List
+
+from docx.oxml.section import CT_SectPr
+from docx.oxml.xmlchemy import BaseOxmlElement, ZeroOrMore, ZeroOrOne
+
+if TYPE_CHECKING:
+    from docx.oxml.table import CT_Tbl
+    from docx.oxml.text.paragraph import CT_P
+
+
+class CT_Document(BaseOxmlElement):
+    """``<w:document>`` element, the root element of a document.xml file."""
+
+    body: CT_Body = ZeroOrOne("w:body")  # pyright: ignore[reportAssignmentType]
+
+    @property
+    def sectPr_lst(self) -> List[CT_SectPr]:
+        """All `w:sectPr` elements directly accessible from document element.
+
+        Note this does not include a `sectPr` child in a paragraphs wrapped in
+        revision marks or other intervening layer, perhaps `w:sdt` or customXml
+        elements.
+
+        `w:sectPr` elements appear in document order. The last one is always
+        `w:body/w:sectPr`, all preceding are `w:p/w:pPr/w:sectPr`.
+        """
+        xpath = "./w:body/w:p/w:pPr/w:sectPr | ./w:body/w:sectPr"
+        return self.xpath(xpath)
+
+
+class CT_Body(BaseOxmlElement):
+    """`w:body`, the container element for the main document story in `document.xml`."""
+
+    add_p: Callable[[], CT_P]
+    get_or_add_sectPr: Callable[[], CT_SectPr]
+    p_lst: List[CT_P]
+    tbl_lst: List[CT_Tbl]
+
+    _insert_tbl: Callable[[CT_Tbl], CT_Tbl]
+
+    p = ZeroOrMore("w:p", successors=("w:sectPr",))
+    tbl = ZeroOrMore("w:tbl", successors=("w:sectPr",))
+    sectPr: CT_SectPr | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "w:sectPr", successors=()
+    )
+
+    def add_section_break(self) -> CT_SectPr:
+        """Return `w:sectPr` element for new section added at end of document.
+
+        The last `w:sectPr` becomes the second-to-last, with the new `w:sectPr` being an
+        exact clone of the previous one, except that all header and footer references
+        are removed (and are therefore now "inherited" from the prior section).
+
+        A copy of the previously-last `w:sectPr` will now appear in a new `w:p` at the
+        end of the document. The returned `w:sectPr` is the sentinel `w:sectPr` for the
+        document (and as implemented, `is` the prior sentinel `w:sectPr` with headers
+        and footers removed).
+        """
+        # ---get the sectPr at file-end, which controls last section (sections[-1])---
+        sentinel_sectPr = self.get_or_add_sectPr()
+        # ---add exact copy to new `w:p` element; that is now second-to last section---
+        self.add_p().set_sectPr(sentinel_sectPr.clone())
+        # ---remove any header or footer references from "new" last section---
+        for hdrftr_ref in sentinel_sectPr.xpath("w:headerReference|w:footerReference"):
+            sentinel_sectPr.remove(hdrftr_ref)
+        # ---the sentinel `w:sectPr` now controls the new last section---
+        return sentinel_sectPr
+
+    def clear_content(self):
+        """Remove all content child elements from this <w:body> element.
+
+        Leave the <w:sectPr> element if it is present.
+        """
+        for content_elm in self.xpath("./*[not(self::w:sectPr)]"):
+            self.remove(content_elm)
+
+    @property
+    def inner_content_elements(self) -> List[CT_P | CT_Tbl]:
+        """Generate all `w:p` and `w:tbl` elements in this document-body.
+
+        Elements appear in document order. Elements shaded by nesting in a `w:ins` or
+        other "wrapper" element will not be included.
+        """
+        return self.xpath("./w:p | ./w:tbl")

docx/oxml/drawing.py

@@ -0,0 +1,11 @@
+"""Custom element-classes for DrawingML-related elements like `<w:drawing>`.
+
+For legacy reasons, many DrawingML-related elements are in `docx.oxml.shape`. Expect
+those to move over here as we have reason to touch them.
+"""
+
+from docx.oxml.xmlchemy import BaseOxmlElement
+
+
+class CT_Drawing(BaseOxmlElement):
+    """`<w:drawing>` element, containing a DrawingML object like a picture or chart."""

docx/oxml/exceptions.py

@@ -0,0 +1,10 @@
+"""Exceptions for oxml sub-package."""
+
+
+class XmlchemyError(Exception):
+    """Generic error class."""
+
+
+class InvalidXmlError(XmlchemyError):
+    """Raised when invalid XML is encountered, such as on attempt to access a missing
+    required child element."""

docx/oxml/ns.py

@@ -0,0 +1,111 @@
+"""Namespace-related objects."""
+
+from __future__ import annotations
+
+from typing import Dict
+
+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",
+    "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",
+    "m": "http://schemas.openxmlformats.org/officeDocument/2006/math",
+    "pic": "http://schemas.openxmlformats.org/drawingml/2006/picture",
+    "r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+    "sl": "http://schemas.openxmlformats.org/schemaLibrary/2006/main",
+    "vt": "http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes",
+    "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
+    "w14": "http://schemas.microsoft.com/office/word/2010/wordml",
+    "wp": "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing",
+    "xml": "http://www.w3.org/XML/1998/namespace",
+    "xsi": "http://www.w3.org/2001/XMLSchema-instance",
+    "asvg": "http://schemas.microsoft.com/office/drawing/2016/SVG/main",
+}
+
+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]
+
+    @property
+    def clark_name(self) -> str:
+        return "{%s}%s" % (self._ns_uri, self._local_part)
+
+    @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 local_part(self) -> str:
+        """The local part of this tag.
+
+        E.g. "foobar" is returned for tag "f:foobar".
+        """
+        return self._local_part
+
+    @property
+    def nsmap(self) -> Dict[str, str]:
+        """Single-member dict mapping prefix of this tag to it's namespace name.
+
+        Example: `{"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) -> str:
+        """The namespace-prefix for this tag.
+
+        For example, "f" is returned for tag "f:foobar".
+        """
+        return self._pfx
+
+    @property
+    def nsuri(self) -> str:
+        """The namespace URI for this tag.
+
+        For example, "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 nsdecls(*prefixes: str) -> str:
+    """Namespace declaration including each namespace-prefix in `prefixes`.
+
+    Handy for adding required namespace declarations to a tree root element.
+    """
+    return " ".join(['xmlns:%s="%s"' % (pfx, nsmap[pfx]) for pfx in prefixes])
+
+
+def nspfxmap(*nspfxs: str) -> Dict[str, str]:
+    """Subset namespace-prefix mappings specified by *nspfxs*.
+
+    Any number of namespace prefixes can be supplied, e.g. namespaces("a", "r", "p").
+    """
+    return {pfx: nsmap[pfx] for pfx in nspfxs}
+
+
+def qn(tag: str) -> str:
+    """Stands for "qualified name".
+
+    This utility function converts a familiar namespace-prefixed tag name like "w:p"
+    into a Clark-notation qualified tag name for lxml. For example, `qn("w:p")` returns
+    "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}p".
+    """
+    prefix, tagroot = tag.split(":")
+    uri = nsmap[prefix]
+    return "{%s}%s" % (uri, tagroot)

docx/oxml/numbering.py

@@ -0,0 +1,109 @@
+"""Custom element classes related to the numbering part."""
+
+from docx.oxml.parser import OxmlElement
+from docx.oxml.shared import CT_DecimalNumber
+from docx.oxml.simpletypes import ST_DecimalNumber
+from docx.oxml.xmlchemy import (
+    BaseOxmlElement,
+    OneAndOnlyOne,
+    RequiredAttribute,
+    ZeroOrMore,
+    ZeroOrOne,
+)
+
+
+class CT_Num(BaseOxmlElement):
+    """``<w:num>`` element, which represents a concrete list definition instance, having
+    a required child <w:abstractNumId> that references an abstract numbering definition
+    that defines most of the formatting details."""
+
+    abstractNumId = OneAndOnlyOne("w:abstractNumId")
+    lvlOverride = ZeroOrMore("w:lvlOverride")
+    numId = RequiredAttribute("w:numId", ST_DecimalNumber)
+
+    def add_lvlOverride(self, ilvl):
+        """Return a newly added CT_NumLvl (<w:lvlOverride>) element having its ``ilvl``
+        attribute set to `ilvl`."""
+        return self._add_lvlOverride(ilvl=ilvl)
+
+    @classmethod
+    def new(cls, num_id, abstractNum_id):
+        """Return a new ``<w:num>`` element having numId of `num_id` and having a
+        ``<w:abstractNumId>`` child with val attribute set to `abstractNum_id`."""
+        num = OxmlElement("w:num")
+        num.numId = num_id
+        abstractNumId = CT_DecimalNumber.new("w:abstractNumId", abstractNum_id)
+        num.append(abstractNumId)
+        return num
+
+
+class CT_NumLvl(BaseOxmlElement):
+    """``<w:lvlOverride>`` element, which identifies a level in a list definition to
+    override with settings it contains."""
+
+    startOverride = ZeroOrOne("w:startOverride", successors=("w:lvl",))
+    ilvl = RequiredAttribute("w:ilvl", ST_DecimalNumber)
+
+    def add_startOverride(self, val):
+        """Return a newly added CT_DecimalNumber element having tagname
+        ``w:startOverride`` and ``val`` attribute set to `val`."""
+        return self._add_startOverride(val=val)
+
+
+class CT_NumPr(BaseOxmlElement):
+    """A ``<w:numPr>`` element, a container for numbering properties applied to a
+    paragraph."""
+
+    ilvl = ZeroOrOne("w:ilvl", successors=("w:numId", "w:numberingChange", "w:ins"))
+    numId = ZeroOrOne("w:numId", successors=("w:numberingChange", "w:ins"))
+
+    # @ilvl.setter
+    # def _set_ilvl(self, val):
+    #     """
+    #     Get or add a <w:ilvl> child and set its ``w:val`` attribute to `val`.
+    #     """
+    #     ilvl = self.get_or_add_ilvl()
+    #     ilvl.val = val
+
+    # @numId.setter
+    # def numId(self, val):
+    #     """
+    #     Get or add a <w:numId> child and set its ``w:val`` attribute to
+    #     `val`.
+    #     """
+    #     numId = self.get_or_add_numId()
+    #     numId.val = val
+
+
+class CT_Numbering(BaseOxmlElement):
+    """``<w:numbering>`` element, the root element of a numbering part, i.e.
+    numbering.xml."""
+
+    num = ZeroOrMore("w:num", successors=("w:numIdMacAtCleanup",))
+
+    def add_num(self, abstractNum_id):
+        """Return a newly added CT_Num (<w:num>) element referencing the abstract
+        numbering definition identified by `abstractNum_id`."""
+        next_num_id = self._next_numId
+        num = CT_Num.new(next_num_id, abstractNum_id)
+        return self._insert_num(num)
+
+    def num_having_numId(self, numId):
+        """Return the ``<w:num>`` child element having ``numId`` attribute matching
+        `numId`."""
+        xpath = './w:num[@w:numId="%d"]' % numId
+        try:
+            return self.xpath(xpath)[0]
+        except IndexError:
+            raise KeyError("no <w:num> element with numId %d" % numId)
+
+    @property
+    def _next_numId(self):
+        """The first ``numId`` unused by a ``<w:num>`` element, starting at 1 and
+        filling any gaps in numbering between existing ``<w:num>`` elements."""
+        numId_strs = self.xpath("./w:num/@w:numId")
+        num_ids = [int(numId_str) for numId_str in numId_strs]
+        for num in range(1, len(num_ids) + 2):
+            if num not in num_ids:
+                break
+        return num

docx/oxml/parser.py

@@ -0,0 +1,62 @@
+# pyright: reportImportCycles=false
+
+"""XML parser for python-docx."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, Type, cast
+
+from lxml import etree
+
+from docx.oxml.ns import NamespacePrefixedTag, nsmap
+
+if TYPE_CHECKING:
+    from docx.oxml.xmlchemy import BaseOxmlElement
+
+
+# -- configure XML parser --
+element_class_lookup = etree.ElementNamespaceClassLookup()
+oxml_parser = etree.XMLParser(remove_blank_text=True, resolve_entities=False)
+oxml_parser.set_element_class_lookup(element_class_lookup)
+
+
+def parse_xml(xml: str | bytes) -> "BaseOxmlElement":
+    """Root lxml element obtained by parsing XML character string `xml`.
+
+    The custom parser is used, so custom element classes are produced for elements in
+    `xml` that have them.
+    """
+    return cast("BaseOxmlElement", etree.fromstring(xml, oxml_parser))
+
+
+def register_element_cls(tag: str, cls: Type["BaseOxmlElement"]):
+    """Register an lxml custom element-class to use for `tag`.
+
+    A instance of `cls` to be constructed when the oxml parser encounters an element
+    with matching `tag`. `tag` is a string of the form `nspfx:tagroot`, e.g.
+    `'w:document'`.
+    """
+    nspfx, tagroot = tag.split(":")
+    namespace = element_class_lookup.get_namespace(nsmap[nspfx])
+    namespace[tagroot] = cls
+
+
+def OxmlElement(
+    nsptag_str: str,
+    attrs: Dict[str, str] | None = None,
+    nsdecls: Dict[str, str] | None = None,
+) -> BaseOxmlElement | etree._Element:  # pyright: ignore[reportPrivateUsage]
+    """Return a 'loose' lxml element having the tag specified by `nsptag_str`.
+
+    The tag in `nsptag_str` must contain the standard namespace prefix, e.g. `a:tbl`.
+    The resulting element is an instance of the custom element class for this tag name
+    if one is defined. A dictionary of attribute values may be provided as `attrs`; they
+    are set if present. All namespaces defined in the dict `nsdecls` are declared in the
+    element using the key as the prefix and the value as the namespace name. If
+    `nsdecls` is not provided, a single namespace declaration is added based on the
+    prefix on `nsptag_str`.
+    """
+    nsptag = NamespacePrefixedTag(nsptag_str)
+    if nsdecls is None:
+        nsdecls = nsptag.nsmap
+    return oxml_parser.makeelement(nsptag.clark_name, attrib=attrs, nsmap=nsdecls)