modn: improve type annotation

scanny · scanny · commit 4262f4de7985 · 2025-06-12T15:37:39.000-07:00
diff --git a/src/docx/opc/coreprops.py b/src/docx/opc/coreprops.py
@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+import datetime as dt
 from typing import TYPE_CHECKING
 
 from docx.oxml.coreprops import CT_CoreProperties
@@ -57,7 +58,7 @@ def created(self):
         return self._element.created_datetime
 
     @created.setter
-    def created(self, value):
+    def created(self, value: dt.datetime):
         self._element.created_datetime = value
 
     @property
@@ -97,23 +98,23 @@ def last_printed(self):
         return self._element.lastPrinted_datetime
 
     @last_printed.setter
-    def last_printed(self, value):
+    def last_printed(self, value: dt.datetime):
         self._element.lastPrinted_datetime = value
 
     @property
     def modified(self):
         return self._element.modified_datetime
 
     @modified.setter
-    def modified(self, value):
+    def modified(self, value: dt.datetime):
         self._element.modified_datetime = value
 
     @property
     def revision(self):
         return self._element.revision_number
 
     @revision.setter
-    def revision(self, value):
+    def revision(self, value: int):
         self._element.revision_number = value
 
     @property
diff --git a/src/docx/opc/oxml.py b/src/docx/opc/oxml.py
@@ -38,7 +38,7 @@ def parse_xml(text: str) -> etree._Element:
     return etree.fromstring(text, oxml_parser)
 
 
-def qn(tag):
+def qn(tag: str) -> str:
     """Stands for "qualified name", a utility function to turn a namespace prefixed tag
     name into a Clark-notation qualified tag name for lxml.
 
@@ -50,7 +50,7 @@ def qn(tag):
     return "{%s}%s" % (uri, tagroot)
 
 
-def serialize_part_xml(part_elm: etree._Element):
+def serialize_part_xml(part_elm: etree._Element) -> bytes:
     """Serialize `part_elm` etree element to XML suitable for storage as an XML part.
 
     That is to say, no insignificant whitespace added for readability, and an
@@ -59,7 +59,7 @@ def serialize_part_xml(part_elm: etree._Element):
     return etree.tostring(part_elm, encoding="UTF-8", standalone=True)
 
 
-def serialize_for_reading(element):
+def serialize_for_reading(element: etree._Element) -> str:
     """Serialize `element` to human-readable XML suitable for tests.
 
     No XML declaration.
@@ -77,7 +77,7 @@ class BaseOxmlElement(etree.ElementBase):
     classes in one place."""
 
     @property
-    def xml(self):
+    def xml(self) -> str:
         """Return XML string for this element, suitable for testing purposes.
 
         Pretty printed for readability and without an XML declaration at the top.
@@ -86,8 +86,10 @@ def xml(self):
 
 
 class CT_Default(BaseOxmlElement):
-    """``<Default>`` element, specifying the default content type to be applied to a
-    part with the specified extension."""
+    """`<Default>` element that appears in `[Content_Types].xml` part.
+
+    Used to specify a default content type to be applied to any part with the specified extension.
+    """
 
     @property
     def content_type(self):
@@ -101,9 +103,8 @@ def extension(self):
         return self.get("Extension")
 
     @staticmethod
-    def new(ext, content_type):
-        """Return a new ``<Default>`` element with attributes set to parameter
-        values."""
+    def new(ext: str, content_type: str):
+        """Return a new ``<Default>`` element with attributes set to parameter values."""
         xml = '<Default xmlns="%s"/>' % nsmap["ct"]
         default = parse_xml(xml)
         default.set("Extension", ext)
@@ -123,8 +124,7 @@ def content_type(self):
 
     @staticmethod
     def new(partname, content_type):
-        """Return a new ``<Override>`` element with attributes set to parameter
-        values."""
+        """Return a new ``<Override>`` element with attributes set to parameter values."""
         xml = '<Override xmlns="%s"/>' % nsmap["ct"]
         override = parse_xml(xml)
         override.set("PartName", partname)
@@ -138,8 +138,7 @@ def partname(self):
 
 
 class CT_Relationship(BaseOxmlElement):
-    """``<Relationship>`` element, representing a single relationship from a source to a
-    target part."""
+    """`<Relationship>` element, representing a single relationship from source to target part."""
 
     @staticmethod
     def new(rId: str, reltype: str, target: str, target_mode: str = RTM.INTERNAL):
diff --git a/src/docx/oxml/__init__.py b/src/docx/oxml/__init__.py
@@ -234,6 +234,7 @@
 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)
diff --git a/src/docx/oxml/coreprops.py b/src/docx/oxml/coreprops.py
@@ -4,7 +4,7 @@
 
 import datetime as dt
 import re
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any, Callable, cast
 
 from docx.oxml.ns import nsdecls, qn
 from docx.oxml.parser import parse_xml
@@ -45,14 +45,14 @@ class CT_CoreProperties(BaseOxmlElement):
     _coreProperties_tmpl = "<cp:coreProperties %s/>\n" % nsdecls("cp", "dc", "dcterms")
 
     @classmethod
-    def new(cls):
+    def new(cls) -> CT_CoreProperties:
         """Return a new `<cp:coreProperties>` element."""
         xml = cls._coreProperties_tmpl
-        coreProperties = parse_xml(xml)
+        coreProperties = cast(CT_CoreProperties, parse_xml(xml))
         return coreProperties
 
     @property
-    def author_text(self):
+    def author_text(self) -> str:
         """The text in the `dc:creator` child element."""
         return self._text_of_element("creator")
 
@@ -77,55 +77,55 @@ def comments_text(self, value: str):
         self._set_element_text("description", value)
 
     @property
-    def contentStatus_text(self):
+    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):
+    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):
+    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):
+    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):
+    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):
+    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):
+    def lastPrinted_datetime(self) -> dt.datetime | None:
         return self._datetime_of_element("lastPrinted")
 
     @lastPrinted_datetime.setter
@@ -141,7 +141,7 @@ def modified_datetime(self, value: dt.datetime):
         self._set_element_datetime("modified", value)
 
     @property
-    def revision_number(self):
+    def revision_number(self) -> int:
         """Integer value of revision property."""
         revision = self.revision
         if revision is None:
@@ -167,23 +167,23 @@ def revision_number(self, value: int):
         revision.text = str(value)
 
     @property
-    def subject_text(self):
+    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):
+    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):
+    def version_text(self) -> str:
         return self._text_of_element("version")
 
     @version_text.setter
@@ -257,7 +257,7 @@ def _parse_W3CDTF_to_datetime(cls, w3cdtf_str: str) -> dt.datetime:
             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):
+    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"
diff --git a/src/docx/oxml/ns.py b/src/docx/oxml/ns.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Dict
+from typing import Dict
 
 nsmap = {
     "a": "http://schemas.openxmlformats.org/drawingml/2006/main",
@@ -29,7 +29,7 @@
 class NamespacePrefixedTag(str):
     """Value object that knows the semantics of an XML tag having a namespace prefix."""
 
-    def __new__(cls, nstag: str, *args: Any):
+    def __new__(cls, nstag: str):
         return super(NamespacePrefixedTag, cls).__new__(cls, nstag)
 
     def __init__(self, nstag: str):
diff --git a/src/docx/oxml/shape.py b/src/docx/oxml/shape.py
@@ -145,10 +145,8 @@ class CT_Picture(BaseOxmlElement):
     spPr: CT_ShapeProperties = OneAndOnlyOne("pic:spPr")  # pyright: ignore[reportAssignmentType]
 
     @classmethod
-    def new(cls, pic_id, filename, rId, cx, cy):
-        """Return a new ``<pic:pic>`` element populated with the minimal contents
-        required to define a viable picture element, based on the values passed as
-        parameters."""
+    def new(cls, pic_id: int, filename: str, rId: str, cx: Length, cy: Length) -> CT_Picture:
+        """A new minimum viable `<pic:pic>` (picture) element."""
         pic = parse_xml(cls._pic_xml())
         pic.nvPicPr.cNvPr.id = pic_id
         pic.nvPicPr.cNvPr.name = filename
diff --git a/src/docx/oxml/text/parfmt.py b/src/docx/oxml/text/parfmt.py
@@ -10,6 +10,7 @@
     WD_TAB_ALIGNMENT,
     WD_TAB_LEADER,
 )
+from docx.oxml.shared import CT_DecimalNumber
 from docx.oxml.simpletypes import ST_SignedTwipsMeasure, ST_TwipsMeasure
 from docx.oxml.xmlchemy import (
     BaseOxmlElement,
@@ -55,6 +56,7 @@ class CT_PPr(BaseOxmlElement):
 
     get_or_add_ind: Callable[[], CT_Ind]
     get_or_add_pStyle: Callable[[], CT_String]
+    get_or_add_sectPr: Callable[[], CT_SectPr]
     _insert_sectPr: Callable[[CT_SectPr], None]
     _remove_pStyle: Callable[[], None]
     _remove_sectPr: Callable[[], None]
@@ -111,6 +113,9 @@ class CT_PPr(BaseOxmlElement):
         "w:ind", successors=_tag_seq[23:]
     )
     jc = ZeroOrOne("w:jc", successors=_tag_seq[27:])
+    outlineLvl: CT_DecimalNumber = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "w:outlineLvl", successors=_tag_seq[31:]
+    )
     sectPr = ZeroOrOne("w:sectPr", successors=_tag_seq[35:])
     del _tag_seq
 
diff --git a/src/docx/oxml/xmlchemy.py b/src/docx/oxml/xmlchemy.py
@@ -5,17 +5,7 @@
 from __future__ import annotations
 
 import re
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Callable,
-    Dict,
-    List,
-    Sequence,
-    Tuple,
-    Type,
-    TypeVar,
-)
+from typing import TYPE_CHECKING, Any, Callable, Sequence, Type, TypeVar
 
 from lxml import etree
 from lxml.etree import ElementBase, _Element  # pyright: ignore[reportPrivateUsage]
@@ -65,7 +55,7 @@ def __eq__(self, other: object) -> bool:
     def __ne__(self, other: object) -> bool:
         return not self.__eq__(other)
 
-    def _attr_seq(self, attrs: str) -> List[str]:
+    def _attr_seq(self, attrs: str) -> list[str]:
         """Return a sequence of attribute strings parsed from `attrs`.
 
         Each attribute string is stripped of whitespace on both ends.
@@ -90,7 +80,7 @@ def _eq_elm_strs(self, line: str, line_2: str):
         return True
 
     @classmethod
-    def _parse_line(cls, line: str) -> Tuple[str, str, str, str]:
+    def _parse_line(cls, line: str) -> tuple[str, str, str, str]:
         """(front, attrs, close, text) 4-tuple result of parsing XML element `line`."""
         match = cls._xml_elm_line_patt.match(line)
         if match is None:
@@ -105,7 +95,7 @@ def _parse_line(cls, line: str) -> Tuple[str, str, str, str]:
 class MetaOxmlElement(type):
     """Metaclass for BaseOxmlElement."""
 
-    def __init__(cls, clsname: str, bases: Tuple[type, ...], namespace: Dict[str, Any]):
+    def __init__(cls, clsname: str, bases: tuple[type, ...], namespace: dict[str, Any]):
         dispatchable = (
             OneAndOnlyOne,
             OneOrMore,
@@ -280,7 +270,7 @@ class _BaseChildElement:
     and ZeroOrMore.
     """
 
-    def __init__(self, nsptagname: str, successors: Tuple[str, ...] = ()):
+    def __init__(self, nsptagname: str, successors: tuple[str, ...] = ()):
         super(_BaseChildElement, self).__init__()
         self._nsptagname = nsptagname
         self._successors = successors
@@ -446,7 +436,7 @@ def populate_class_members(  # pyright: ignore[reportIncompatibleMethodOverride]
         self,
         element_cls: MetaOxmlElement,
         group_prop_name: str,
-        successors: Tuple[str, ...],
+        successors: tuple[str, ...],
     ) -> None:
         """Add the appropriate methods to `element_cls`."""
         self._element_cls = element_cls
@@ -597,7 +587,7 @@ class ZeroOrOneChoice(_BaseChildElement):
     """Correspondes to an ``EG_*`` element group where at most one of its members may
     appear as a child."""
 
-    def __init__(self, choices: Sequence[Choice], successors: Tuple[str, ...] = ()):
+    def __init__(self, choices: Sequence[Choice], successors: tuple[str, ...] = ()):
         self._choices = choices
         self._successors = successors
 
diff --git a/src/docx/parts/document.py b/src/docx/parts/document.py
