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

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,109 @@
+"""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",
+    "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",
+}
+
+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)