rfctr: improve typing

Author: scanny

pyrightconfig.json

@@ -0,0 +1,19 @@
+{
+    "exclude": [
+        "**/__pycache__",
+        "**/.*"
+    ],
+    "ignore":  [
+    ],
+    "include": [
+        "src/docx/",
+        "tests"
+    ],
+    "pythonPlatform": "All",
+    "pythonVersion": "3.7",
+    "reportImportCycles": true,
+    "reportUnnecessaryCast": true,
+    "typeCheckingMode": "strict",
+    "useLibraryCodeForTypes": false,
+    "verboseOutput": true
+}

requirements-test.txt

@@ -3,3 +3,4 @@ behave>=1.2.3
 pyparsing>=2.0.1
 pytest>=2.5
 ruff
+typing-extensions

src/docx/api.py

@@ -3,13 +3,16 @@
 Provides a syntactically more convenient API for interacting with the OpcPackage graph.
 """
 
+from __future__ import annotations
+
 import os
+from typing import IO
 
 from docx.opc.constants import CONTENT_TYPE as CT
 from docx.package import Package
 
 
-def Document(docx=None):
+def Document(docx: str | IO[bytes] | None = None):
     """Return a |Document| object loaded from `docx`, where `docx` can be either a path
     to a ``.docx`` file (a string) or a file-like object.
 

src/docx/opc/oxml.py

@@ -27,8 +27,8 @@
 # ===========================================================================
 
 
-def parse_xml(text):
-    """``etree.fromstring()`` replacement that uses oxml parser."""
+def parse_xml(text: str) -> etree._Element:  # pyright: ignore[reportPrivateUsage]
+    """`etree.fromstring()` replacement that uses oxml parser."""
     return etree.fromstring(text, oxml_parser)
 
 

src/docx/opc/rel.py

@@ -1,17 +1,23 @@
 """Relationship-related objects."""
 
-from .oxml import CT_Relationships
+from __future__ import annotations
 
+from typing import Any, Dict
 
-class Relationships(dict):
+from docx.opc.oxml import CT_Relationships
+
+
+class Relationships(Dict[str, "_Relationship"]):
     """Collection object for |_Relationship| instances, having list semantics."""
 
-    def __init__(self, baseURI):
+    def __init__(self, baseURI: str):
         super(Relationships, self).__init__()
         self._baseURI = baseURI
-        self._target_parts_by_rId = {}
+        self._target_parts_by_rId: Dict[str, Any] = {}
 
-    def add_relationship(self, reltype, target, rId, is_external=False):
+    def add_relationship(
+        self, reltype: str, target: str | Any, rId: str, is_external: bool = False
+    ) -> "_Relationship":
         """Return a newly added |_Relationship| instance."""
         rel = _Relationship(rId, reltype, target, self._baseURI, is_external)
         self[rId] = rel
@@ -105,7 +111,7 @@ def _next_rId(self):
 class _Relationship(object):
     """Value object for relationship to part."""
 
-    def __init__(self, rId, reltype, target, baseURI, external=False):
+    def __init__(self, rId: str, reltype, target, baseURI, external=False):
         super(_Relationship, self).__init__()
         self._rId = rId
         self._reltype = reltype
@@ -135,7 +141,7 @@ def target_part(self):
         return self._target
 
     @property
-    def target_ref(self):
+    def target_ref(self) -> str:
         if self._is_external:
             return self._target
         else:

src/docx/oxml/__init__.py

@@ -3,6 +3,8 @@
 This including registering custom element classes corresponding to Open XML elements.
 """
 
+from __future__ import annotations
+
 from lxml import etree
 
 from docx.oxml.ns import NamespacePrefixedTag, nsmap

src/docx/oxml/coreprops.py

@@ -2,6 +2,7 @@
 
 import re
 from datetime import datetime, timedelta
+from typing import Any
 
 from docx.oxml import parse_xml
 from docx.oxml.ns import nsdecls, qn
@@ -47,31 +48,31 @@ def author_text(self):
         return self._text_of_element("creator")
 
     @author_text.setter
-    def author_text(self, value):
+    def author_text(self, value: str):
         self._set_element_text("creator", value)
 
     @property
-    def category_text(self):
+    def category_text(self) -> str:
         return self._text_of_element("category")
 
     @category_text.setter
-    def category_text(self, value):
+    def category_text(self, value: str):
         self._set_element_text("category", value)
 
     @property
-    def comments_text(self):
+    def comments_text(self) -> str:
         return self._text_of_element("description")
 
     @comments_text.setter
-    def comments_text(self, value):
+    def comments_text(self, value: str):
         self._set_element_text("description", value)
 
     @property
     def contentStatus_text(self):
         return self._text_of_element("contentStatus")
 
     @contentStatus_text.setter
-    def contentStatus_text(self, value):
+    def contentStatus_text(self, value: str):
         self._set_element_text("contentStatus", value)
 
     @property
@@ -264,7 +265,7 @@ def _set_element_datetime(self, prop_name, value):
             element.set(qn("xsi:type"), "dcterms:W3CDTF")
             del self.attrib[qn("xsi:foo")]
 
-    def _set_element_text(self, prop_name, value):
+    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)
@@ -275,7 +276,7 @@ def _set_element_text(self, prop_name, value):
         element = self._get_or_add(prop_name)
         element.text = value
 
-    def _text_of_element(self, property_name):
+    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.

src/docx/oxml/ns.py

@@ -1,5 +1,9 @@
 """Namespace-related objects."""
 
+from typing import Any, Dict
+
+from typing_extensions import Self
+
 nsmap = {
     "a": "http://schemas.openxmlformats.org/drawingml/2006/main",
     "c": "http://schemas.openxmlformats.org/drawingml/2006/chart",
@@ -25,74 +29,80 @@
 class NamespacePrefixedTag(str):
     """Value object that knows the semantics of an XML tag having a namespace prefix."""
 
-    def __new__(cls, nstag, *args):
+    def __new__(cls, nstag: str, *args: Any):
         return super(NamespacePrefixedTag, cls).__new__(cls, nstag)
 
-    def __init__(self, nstag):
+    def __init__(self, nstag: str):
         self._pfx, self._local_part = nstag.split(":")
         self._ns_uri = nsmap[self._pfx]
 
     @property
-    def clark_name(self):
+    def clark_name(self) -> str:
         return "{%s}%s" % (self._ns_uri, self._local_part)
 
     @classmethod
-    def from_clark_name(cls, clark_name):
+    def from_clark_name(cls, clark_name: str) -> Self:
         nsuri, local_name = clark_name[1:].split("}")
         nstag = "%s:%s" % (pfxmap[nsuri], local_name)
         return cls(nstag)
 
     @property
-    def local_part(self):
-        """Return the local part of the tag as a string.
+    def local_part(self) -> str:
+        """The local part of this tag.
 
-        E.g. 'foobar' is returned for tag 'f:foobar'.
+        E.g. "foobar" is returned for tag "f:foobar".
         """
         return self._local_part
 
     @property
-    def nsmap(self):
-        """Return a dict having a single member, mapping the namespace prefix of this
-        tag to it's namespace name (e.g. {'f': 'http://foo/bar'}).
+    def nsmap(self) -> Dict[str, str]:
+        """Single-member dict mapping prefix of this tag to it's namespace name.
 
-        This is handy for passing to xpath calls and other uses.
+        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):
-        """Return the string namespace prefix for the tag, e.g. 'f' is returned for tag
-        'f:foobar'."""
+    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):
-        """Return the namespace URI for the tag, e.g. 'http://foo/bar' would be returned
-        for tag 'f:foobar' if the 'f' prefix maps to 'http://foo/bar' in nsmap."""
+    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):
-    """Return a string containing a namespace declaration for each of the namespace
-    prefix strings, e.g. 'p', 'ct', passed as `prefixes`."""
+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):
-    """Return a dict containing the subset namespace prefix mappings specified by
-    `nspfxs`.
+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').
+    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):
-    """Stands for "qualified name", a utility function to turn a namespace prefixed tag
-    name into a Clark-notation qualified tag name for lxml.
+def qn(tag: str) -> str:
+    """Stands for "qualified name".
 
-    For
-    example, ``qn('p:cSld')`` returns ``'{http://schemas.../main}cSld'``.
+    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]

src/docx/oxml/shape.py

@@ -1,5 +1,7 @@
 """Custom element classes for shape-related elements like `<w:inline>`."""
 
+from __future__ import annotations
+
 from docx.oxml import parse_xml
 from docx.oxml.ns import nsdecls
 from docx.oxml.simpletypes import (

src/docx/oxml/text/paragraph.py

@@ -1,43 +1,48 @@
 """Custom element classes related to paragraphs (CT_P)."""
 
-from docx.oxml.ns import qn
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable, List
+
 from docx.oxml.xmlchemy import BaseOxmlElement, OxmlElement, ZeroOrMore, ZeroOrOne
 
+if TYPE_CHECKING:
+    from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
+    from docx.oxml.text.parfmt import CT_PPr
+    from docx.oxml.text.run import CT_R
+
 
 class CT_P(BaseOxmlElement):
     """`<w:p>` element, containing the properties and text for a paragraph."""
 
-    pPr = ZeroOrOne("w:pPr")
-    r = ZeroOrMore("w:r")
+    get_or_add_pPr: Callable[[], CT_PPr]
+    r_lst: List[CT_R]
 
-    def _insert_pPr(self, pPr):
-        self.insert(0, pPr)
-        return pPr
+    pPr: CT_PPr | None = ZeroOrOne("w:pPr")  # pyright: ignore[reportGeneralTypeIssues]
+    r = ZeroOrMore("w:r")
 
-    def add_p_before(self):
+    def add_p_before(self) -> CT_P:
         """Return a new `<w:p>` element inserted directly prior to this one."""
         new_p = OxmlElement("w:p")
         self.addprevious(new_p)
         return new_p
 
     @property
-    def alignment(self):
+    def alignment(self) -> WD_PARAGRAPH_ALIGNMENT | None:
         """The value of the `<w:jc>` grandchild element or |None| if not present."""
         pPr = self.pPr
         if pPr is None:
             return None
         return pPr.jc_val
 
     @alignment.setter
-    def alignment(self, value):
+    def alignment(self, value: WD_PARAGRAPH_ALIGNMENT):
         pPr = self.get_or_add_pPr()
         pPr.jc_val = value
 
     def clear_content(self):
         """Remove all child elements, except the `<w:pPr>` element if present."""
-        for child in self[:]:
-            if child.tag == qn("w:pPr"):
-                continue
+        for child in self.xpath("./*[not(self::w:pPr)]"):
             self.remove(child)
 
     def set_sectPr(self, sectPr):
@@ -47,7 +52,7 @@ def set_sectPr(self, sectPr):
         pPr._insert_sectPr(sectPr)
 
     @property
-    def style(self):
+    def style(self) -> str | None:
         """String contained in `w:val` attribute of `./w:pPr/w:pStyle` grandchild.
 
         |None| if not present.
@@ -61,3 +66,7 @@ def style(self):
     def style(self, style):
         pPr = self.get_or_add_pPr()
         pPr.style = style
+
+    def _insert_pPr(self, pPr: CT_PPr) -> CT_PPr:
+        self.insert(0, pPr)
+        return pPr