rfctr: Paragraph type-checks clean

Author: scanny

src/docx/opc/part.py

@@ -1,11 +1,18 @@
 """Open Packaging Convention (OPC) objects related to package parts."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 from docx.opc.oxml import serialize_part_xml
 from docx.opc.packuri import PackURI
 from docx.opc.rel import Relationships
 from docx.opc.shared import cls_method_fn, lazyproperty
 from docx.oxml.parser import parse_xml
 
+if TYPE_CHECKING:
+    from docx.opc.package import OpcPackage
+
 
 class Part(object):
     """Base class for package parts.
@@ -14,7 +21,13 @@ class Part(object):
     to implement specific part behaviors.
     """
 
-    def __init__(self, partname, content_type, blob=None, package=None):
+    def __init__(
+        self,
+        partname: str,
+        content_type: str,
+        blob: bytes | None = None,
+        package: OpcPackage | None = None,
+    ):
         super(Part, self).__init__()
         self._partname = partname
         self._content_type = content_type
@@ -96,7 +109,7 @@ def partname(self, partname):
             raise TypeError(tmpl % type(partname).__name__)
         self._partname = partname
 
-    def part_related_by(self, reltype):
+    def part_related_by(self, reltype: str) -> Part:
         """Return part to which this part has a relationship of `reltype`.
 
         Raises |KeyError| if no such relationship is found and |ValueError| if more than
@@ -105,9 +118,12 @@ def part_related_by(self, reltype):
         """
         return self.rels.part_with_reltype(reltype)
 
-    def relate_to(self, target, reltype, is_external=False):
-        """Return rId key of relationship of `reltype` to `target`, from an existing
-        relationship if there is one, otherwise a newly created one."""
+    def relate_to(self, target: Part, reltype: str, is_external: bool = False) -> str:
+        """Return rId key of relationship of `reltype` to `target`.
+
+        The returned `rId` is from an existing relationship if there is one, otherwise a
+        new relationship is created.
+        """
         if is_external:
             return self.rels.get_or_add_ext_rel(reltype, target)
         else:

src/docx/oxml/__init__.py

@@ -21,6 +21,7 @@
     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 (
@@ -68,13 +69,13 @@
 register_element_cls("w:t", CT_Text)
 
 # ---------------------------------------------------------------------------
-# other custom element class mappings
-
-from .shared import CT_DecimalNumber, CT_OnOff, CT_String  # noqa
+# header/footer-related mappings
 
 register_element_cls("w:evenAndOddHeaders", CT_OnOff)
 register_element_cls("w:titlePg", CT_OnOff)
 
+# ---------------------------------------------------------------------------
+# other custom element class mappings
 
 from .coreprops import CT_CoreProperties  # noqa
 

src/docx/oxml/shared.py

@@ -1,5 +1,9 @@
 """Objects shared by modules in the docx.oxml subpackage."""
 
+from __future__ import annotations
+
+from typing import cast
+
 from docx.oxml.ns import qn
 from docx.oxml.parser import OxmlElement
 from docx.oxml.simpletypes import ST_DecimalNumber, ST_OnOff, ST_String
@@ -33,15 +37,19 @@ class CT_OnOff(BaseOxmlElement):
 
 
 class CT_String(BaseOxmlElement):
-    """Used for ``<w:pStyle>`` and ``<w:tblStyle>`` elements and others, containing a
-    style name in its ``val`` attribute."""
+    """Used for `w:pStyle` and `w:tblStyle` elements and others.
+
+    In those cases, it containing a style name in its `val` attribute.
+    """
 
-    val = RequiredAttribute("w:val", ST_String)
+    val: str = RequiredAttribute(  # pyright: ignore[reportGeneralTypeIssues]
+        "w:val", ST_String
+    )
 
     @classmethod
-    def new(cls, nsptagname, val):
+    def new(cls, nsptagname: str, val: str):
         """Return a new ``CT_String`` element with tagname `nsptagname` and ``val``
         attribute set to `val`."""
-        elm = OxmlElement(nsptagname)
+        elm = cast(CT_String, OxmlElement(nsptagname))
         elm.val = val
         return elm

src/docx/oxml/styles.py

@@ -1,5 +1,7 @@
 """Custom element classes related to the styles part."""
 
+from __future__ import annotations
+
 from docx.enum.style import WD_STYLE_TYPE
 from docx.oxml.simpletypes import ST_DecimalNumber, ST_OnOff, ST_String
 from docx.oxml.xmlchemy import (
@@ -126,8 +128,14 @@ class CT_Style(BaseOxmlElement):
     rPr = ZeroOrOne("w:rPr", successors=_tag_seq[18:])
     del _tag_seq
 
-    type = OptionalAttribute("w:type", WD_STYLE_TYPE)
-    styleId = OptionalAttribute("w:styleId", ST_String)
+    type: WD_STYLE_TYPE | None = (
+        OptionalAttribute(  # pyright: ignore[reportGeneralTypeIssues]
+            "w:type", WD_STYLE_TYPE
+        )
+    )
+    styleId: str | None = OptionalAttribute(  # pyright: ignore[reportGeneralTypeIssues]
+        "w:styleId", ST_String
+    )
     default = OptionalAttribute("w:default", ST_OnOff)
     customStyle = OptionalAttribute("w:customStyle", ST_OnOff)
 
@@ -293,23 +301,21 @@ def default_for(self, style_type):
         # spec calls for last default in document order
         return default_styles_for_type[-1]
 
-    def get_by_id(self, styleId):
-        """Return the ``<w:style>`` child element having ``styleId`` attribute matching
-        `styleId`, or |None| if not found."""
-        xpath = 'w:style[@w:styleId="%s"]' % styleId
-        try:
-            return self.xpath(xpath)[0]
-        except IndexError:
-            return None
+    def get_by_id(self, styleId: str) -> CT_Style | None:
+        """`w:style` child where @styleId = `styleId`.
 
-    def get_by_name(self, name):
-        """Return the ``<w:style>`` child element having ``<w:name>`` child element with
-        value `name`, or |None| if not found."""
+        |None| if not found.
+        """
+        xpath = f'w:style[@w:styleId="{styleId}"]'
+        return next(iter(self.xpath(xpath)), None)
+
+    def get_by_name(self, name: str) -> CT_Style | None:
+        """`w:style` child with `w:name` grandchild having value `name`.
+
+        |None| if not found.
+        """
         xpath = 'w:style[w:name/@w:val="%s"]' % name
-        try:
-            return self.xpath(xpath)[0]
-        except IndexError:
-            return None
+        return next(iter(self.xpath(xpath)), None)
 
     def _iter_styles(self):
         """Generate each of the `w:style` child elements in document order."""

src/docx/oxml/text/paragraph.py

@@ -1,14 +1,17 @@
+# pyright: reportPrivateUsage=false
+
 """Custom element classes related to paragraphs (CT_P)."""
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Callable, List
+from typing import TYPE_CHECKING, Callable, List, cast
 
 from docx.oxml.parser import OxmlElement
 from docx.oxml.xmlchemy import BaseOxmlElement, ZeroOrMore, ZeroOrOne
 
 if TYPE_CHECKING:
     from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
+    from docx.oxml.section import CT_SectPr
     from docx.oxml.text.hyperlink import CT_Hyperlink
     from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
     from docx.oxml.text.parfmt import CT_PPr
@@ -18,6 +21,7 @@
 class CT_P(BaseOxmlElement):
     """`<w:p>` element, containing the properties and text for a paragraph."""
 
+    add_r: Callable[[], CT_R]
     get_or_add_pPr: Callable[[], CT_PPr]
     hyperlink_lst: List[CT_Hyperlink]
     r_lst: List[CT_R]
@@ -28,7 +32,7 @@ class CT_P(BaseOxmlElement):
 
     def add_p_before(self) -> CT_P:
         """Return a new `<w:p>` element inserted directly prior to this one."""
-        new_p = OxmlElement("w:p")
+        new_p = cast(CT_P, OxmlElement("w:p"))
         self.addprevious(new_p)
         return new_p
 
@@ -66,7 +70,7 @@ def lastRenderedPageBreaks(self) -> List[CT_LastRenderedPageBreak]:
             "./w:r/w:lastRenderedPageBreak | ./w:hyperlink/w:r/w:lastRenderedPageBreak"
         )
 
-    def set_sectPr(self, sectPr):
+    def set_sectPr(self, sectPr: CT_SectPr):
         """Unconditionally replace or add `sectPr` as grandchild in correct sequence."""
         pPr = self.get_or_add_pPr()
         pPr._remove_sectPr()
@@ -84,7 +88,7 @@ def style(self) -> str | None:
         return pPr.style
 
     @style.setter
-    def style(self, style):
+    def style(self, style: str | None):
         pPr = self.get_or_add_pPr()
         pPr.style = style
 

src/docx/oxml/text/parfmt.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, Callable
+
 from docx.enum.text import (
     WD_ALIGN_PARAGRAPH,
     WD_LINE_SPACING,
@@ -18,6 +20,10 @@
 )
 from docx.shared import Length
 
+if TYPE_CHECKING:
+    from docx.oxml.section import CT_SectPr
+    from docx.oxml.shared import CT_String
+
 
 class CT_Ind(BaseOxmlElement):
     """``<w:ind>`` element, specifying paragraph indentation."""
@@ -37,6 +43,11 @@ class CT_Jc(BaseOxmlElement):
 class CT_PPr(BaseOxmlElement):
     """``<w:pPr>`` element, containing the properties for a paragraph."""
 
+    get_or_add_pStyle: Callable[[], CT_String]
+    _insert_sectPr: Callable[[CT_SectPr], None]
+    _remove_pStyle: Callable[[], None]
+    _remove_sectPr: Callable[[], None]
+
     _tag_seq = (
         "w:pStyle",
         "w:keepNext",
@@ -75,7 +86,9 @@ class CT_PPr(BaseOxmlElement):
         "w:sectPr",
         "w:pPrChange",
     )
-    pStyle = ZeroOrOne("w:pStyle", successors=_tag_seq[1:])
+    pStyle: CT_String | None = ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
+        "w:pStyle", successors=_tag_seq[1:]
+    )
     keepNext = ZeroOrOne("w:keepNext", successors=_tag_seq[2:])
     keepLines = ZeroOrOne("w:keepLines", successors=_tag_seq[3:])
     pageBreakBefore = ZeroOrOne("w:pageBreakBefore", successors=_tag_seq[4:])
@@ -273,20 +286,18 @@ def spacing_lineRule(self, value):
         self.get_or_add_spacing().lineRule = value
 
     @property
-    def style(self):
-        """String contained in <w:pStyle> child, or None if that element is not
-        present."""
+    def style(self) -> str | None:
+        """String contained in `./w:pStyle/@val`, or None if child is not present."""
         pStyle = self.pStyle
         if pStyle is None:
             return None
         return pStyle.val
 
     @style.setter
-    def style(self, style):
-        """Set val attribute of <w:pStyle> child element to `style`, adding a new
-        element if necessary.
+    def style(self, style: str | None):
+        """Set `./w:pStyle/@val` `style`, adding a new element if necessary.
 
-        If `style` is |None|, remove the <w:pStyle> element if present.
+        If `style` is |None|, remove `./w:pStyle` when present.
         """
         if style is None:
             self._remove_pStyle()

src/docx/oxml/xmlchemy.py

@@ -623,6 +623,7 @@ class BaseOxmlElement(metaclass=MetaOxmlElement):
     Adds standardized behavior to all classes in one place.
     """
 
+    addprevious: Callable[[BaseOxmlElement], None]
     attrib: Dict[str, str]
     append: Callable[[ElementBase], None]
     find: Callable[[str], ElementBase | None]

src/docx/parts/document.py

@@ -1,6 +1,11 @@
 """|DocumentPart| and closely related objects."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
 from docx.document import Document
+from docx.enum.style import WD_STYLE_TYPE
 from docx.opc.constants import RELATIONSHIP_TYPE as RT
 from docx.parts.hdrftr import FooterPart, HeaderPart
 from docx.parts.numbering import NumberingPart
@@ -10,6 +15,9 @@
 from docx.shape import InlineShapes
 from docx.shared import lazyproperty
 
+if TYPE_CHECKING:
+    from docx.styles.style import BaseStyle
+
 
 class DocumentPart(StoryPart):
     """Main document part of a WordprocessingML (WML) package, aka a .docx file.
@@ -51,7 +59,7 @@ def footer_part(self, rId: str):
         """Return |FooterPart| related by `rId`."""
         return self.related_parts[rId]
 
-    def get_style(self, style_id, style_type):
+    def get_style(self, style_id: str | None, style_type: WD_STYLE_TYPE) -> BaseStyle:
         """Return the style in this document matching `style_id`.
 
         Returns the default style for `style_type` if `style_id` is |None| or does not
@@ -124,14 +132,16 @@ def _settings_part(self):
             return settings_part
 
     @property
-    def _styles_part(self):
+    def _styles_part(self) -> StylesPart:
         """Instance of |StylesPart| for this document.
 
         Creates an empty styles part if one is not present.
         """
         try:
-            return self.part_related_by(RT.STYLES)
+            return cast(StylesPart, self.part_related_by(RT.STYLES))
         except KeyError:
-            styles_part = StylesPart.default(self.package)
+            package = self.package
+            assert package is not None
+            styles_part = StylesPart.default(package)
             self.relate_to(styles_part, RT.STYLES)
             return styles_part