rfctr: improve typing

Author: scanny

features/steps/coreprops.py

@@ -3,6 +3,7 @@
 from datetime import datetime, timedelta
 
 from behave import given, then, when
+from behave.runner import Context
 
 from docx import Document
 from docx.opc.coreprops import CoreProperties
@@ -13,25 +14,25 @@
 
 
 @given("a document having known core properties")
-def given_a_document_having_known_core_properties(context):
+def given_a_document_having_known_core_properties(context: Context):
     context.document = Document(test_docx("doc-coreprops"))
 
 
 @given("a document having no core properties part")
-def given_a_document_having_no_core_properties_part(context):
+def given_a_document_having_no_core_properties_part(context: Context):
     context.document = Document(test_docx("doc-no-coreprops"))
 
 
 # when ====================================================
 
 
 @when("I access the core properties object")
-def when_I_access_the_core_properties_object(context):
+def when_I_access_the_core_properties_object(context: Context):
     context.document.core_properties
 
 
 @when("I assign new values to the properties")
-def when_I_assign_new_values_to_the_properties(context):
+def when_I_assign_new_values_to_the_properties(context: Context):
     context.propvals = (
         ("author", "Creator"),
         ("category", "Category"),
@@ -58,7 +59,7 @@ def when_I_assign_new_values_to_the_properties(context):
 
 
 @then("a core properties part with default values is added")
-def then_a_core_properties_part_with_default_values_is_added(context):
+def then_a_core_properties_part_with_default_values_is_added(context: Context):
     core_properties = context.document.core_properties
     assert core_properties.title == "Word Document"
     assert core_properties.last_modified_by == "python-docx"
@@ -71,14 +72,14 @@ def then_a_core_properties_part_with_default_values_is_added(context):
 
 
 @then("I can access the core properties object")
-def then_I_can_access_the_core_properties_object(context):
+def then_I_can_access_the_core_properties_object(context: Context):
     document = context.document
     core_properties = document.core_properties
     assert isinstance(core_properties, CoreProperties)
 
 
 @then("the core property values match the known values")
-def then_the_core_property_values_match_the_known_values(context):
+def then_the_core_property_values_match_the_known_values(context: Context):
     known_propvals = (
         ("author", "Steve Canny"),
         ("category", "Category"),
@@ -106,7 +107,7 @@ def then_the_core_property_values_match_the_known_values(context):
 
 
 @then("the core property values match the new values")
-def then_the_core_property_values_match_the_new_values(context):
+def then_the_core_property_values_match_the_new_values(context: Context):
     core_properties = context.document.core_properties
     for name, expected_value in context.propvals:
         value = getattr(core_properties, name)

src/docx/enum/__init__.py

@@ -1,11 +0,0 @@
-"""Enumerations used in python-docx."""
-
-
-class Enumeration:
-    @classmethod
-    def from_xml(cls, xml_val):
-        return cls._xml_to_idx[xml_val]
-
-    @classmethod
-    def to_xml(cls, enum_val):
-        return cls._idx_to_xml[enum_val]

src/docx/image/image.py

@@ -114,7 +114,7 @@ def height(self) -> Inches:
         return Inches(self.px_height / self.vert_dpi)
 
     def scaled_dimensions(
-        self, width: int | None = None, height: int | None = None
+        self, width: int | Length | None = None, height: int | Length | None = None
     ) -> Tuple[Length, Length]:
         """(cx, cy) pair representing scaled dimensions of this image.
 

src/docx/opc/coreprops.py

@@ -3,44 +3,53 @@
 These are broadly-standardized attributes like author, last-modified, etc.
 """
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docx.oxml.coreprops import CT_CoreProperties
+
+if TYPE_CHECKING:
+    from docx.oxml.coreprops import CT_CoreProperties
+
 
 class CoreProperties:
     """Corresponds to part named ``/docProps/core.xml``, containing the core document
     properties for this document package."""
 
-    def __init__(self, element):
+    def __init__(self, element: CT_CoreProperties):
         self._element = element
 
     @property
     def author(self):
         return self._element.author_text
 
     @author.setter
-    def author(self, value):
+    def author(self, value: str):
         self._element.author_text = value
 
     @property
     def category(self):
         return self._element.category_text
 
     @category.setter
-    def category(self, value):
+    def category(self, value: str):
         self._element.category_text = value
 
     @property
     def comments(self):
         return self._element.comments_text
 
     @comments.setter
-    def comments(self, value):
+    def comments(self, value: str):
         self._element.comments_text = value
 
     @property
     def content_status(self):
         return self._element.contentStatus_text
 
     @content_status.setter
-    def content_status(self, value):
+    def content_status(self, value: str):
         self._element.contentStatus_text = value
 
     @property
@@ -56,31 +65,31 @@ def identifier(self):
         return self._element.identifier_text
 
     @identifier.setter
-    def identifier(self, value):
+    def identifier(self, value: str):
         self._element.identifier_text = value
 
     @property
     def keywords(self):
         return self._element.keywords_text
 
     @keywords.setter
-    def keywords(self, value):
+    def keywords(self, value: str):
         self._element.keywords_text = value
 
     @property
     def language(self):
         return self._element.language_text
 
     @language.setter
-    def language(self, value):
+    def language(self, value: str):
         self._element.language_text = value
 
     @property
     def last_modified_by(self):
         return self._element.lastModifiedBy_text
 
     @last_modified_by.setter
-    def last_modified_by(self, value):
+    def last_modified_by(self, value: str):
         self._element.lastModifiedBy_text = value
 
     @property
@@ -112,21 +121,21 @@ def subject(self):
         return self._element.subject_text
 
     @subject.setter
-    def subject(self, value):
+    def subject(self, value: str):
         self._element.subject_text = value
 
     @property
     def title(self):
         return self._element.title_text
 
     @title.setter
-    def title(self, value):
+    def title(self, value: str):
         self._element.title_text = value
 
     @property
     def version(self):
         return self._element.version_text
 
     @version.setter
-    def version(self, value):
+    def version(self, value: str):
         self._element.version_text = value

src/docx/opc/oxml.py

@@ -7,6 +7,10 @@
 deleted or only hold the package related custom element classes.
 """
 
+from __future__ import annotations
+
+from typing import cast
+
 from lxml import etree
 
 from docx.opc.constants import NAMESPACE as NS
@@ -138,7 +142,7 @@ class CT_Relationship(BaseOxmlElement):
     target part."""
 
     @staticmethod
-    def new(rId, reltype, target, target_mode=RTM.INTERNAL):
+    def new(rId: str, reltype: str, target: str, target_mode: str = RTM.INTERNAL):
         """Return a new ``<Relationship>`` element."""
         xml = '<Relationship xmlns="%s"/>' % nsmap["pr"]
         relationship = parse_xml(xml)
@@ -178,19 +182,18 @@ def target_mode(self):
 class CT_Relationships(BaseOxmlElement):
     """``<Relationships>`` element, the root element in a .rels file."""
 
-    def add_rel(self, rId, reltype, target, is_external=False):
+    def add_rel(self, rId: str, reltype: str, target: str, is_external: bool = False):
         """Add a child ``<Relationship>`` element with attributes set according to
         parameter values."""
         target_mode = RTM.EXTERNAL if is_external else RTM.INTERNAL
         relationship = CT_Relationship.new(rId, reltype, target, target_mode)
         self.append(relationship)
 
     @staticmethod
-    def new():
+    def new() -> CT_Relationships:
         """Return a new ``<Relationships>`` element."""
         xml = '<Relationships xmlns="%s"/>' % nsmap["pr"]
-        relationships = parse_xml(xml)
-        return relationships
+        return cast(CT_Relationships, parse_xml(xml))
 
     @property
     def Relationship_lst(self):

src/docx/opc/package.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import IO, TYPE_CHECKING, Iterator
+from typing import IO, TYPE_CHECKING, Iterator, cast
 
 from docx.opc.constants import RELATIONSHIP_TYPE as RT
 from docx.opc.packuri import PACKAGE_URI, PackURI
@@ -14,7 +14,9 @@
 from docx.shared import lazyproperty
 
 if TYPE_CHECKING:
+    from docx.opc.coreprops import CoreProperties
     from docx.opc.part import Part
+    from docx.opc.rel import _Relationship  # pyright: ignore[reportPrivateUsage]
 
 
 class OpcPackage:
@@ -37,16 +39,18 @@ def after_unmarshal(self):
         pass
 
     @property
-    def core_properties(self):
+    def core_properties(self) -> CoreProperties:
         """|CoreProperties| object providing read/write access to the Dublin Core
         properties for this document."""
         return self._core_properties_part.core_properties
 
-    def iter_rels(self):
+    def iter_rels(self) -> Iterator[_Relationship]:
         """Generate exactly one reference to each relationship in the package by
         performing a depth-first traversal of the rels graph."""
 
-        def walk_rels(source, visited=None):
+        def walk_rels(
+            source: OpcPackage | Part, visited: list[Part] | None = None
+        ) -> Iterator[_Relationship]:
             visited = [] if visited is None else visited
             for rel in source.rels.values():
                 yield rel
@@ -103,7 +107,7 @@ def main_document_part(self):
         """
         return self.part_related_by(RT.OFFICE_DOCUMENT)
 
-    def next_partname(self, template):
+    def next_partname(self, template: str) -> PackURI:
         """Return a |PackURI| instance representing partname matching `template`.
 
         The returned part-name has the next available numeric suffix to distinguish it
@@ -163,13 +167,13 @@ def save(self, pkg_file: str | IO[bytes]):
         PackageWriter.write(pkg_file, self.rels, self.parts)
 
     @property
-    def _core_properties_part(self):
+    def _core_properties_part(self) -> CorePropertiesPart:
         """|CorePropertiesPart| object related to this package.
 
         Creates a default core properties part if one is not present (not common).
         """
         try:
-            return self.part_related_by(RT.CORE_PROPERTIES)
+            return cast(CorePropertiesPart, self.part_related_by(RT.CORE_PROPERTIES))
         except KeyError:
             core_properties_part = CorePropertiesPart.default(self)
             self.relate_to(core_properties_part, RT.CORE_PROPERTIES)

src/docx/opc/packuri.py

@@ -3,6 +3,8 @@
 Also some useful known pack URI strings such as PACKAGE_URI.
 """
 
+from __future__ import annotations
+
 import posixpath
 import re
 
@@ -16,22 +18,21 @@ class PackURI(str):
 
     _filename_re = re.compile("([a-zA-Z]+)([1-9][0-9]*)?")
 
-    def __new__(cls, pack_uri_str):
+    def __new__(cls, pack_uri_str: str):
         if pack_uri_str[0] != "/":
             tmpl = "PackURI must begin with slash, got '%s'"
             raise ValueError(tmpl % pack_uri_str)
         return str.__new__(cls, pack_uri_str)
 
     @staticmethod
-    def from_rel_ref(baseURI, relative_ref):
-        """Return a |PackURI| instance containing the absolute pack URI formed by
-        translating `relative_ref` onto `baseURI`."""
+    def from_rel_ref(baseURI: str, relative_ref: str) -> PackURI:
+        """The absolute PackURI formed by translating `relative_ref` onto `baseURI`."""
         joined_uri = posixpath.join(baseURI, relative_ref)
         abs_uri = posixpath.abspath(joined_uri)
         return PackURI(abs_uri)
 
     @property
-    def baseURI(self):
+    def baseURI(self) -> str:
         """The base URI of this pack URI, the directory portion, roughly speaking.
 
         E.g. ``'/ppt/slides'`` for ``'/ppt/slides/slide1.xml'``. For the package pseudo-
@@ -40,9 +41,8 @@ def baseURI(self):
         return posixpath.split(self)[0]
 
     @property
-    def ext(self):
-        """The extension portion of this pack URI, e.g. ``'xml'`` for
-        ``'/word/document.xml'``.
+    def ext(self) -> str:
+        """The extension portion of this pack URI, e.g. ``'xml'`` for ``'/word/document.xml'``.
 
         Note the period is not included.
         """
@@ -84,7 +84,7 @@ def membername(self):
         """
         return self[1:]
 
-    def relative_ref(self, baseURI):
+    def relative_ref(self, baseURI: str):
         """Return string containing relative reference to package item from `baseURI`.
 
         E.g. PackURI('/ppt/slideLayouts/slideLayout1.xml') would return

src/docx/opc/part.py

@@ -1,8 +1,10 @@
+# pyright: reportImportCycles=false
+
 """Open Packaging Convention (OPC) objects related to package parts."""
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Callable, Dict, Type, cast
+from typing import TYPE_CHECKING, Callable, Type, cast
 
 from docx.opc.oxml import serialize_part_xml
 from docx.opc.packuri import PackURI
@@ -12,6 +14,7 @@
 from docx.shared import lazyproperty
 
 if TYPE_CHECKING:
+    from docx.oxml.xmlchemy import BaseOxmlElement
     from docx.package import Package
 
 
@@ -24,7 +27,7 @@ class Part:
 
     def __init__(
         self,
-        partname: str,
+        partname: PackURI,
         content_type: str,
         blob: bytes | None = None,
         package: Package | None = None,
@@ -56,13 +59,13 @@ def before_marshal(self):
         pass
 
     @property
-    def blob(self):
+    def blob(self) -> bytes:
         """Contents of this package part as a sequence of bytes.
 
         May be text or binary. Intended to be overridden by subclasses. Default behavior
         is to return load blob.
         """
-        return self._blob
+        return self._blob or b""
 
     @property
     def content_type(self):
@@ -79,7 +82,7 @@ def drop_rel(self, rId: str):
             del self.rels[rId]
 
     @classmethod
-    def load(cls, partname: str, content_type: str, blob: bytes, package: Package):
+    def load(cls, partname: PackURI, content_type: str, blob: bytes, package: Package):
         return cls(partname, content_type, blob, package)
 
     def load_rel(self, reltype: str, target: Part | str, rId: str, is_external: bool = False):
@@ -105,7 +108,7 @@ def partname(self):
         return self._partname
 
     @partname.setter
-    def partname(self, partname):
+    def partname(self, partname: str):
         if not isinstance(partname, PackURI):
             tmpl = "partname must be instance of PackURI, got '%s'"
             raise TypeError(tmpl % type(partname).__name__)
@@ -127,9 +130,9 @@ def relate_to(self, target: Part | str, reltype: str, is_external: bool = False)
         new relationship is created.
         """
         if is_external:
-            return self.rels.get_or_add_ext_rel(reltype, target)
+            return self.rels.get_or_add_ext_rel(reltype, cast(str, target))
         else:
-            rel = self.rels.get_or_add(reltype, target)
+            rel = self.rels.get_or_add(reltype, cast(Part, target))
             return rel.rId
 
     @property
@@ -171,12 +174,12 @@ class PartFactory:
     """
 
     part_class_selector: Callable[[str, str], Type[Part] | None] | None
-    part_type_for: Dict[str, Type[Part]] = {}
+    part_type_for: dict[str, Type[Part]] = {}
     default_part_type = Part
 
     def __new__(
         cls,
-        partname: str,
+        partname: PackURI,
         content_type: str,
         reltype: str,
         blob: bytes,
@@ -206,7 +209,9 @@ class XmlPart(Part):
     reserializing the XML payload and managing relationships to other parts.
     """
 
-    def __init__(self, partname, content_type, element, package):
+    def __init__(
+        self, partname: PackURI, content_type: str, element: BaseOxmlElement, package: Package
+    ):
         super(XmlPart, self).__init__(partname, content_type, package=package)
         self._element = element
 
@@ -220,7 +225,7 @@ def element(self):
         return self._element
 
     @classmethod
-    def load(cls, partname, content_type, blob, package):
+    def load(cls, partname: PackURI, content_type: str, blob: bytes, package: Package):
         element = parse_xml(blob)
         return cls(partname, content_type, element, package)
 

src/docx/opc/parts/coreprops.py

@@ -1,28 +1,37 @@
 """Core properties part, corresponds to ``/docProps/core.xml`` part in package."""
 
-from datetime import datetime
+from __future__ import annotations
+
+import datetime as dt
+from typing import TYPE_CHECKING
 
 from docx.opc.constants import CONTENT_TYPE as CT
 from docx.opc.coreprops import CoreProperties
 from docx.opc.packuri import PackURI
 from docx.opc.part import XmlPart
 from docx.oxml.coreprops import CT_CoreProperties
 
+if TYPE_CHECKING:
+    from docx.opc.package import OpcPackage
+
 
 class CorePropertiesPart(XmlPart):
-    """Corresponds to part named ``/docProps/core.xml``, containing the core document
-    properties for this document package."""
+    """Corresponds to part named ``/docProps/core.xml``.
+
+    The "core" is short for "Dublin Core" and contains document metadata relatively common across
+    documents of all types, not just DOCX.
+    """
 
     @classmethod
-    def default(cls, package):
+    def default(cls, package: OpcPackage):
         """Return a new |CorePropertiesPart| object initialized with default values for
         its base properties."""
         core_properties_part = cls._new(package)
         core_properties = core_properties_part.core_properties
         core_properties.title = "Word Document"
         core_properties.last_modified_by = "python-docx"
         core_properties.revision = 1
-        core_properties.modified = datetime.utcnow()
+        core_properties.modified = dt.datetime.utcnow()
         return core_properties_part
 
     @property
@@ -32,7 +41,7 @@ def core_properties(self):
         return CoreProperties(self.element)
 
     @classmethod
-    def _new(cls, package):
+    def _new(cls, package: OpcPackage) -> CorePropertiesPart:
         partname = PackURI("/docProps/core.xml")
         content_type = CT.OPC_CORE_PROPERTIES
         coreProperties = CT_CoreProperties.new()

src/docx/opc/rel.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Dict
+from typing import TYPE_CHECKING, Any, Dict, cast
 
 from docx.opc.oxml import CT_Relationships
 
@@ -16,7 +16,7 @@ class Relationships(Dict[str, "_Relationship"]):
     def __init__(self, baseURI: str):
         super(Relationships, self).__init__()
         self._baseURI = baseURI
-        self._target_parts_by_rId: Dict[str, Any] = {}
+        self._target_parts_by_rId: dict[str, Any] = {}
 
     def add_relationship(
         self, reltype: str, target: Part | str, rId: str, is_external: bool = False
@@ -37,7 +37,7 @@ def get_or_add(self, reltype: str, target_part: Part) -> _Relationship:
             rel = self.add_relationship(reltype, target_part, rId)
         return rel
 
-    def get_or_add_ext_rel(self, reltype, target_ref):
+    def get_or_add_ext_rel(self, reltype: str, target_ref: str) -> str:
         """Return rId of external relationship of `reltype` to `target_ref`, newly added
         if not already present in collection."""
         rel = self._get_matching(reltype, target_ref, is_external=True)
@@ -46,7 +46,7 @@ def get_or_add_ext_rel(self, reltype, target_ref):
             rel = self.add_relationship(reltype, target_ref, rId, is_external=True)
         return rel.rId
 
-    def part_with_reltype(self, reltype):
+    def part_with_reltype(self, reltype: str) -> Part:
         """Return target part of rel with matching `reltype`, raising |KeyError| if not
         found and |ValueError| if more than one matching relationship is found."""
         rel = self._get_rel_of_type(reltype)
@@ -59,7 +59,7 @@ def related_parts(self):
         return self._target_parts_by_rId
 
     @property
-    def xml(self):
+    def xml(self) -> str:
         """Serialize this relationship collection into XML suitable for storage as a
         .rels file in an OPC package."""
         rels_elm = CT_Relationships.new()
@@ -73,7 +73,7 @@ def _get_matching(
         """Return relationship of matching `reltype`, `target`, and `is_external` from
         collection, or None if not found."""
 
-        def matches(rel, reltype, target, is_external):
+        def matches(rel: _Relationship, reltype: str, target: Part | str, is_external: bool):
             if rel.reltype != reltype:
                 return False
             if rel.is_external != is_external:
@@ -88,7 +88,7 @@ def matches(rel, reltype, target, is_external):
                 return rel
         return None
 
-    def _get_rel_of_type(self, reltype):
+    def _get_rel_of_type(self, reltype: str):
         """Return single relationship of type `reltype` from the collection.
 
         Raises |KeyError| if no matching relationship is found. Raises |ValueError| if
@@ -104,7 +104,7 @@ def _get_rel_of_type(self, reltype):
         return matching[0]
 
     @property
-    def _next_rId(self) -> str:
+    def _next_rId(self) -> str:  # pyright: ignore[reportReturnType]
         """Next available rId in collection, starting from 'rId1' and making use of any
         gaps in numbering, e.g. 'rId2' for rIds ['rId1', 'rId3']."""
         for n in range(1, len(self) + 2):
@@ -116,7 +116,9 @@ def _next_rId(self) -> str:
 class _Relationship:
     """Value object for relationship to part."""
 
-    def __init__(self, rId: str, reltype, target, baseURI, external=False):
+    def __init__(
+        self, rId: str, reltype: str, target: Part | str, baseURI: str, external: bool = False
+    ):
         super(_Relationship, self).__init__()
         self._rId = rId
         self._reltype = reltype
@@ -125,28 +127,29 @@ def __init__(self, rId: str, reltype, target, baseURI, external=False):
         self._is_external = bool(external)
 
     @property
-    def is_external(self):
+    def is_external(self) -> bool:
         return self._is_external
 
     @property
-    def reltype(self):
+    def reltype(self) -> str:
         return self._reltype
 
     @property
-    def rId(self):
+    def rId(self) -> str:
         return self._rId
 
     @property
-    def target_part(self):
+    def target_part(self) -> Part:
         if self._is_external:
             raise ValueError(
                 "target_part property on _Relationship is undef" "ined when target mode is External"
             )
-        return self._target
+        return cast("Part", self._target)
 
     @property
     def target_ref(self) -> str:
         if self._is_external:
-            return self._target
+            return cast(str, self._target)
         else:
-            return self._target.partname.relative_ref(self._baseURI)
+            target = cast("Part", self._target)
+            return target.partname.relative_ref(self._baseURI)

src/docx/oxml/coreprops.py

@@ -1,13 +1,18 @@
 """Custom element classes for core properties-related XML elements."""
 
+from __future__ import annotations
+
+import datetime as dt
 import re
-from datetime import datetime, timedelta
-from typing import Any
+from typing import TYPE_CHECKING, Any, Callable
 
 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 lxml.etree import _Element as etree_Element  # pyright: ignore[reportPrivateUsage]
+
 
 class CT_CoreProperties(BaseOxmlElement):
     """`<cp:coreProperties>` element, the root element of the Core Properties part.
@@ -17,6 +22,8 @@ class CT_CoreProperties(BaseOxmlElement):
     present in the XML. String elements are limited in length to 255 unicode characters.
     """
 
+    get_or_add_revision: Callable[[], etree_Element]
+
     category = ZeroOrOne("cp:category", successors=())
     contentStatus = ZeroOrOne("cp:contentStatus", successors=())
     created = ZeroOrOne("dcterms:created", successors=())
@@ -28,7 +35,9 @@ class CT_CoreProperties(BaseOxmlElement):
     lastModifiedBy = ZeroOrOne("cp:lastModifiedBy", successors=())
     lastPrinted = ZeroOrOne("cp:lastPrinted", successors=())
     modified = ZeroOrOne("dcterms:modified", successors=())
-    revision = ZeroOrOne("cp:revision", successors=())
+    revision: etree_Element | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "cp:revision", successors=()
+    )
     subject = ZeroOrOne("dc:subject", successors=())
     title = ZeroOrOne("dc:title", successors=())
     version = ZeroOrOne("cp:version", successors=())
@@ -80,55 +89,55 @@ def created_datetime(self):
         return self._datetime_of_element("created")
 
     @created_datetime.setter
-    def created_datetime(self, value):
+    def created_datetime(self, value: dt.datetime):
         self._set_element_datetime("created", value)
 
     @property
     def identifier_text(self):
         return self._text_of_element("identifier")
 
     @identifier_text.setter
-    def identifier_text(self, value):
+    def identifier_text(self, value: str):
         self._set_element_text("identifier", value)
 
     @property
     def keywords_text(self):
         return self._text_of_element("keywords")
 
     @keywords_text.setter
-    def keywords_text(self, value):
+    def keywords_text(self, value: str):
         self._set_element_text("keywords", value)
 
     @property
     def language_text(self):
         return self._text_of_element("language")
 
     @language_text.setter
-    def language_text(self, value):
+    def language_text(self, value: str):
         self._set_element_text("language", value)
 
     @property
     def lastModifiedBy_text(self):
         return self._text_of_element("lastModifiedBy")
 
     @lastModifiedBy_text.setter
-    def lastModifiedBy_text(self, value):
+    def lastModifiedBy_text(self, value: str):
         self._set_element_text("lastModifiedBy", value)
 
     @property
     def lastPrinted_datetime(self):
         return self._datetime_of_element("lastPrinted")
 
     @lastPrinted_datetime.setter
-    def lastPrinted_datetime(self, value):
+    def lastPrinted_datetime(self, value: dt.datetime):
         self._set_element_datetime("lastPrinted", value)
 
     @property
-    def modified_datetime(self):
+    def modified_datetime(self) -> dt.datetime | None:
         return self._datetime_of_element("modified")
 
     @modified_datetime.setter
-    def modified_datetime(self, value):
+    def modified_datetime(self, value: dt.datetime):
         self._set_element_datetime("modified", value)
 
     @property
@@ -137,7 +146,7 @@ def revision_number(self):
         revision = self.revision
         if revision is None:
             return 0
-        revision_str = revision.text
+        revision_str = str(revision.text)
         try:
             revision = int(revision_str)
         except ValueError:
@@ -149,9 +158,9 @@ def revision_number(self):
         return revision
 
     @revision_number.setter
-    def revision_number(self, value):
+    def revision_number(self, value: int):
         """Set revision property to string value of integer `value`."""
-        if not isinstance(value, int) or value < 1:
+        if not isinstance(value, int) or value < 1:  # pyright: ignore[reportUnnecessaryIsInstance]
             tmpl = "revision property requires positive int, got '%s'"
             raise ValueError(tmpl % value)
         revision = self.get_or_add_revision()
@@ -162,26 +171,26 @@ def subject_text(self):
         return self._text_of_element("subject")
 
     @subject_text.setter
-    def subject_text(self, value):
+    def subject_text(self, value: str):
         self._set_element_text("subject", value)
 
     @property
     def title_text(self):
         return self._text_of_element("title")
 
     @title_text.setter
-    def title_text(self, value):
+    def title_text(self, value: str):
         self._set_element_text("title", value)
 
     @property
     def version_text(self):
         return self._text_of_element("version")
 
     @version_text.setter
-    def version_text(self, value):
+    def version_text(self, value: str):
         self._set_element_text("version", value)
 
-    def _datetime_of_element(self, property_name):
+    def _datetime_of_element(self, property_name: str) -> dt.datetime | None:
         element = getattr(self, property_name)
         if element is None:
             return None
@@ -192,16 +201,16 @@ def _datetime_of_element(self, property_name):
             # invalid datetime strings are ignored
             return None
 
-    def _get_or_add(self, prop_name):
+    def _get_or_add(self, prop_name: str) -> BaseOxmlElement:
         """Return element returned by "get_or_add_" method for `prop_name`."""
         get_or_add_method_name = "get_or_add_%s" % prop_name
         get_or_add_method = getattr(self, get_or_add_method_name)
         element = get_or_add_method()
         return element
 
     @classmethod
-    def _offset_dt(cls, dt, offset_str):
-        """A |datetime| instance offset from `dt` by timezone offset in `offset_str`.
+    def _offset_dt(cls, dt_: dt.datetime, offset_str: str) -> dt.datetime:
+        """A |datetime| instance offset from `dt_` by timezone offset in `offset_str`.
 
         `offset_str` is like `"-07:00"`.
         """
@@ -212,13 +221,13 @@ def _offset_dt(cls, dt, offset_str):
         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
+        td = dt.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):
+    def _parse_W3CDTF_to_datetime(cls, w3cdtf_str: str) -> dt.datetime:
         # valid W3CDTF date cases:
         # yyyy e.g. "2003"
         # yyyy-mm e.g. "2003-12"
@@ -235,22 +244,22 @@ def _parse_W3CDTF_to_datetime(cls, w3cdtf_str):
         # "-07:30", so we have to do it ourselves
         parseable_part = w3cdtf_str[:19]
         offset_str = w3cdtf_str[19:]
-        dt = None
+        dt_ = None
         for tmpl in templates:
             try:
-                dt = datetime.strptime(parseable_part, tmpl)
+                dt_ = dt.datetime.strptime(parseable_part, tmpl)
             except ValueError:
                 continue
-        if dt is None:
+        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
+            return cls._offset_dt(dt_, offset_str)
+        return dt_
 
-    def _set_element_datetime(self, prop_name, value):
+    def _set_element_datetime(self, prop_name: str, value: dt.datetime):
         """Set date/time value of child element having `prop_name` to `value`."""
-        if not isinstance(value, datetime):
+        if not isinstance(value, dt.datetime):  # pyright: ignore[reportUnnecessaryIsInstance]
             tmpl = "property requires <type 'datetime.datetime'> object, got %s"
             raise ValueError(tmpl % type(value))
         element = self._get_or_add(prop_name)

src/docx/oxml/document.py

@@ -15,7 +15,7 @@
 class CT_Document(BaseOxmlElement):
     """``<w:document>`` element, the root element of a document.xml file."""
 
-    body = ZeroOrOne("w:body")
+    body: CT_Body = ZeroOrOne("w:body")  # pyright: ignore[reportAssignmentType]
 
     @property
     def sectPr_lst(self) -> List[CT_SectPr]:

src/docx/oxml/parser.py

@@ -20,7 +20,7 @@
 oxml_parser.set_element_class_lookup(element_class_lookup)
 
 
-def parse_xml(xml: str) -> "BaseOxmlElement":
+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

src/docx/oxml/settings.py

@@ -1,11 +1,21 @@
 """Custom element classes related to document settings."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable
+
 from docx.oxml.xmlchemy import BaseOxmlElement, ZeroOrOne
 
+if TYPE_CHECKING:
+    from docx.oxml.shared import CT_OnOff
+
 
 class CT_Settings(BaseOxmlElement):
     """`w:settings` element, root element for the settings part."""
 
+    get_or_add_evenAndOddHeaders: Callable[[], CT_OnOff]
+    _remove_evenAndOddHeaders: Callable[[], None]
+
     _tag_seq = (
         "w:writeProtection",
         "w:view",
@@ -106,20 +116,23 @@ class CT_Settings(BaseOxmlElement):
         "w:decimalSymbol",
         "w:listSeparator",
     )
-    evenAndOddHeaders = ZeroOrOne("w:evenAndOddHeaders", successors=_tag_seq[48:])
+    evenAndOddHeaders: CT_OnOff | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "w:evenAndOddHeaders", successors=_tag_seq[48:]
+    )
     del _tag_seq
 
     @property
-    def evenAndOddHeaders_val(self):
+    def evenAndOddHeaders_val(self) -> bool:
         """Value of `w:evenAndOddHeaders/@w:val` or |None| if not present."""
         evenAndOddHeaders = self.evenAndOddHeaders
         if evenAndOddHeaders is None:
             return False
         return evenAndOddHeaders.val
 
     @evenAndOddHeaders_val.setter
-    def evenAndOddHeaders_val(self, value):
-        if value in [None, False]:
+    def evenAndOddHeaders_val(self, value: bool | None):
+        if value is None or value is False:
             self._remove_evenAndOddHeaders()
-        else:
-            self.get_or_add_evenAndOddHeaders().val = value
+            return
+
+        self.get_or_add_evenAndOddHeaders().val = value

src/docx/oxml/shape.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 from docx.oxml.ns import nsdecls
 from docx.oxml.parser import parse_xml
@@ -34,48 +34,58 @@ class CT_Blip(BaseOxmlElement):
     """``<a:blip>`` element, specifies image source and adjustments such as alpha and
     tint."""
 
-    embed = OptionalAttribute("r:embed", ST_RelationshipId)
-    link = OptionalAttribute("r:link", ST_RelationshipId)
+    embed: str | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
+        "r:embed", ST_RelationshipId
+    )
+    link: str | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
+        "r:link", ST_RelationshipId
+    )
 
 
 class CT_BlipFillProperties(BaseOxmlElement):
     """``<pic:blipFill>`` element, specifies picture properties."""
 
-    blip = ZeroOrOne("a:blip", successors=("a:srcRect", "a:tile", "a:stretch"))
+    blip: CT_Blip = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "a:blip", successors=("a:srcRect", "a:tile", "a:stretch")
+    )
 
 
 class CT_GraphicalObject(BaseOxmlElement):
     """``<a:graphic>`` element, container for a DrawingML object."""
 
-    graphicData = OneAndOnlyOne("a:graphicData")
+    graphicData: CT_GraphicalObjectData = OneAndOnlyOne(  # pyright: ignore[reportAssignmentType]
+        "a:graphicData"
+    )
 
 
 class CT_GraphicalObjectData(BaseOxmlElement):
     """``<a:graphicData>`` element, container for the XML of a DrawingML object."""
 
-    pic = ZeroOrOne("pic:pic")
-    uri = RequiredAttribute("uri", XsdToken)
+    pic: CT_Picture = ZeroOrOne("pic:pic")  # pyright: ignore[reportAssignmentType]
+    uri: str = RequiredAttribute("uri", XsdToken)  # pyright: ignore[reportAssignmentType]
 
 
 class CT_Inline(BaseOxmlElement):
     """`<wp:inline>` element, container for an inline shape."""
 
-    extent = OneAndOnlyOne("wp:extent")
-    docPr = OneAndOnlyOne("wp:docPr")
-    graphic = OneAndOnlyOne("a:graphic")
+    extent: CT_PositiveSize2D = OneAndOnlyOne("wp:extent")  # pyright: ignore[reportAssignmentType]
+    docPr: CT_NonVisualDrawingProps = OneAndOnlyOne(  # pyright: ignore[reportAssignmentType]
+        "wp:docPr"
+    )
+    graphic: CT_GraphicalObject = OneAndOnlyOne(  # pyright: ignore[reportAssignmentType]
+        "a:graphic"
+    )
 
     @classmethod
     def new(cls, cx: Length, cy: Length, shape_id: int, pic: CT_Picture) -> CT_Inline:
         """Return a new ``<wp:inline>`` element populated with the values passed as
         parameters."""
-        inline = parse_xml(cls._inline_xml())
+        inline = cast(CT_Inline, parse_xml(cls._inline_xml()))
         inline.extent.cx = cx
         inline.extent.cy = cy
         inline.docPr.id = shape_id
         inline.docPr.name = "Picture %d" % shape_id
-        inline.graphic.graphicData.uri = (
-            "http://schemas.openxmlformats.org/drawingml/2006/picture"
-        )
+        inline.graphic.graphicData.uri = "http://schemas.openxmlformats.org/drawingml/2006/picture"
         inline.graphic.graphicData._insert_pic(pic)
         return inline
 
@@ -126,9 +136,13 @@ class CT_NonVisualPictureProperties(BaseOxmlElement):
 class CT_Picture(BaseOxmlElement):
     """``<pic:pic>`` element, a DrawingML picture."""
 
-    nvPicPr = OneAndOnlyOne("pic:nvPicPr")
-    blipFill = OneAndOnlyOne("pic:blipFill")
-    spPr = OneAndOnlyOne("pic:spPr")
+    nvPicPr: CT_PictureNonVisual = OneAndOnlyOne(  # pyright: ignore[reportAssignmentType]
+        "pic:nvPicPr"
+    )
+    blipFill: CT_BlipFillProperties = OneAndOnlyOne(  # pyright: ignore[reportAssignmentType]
+        "pic:blipFill"
+    )
+    spPr: CT_ShapeProperties = OneAndOnlyOne("pic:spPr")  # pyright: ignore[reportAssignmentType]
 
     @classmethod
     def new(cls, pic_id, filename, rId, cx, cy):
@@ -190,8 +204,12 @@ class CT_PositiveSize2D(BaseOxmlElement):
     Specifies the size of a DrawingML drawing.
     """
 
-    cx = RequiredAttribute("cx", ST_PositiveCoordinate)
-    cy = RequiredAttribute("cy", ST_PositiveCoordinate)
+    cx: Length = RequiredAttribute(  # pyright: ignore[reportAssignmentType]
+        "cx", ST_PositiveCoordinate
+    )
+    cy: Length = RequiredAttribute(  # pyright: ignore[reportAssignmentType]
+        "cy", ST_PositiveCoordinate
+    )
 
 
 class CT_PresetGeometry2D(BaseOxmlElement):

src/docx/oxml/shared.py

@@ -18,7 +18,7 @@ class CT_DecimalNumber(BaseOxmlElement):
     val: int = RequiredAttribute("w:val", ST_DecimalNumber)  # pyright: ignore[reportAssignmentType]
 
     @classmethod
-    def new(cls, nsptagname, val):
+    def new(cls, nsptagname: str, val: int):
         """Return a new ``CT_DecimalNumber`` element having tagname `nsptagname` and
         ``val`` attribute set to `val`."""
         return OxmlElement(nsptagname, attrs={qn("w:val"): str(val)})
@@ -31,7 +31,7 @@ class CT_OnOff(BaseOxmlElement):
     "off". Defaults to `True`, so `<w:b>` for example means "bold is turned on".
     """
 
-    val: bool = OptionalAttribute(  # pyright: ignore[reportGeneralTypeIssues]
+    val: bool = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
         "w:val", ST_OnOff, default=True
     )
 
@@ -42,7 +42,7 @@ class CT_String(BaseOxmlElement):
     In those cases, it containing a style name in its `val` attribute.
     """
 
-    val: str = RequiredAttribute("w:val", ST_String)  # pyright: ignore[reportGeneralTypeIssues]
+    val: str = RequiredAttribute("w:val", ST_String)  # pyright: ignore[reportAssignmentType]
 
     @classmethod
     def new(cls, nsptagname: str, val: str):

src/docx/oxml/styles.py

@@ -128,12 +128,10 @@ class CT_Style(BaseOxmlElement):
     rPr = ZeroOrOne("w:rPr", successors=_tag_seq[18:])
     del _tag_seq
 
-    type: WD_STYLE_TYPE | None = (
-        OptionalAttribute(  # pyright: ignore[reportGeneralTypeIssues]
-            "w:type", WD_STYLE_TYPE
-        )
+    type: WD_STYLE_TYPE | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
+        "w:type", WD_STYLE_TYPE
     )
-    styleId: str | None = OptionalAttribute(  # pyright: ignore[reportGeneralTypeIssues]
+    styleId: str | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
         "w:styleId", ST_String
     )
     default = OptionalAttribute("w:default", ST_OnOff)

src/docx/oxml/table.py

@@ -973,5 +973,5 @@ class CT_VMerge(BaseOxmlElement):
     """``<w:vMerge>`` element, specifying vertical merging behavior of a cell."""
 
     val: str | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
-        "w:val", ST_Merge, default=ST_Merge.CONTINUE  # pyright: ignore[reportArgumentType]
+        "w:val", ST_Merge, default=ST_Merge.CONTINUE
     )

src/docx/oxml/text/font.py

@@ -39,10 +39,10 @@ class CT_Fonts(BaseOxmlElement):
     Specifies typeface name for the various language types.
     """
 
-    ascii: str | None = OptionalAttribute(  # pyright: ignore[reportGeneralTypeIssues]
+    ascii: str | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
         "w:ascii", ST_String
     )
-    hAnsi: str | None = OptionalAttribute(  # pyright: ignore[reportGeneralTypeIssues]
+    hAnsi: str | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
         "w:hAnsi", ST_String
     )
 
@@ -148,18 +148,14 @@ class CT_RPr(BaseOxmlElement):
     sz: CT_HpsMeasure | None = ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
         "w:sz", successors=_tag_seq[24:]
     )
-    highlight: CT_Highlight | None = (
-        ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
-            "w:highlight", successors=_tag_seq[26:]
-        )
+    highlight: CT_Highlight | None = ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
+        "w:highlight", successors=_tag_seq[26:]
     )
     u: CT_Underline | None = ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
         "w:u", successors=_tag_seq[27:]
     )
-    vertAlign: CT_VerticalAlignRun | None = (
-        ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
-            "w:vertAlign", successors=_tag_seq[32:]
-        )
+    vertAlign: CT_VerticalAlignRun | None = ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
+        "w:vertAlign", successors=_tag_seq[32:]
     )
     rtl = ZeroOrOne("w:rtl", successors=_tag_seq[33:])
     cs = ZeroOrOne("w:cs", successors=_tag_seq[34:])
@@ -268,10 +264,7 @@ def subscript(self, value: bool | None) -> None:
         elif bool(value) is True:
             self.get_or_add_vertAlign().val = ST_VerticalAlignRun.SUBSCRIPT
         # -- assert bool(value) is False --
-        elif (
-            self.vertAlign is not None
-            and self.vertAlign.val == ST_VerticalAlignRun.SUBSCRIPT
-        ):
+        elif self.vertAlign is not None and self.vertAlign.val == ST_VerticalAlignRun.SUBSCRIPT:
             self._remove_vertAlign()
 
     @property
@@ -295,10 +288,7 @@ def superscript(self, value: bool | None):
         elif bool(value) is True:
             self.get_or_add_vertAlign().val = ST_VerticalAlignRun.SUPERSCRIPT
         # -- assert bool(value) is False --
-        elif (
-            self.vertAlign is not None
-            and self.vertAlign.val == ST_VerticalAlignRun.SUPERSCRIPT
-        ):
+        elif self.vertAlign is not None and self.vertAlign.val == ST_VerticalAlignRun.SUPERSCRIPT:
             self._remove_vertAlign()
 
     @property
@@ -353,10 +343,8 @@ def _set_bool_val(self, name: str, value: bool | None):
 class CT_Underline(BaseOxmlElement):
     """`<w:u>` element, specifying the underlining style for a run."""
 
-    val: WD_UNDERLINE | None = (
-        OptionalAttribute(  # pyright: ignore[reportGeneralTypeIssues]
-            "w:val", WD_UNDERLINE
-        )
+    val: WD_UNDERLINE | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
+        "w:val", WD_UNDERLINE
     )
 
 

src/docx/package.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import IO
+from typing import IO, cast
 
 from docx.image.image import Image
 from docx.opc.constants import RELATIONSHIP_TYPE as RT
@@ -44,16 +44,16 @@ def _gather_image_parts(self):
                 continue
             if rel.target_part in self.image_parts:
                 continue
-            self.image_parts.append(rel.target_part)
+            self.image_parts.append(cast("ImagePart", rel.target_part))
 
 
 class ImageParts:
     """Collection of |ImagePart| objects corresponding to images in the package."""
 
     def __init__(self):
-        self._image_parts = []
+        self._image_parts: list[ImagePart] = []
 
-    def __contains__(self, item):
+    def __contains__(self, item: object):
         return self._image_parts.__contains__(item)
 
     def __iter__(self):
@@ -62,7 +62,7 @@ def __iter__(self):
     def __len__(self):
         return self._image_parts.__len__()
 
-    def append(self, item):
+    def append(self, item: ImagePart):
         self._image_parts.append(item)
 
     def get_or_add_image_part(self, image_descriptor: str | IO[bytes]) -> ImagePart:
@@ -77,31 +77,30 @@ def get_or_add_image_part(self, image_descriptor: str | IO[bytes]) -> ImagePart:
             return matching_image_part
         return self._add_image_part(image)
 
-    def _add_image_part(self, image):
-        """Return an |ImagePart| instance newly created from image and appended to the
-        collection."""
+    def _add_image_part(self, image: Image):
+        """Return |ImagePart| instance newly created from `image` and appended to the collection."""
         partname = self._next_image_partname(image.ext)
         image_part = ImagePart.from_image(image, partname)
         self.append(image_part)
         return image_part
 
-    def _get_by_sha1(self, sha1):
+    def _get_by_sha1(self, sha1: str) -> ImagePart | None:
         """Return the image part in this collection having a SHA1 hash matching `sha1`,
         or |None| if not found."""
         for image_part in self._image_parts:
             if image_part.sha1 == sha1:
                 return image_part
         return None
 
-    def _next_image_partname(self, ext):
+    def _next_image_partname(self, ext: str) -> PackURI:
         """The next available image partname, starting from ``/word/media/image1.{ext}``
         where unused numbers are reused.
 
         The partname is unique by number, without regard to the extension. `ext` does
         not include the leading period.
         """
 
-        def image_partname(n):
+        def image_partname(n: int) -> PackURI:
             return PackURI("/word/media/image%d.%s" % (n, ext))
 
         used_numbers = [image_part.partname.idx for image_part in self]

src/docx/parts/document.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, cast
+from typing import IO, TYPE_CHECKING, cast
 
 from docx.document import Document
 from docx.enum.style import WD_STYLE_TYPE
@@ -17,6 +17,7 @@
 
 if TYPE_CHECKING:
     from docx.opc.coreprops import CoreProperties
+    from docx.settings import Settings
     from docx.styles.style import BaseStyle
 
 
@@ -101,13 +102,13 @@ def numbering_part(self):
             self.relate_to(numbering_part, RT.NUMBERING)
             return numbering_part
 
-    def save(self, path_or_stream):
+    def save(self, path_or_stream: str | IO[bytes]):
         """Save this document to `path_or_stream`, which can be either a path to a
         filesystem location (a string) or a file-like object."""
         self.package.save(path_or_stream)
 
     @property
-    def settings(self):
+    def settings(self) -> Settings:
         """A |Settings| object providing access to the settings in the settings part of
         this document."""
         return self._settings_part.settings
@@ -119,14 +120,14 @@ def styles(self):
         return self._styles_part.styles
 
     @property
-    def _settings_part(self):
+    def _settings_part(self) -> SettingsPart:
         """A |SettingsPart| object providing access to the document-level settings for
         this document.
 
         Creates a default settings part if one is not present.
         """
         try:
-            return self.part_related_by(RT.SETTINGS)
+            return cast(SettingsPart, self.part_related_by(RT.SETTINGS))
         except KeyError:
             settings_part = SettingsPart.default(self.package)
             self.relate_to(settings_part, RT.SETTINGS)

src/docx/parts/hdrftr.py

@@ -1,17 +1,23 @@
 """Header and footer part objects."""
 
+from __future__ import annotations
+
 import os
+from typing import TYPE_CHECKING
 
 from docx.opc.constants import CONTENT_TYPE as CT
 from docx.oxml.parser import parse_xml
 from docx.parts.story import StoryPart
 
+if TYPE_CHECKING:
+    from docx.package import Package
+
 
 class FooterPart(StoryPart):
     """Definition of a section footer."""
 
     @classmethod
-    def new(cls, package):
+    def new(cls, package: Package):
         """Return newly created footer part."""
         partname = package.next_partname("/word/footer%d.xml")
         content_type = CT.WML_FOOTER
@@ -21,9 +27,7 @@ def new(cls, package):
     @classmethod
     def _default_footer_xml(cls):
         """Return bytes containing XML for a default footer part."""
-        path = os.path.join(
-            os.path.split(__file__)[0], "..", "templates", "default-footer.xml"
-        )
+        path = os.path.join(os.path.split(__file__)[0], "..", "templates", "default-footer.xml")
         with open(path, "rb") as f:
             xml_bytes = f.read()
         return xml_bytes
@@ -33,7 +37,7 @@ class HeaderPart(StoryPart):
     """Definition of a section header."""
 
     @classmethod
-    def new(cls, package):
+    def new(cls, package: Package):
         """Return newly created header part."""
         partname = package.next_partname("/word/header%d.xml")
         content_type = CT.WML_HEADER
@@ -43,9 +47,7 @@ def new(cls, package):
     @classmethod
     def _default_header_xml(cls):
         """Return bytes containing XML for a default header part."""
-        path = os.path.join(
-            os.path.split(__file__)[0], "..", "templates", "default-header.xml"
-        )
+        path = os.path.join(os.path.split(__file__)[0], "..", "templates", "default-header.xml")
         with open(path, "rb") as f:
             xml_bytes = f.read()
         return xml_bytes

src/docx/parts/image.py

@@ -3,11 +3,16 @@
 from __future__ import annotations
 
 import hashlib
+from typing import TYPE_CHECKING
 
 from docx.image.image import Image
 from docx.opc.part import Part
 from docx.shared import Emu, Inches
 
+if TYPE_CHECKING:
+    from docx.opc.package import OpcPackage
+    from docx.opc.packuri import PackURI
+
 
 class ImagePart(Part):
     """An image part.
@@ -16,7 +21,7 @@ class ImagePart(Part):
     """
 
     def __init__(
-        self, partname: str, content_type: str, blob: bytes, image: Image | None = None
+        self, partname: PackURI, content_type: str, blob: bytes, image: Image | None = None
     ):
         super(ImagePart, self).__init__(partname, content_type, blob)
         self._image = image
@@ -36,7 +41,7 @@ def default_cy(self):
         vertical dots per inch (dpi)."""
         px_height = self.image.px_height
         horz_dpi = self.image.horz_dpi
-        height_in_emu = 914400 * px_height / horz_dpi
+        height_in_emu = int(round(914400 * px_height / horz_dpi))
         return Emu(height_in_emu)
 
     @property
@@ -52,7 +57,7 @@ def filename(self):
         return "image.%s" % self.partname.ext
 
     @classmethod
-    def from_image(cls, image, partname):
+    def from_image(cls, image: Image, partname: PackURI):
         """Return an |ImagePart| instance newly created from `image` and assigned
         `partname`."""
         return ImagePart(partname, image.content_type, image.blob, image)
@@ -64,12 +69,12 @@ def image(self) -> Image:
         return self._image
 
     @classmethod
-    def load(cls, partname, content_type, blob, package):
+    def load(cls, partname: PackURI, content_type: str, blob: bytes, package: OpcPackage):
         """Called by ``docx.opc.package.PartFactory`` to load an image part from a
         package being opened by ``Document(...)`` call."""
         return cls(partname, content_type, blob)
 
     @property
     def sha1(self):
         """SHA1 hash digest of the blob of this image part."""
-        return hashlib.sha1(self._blob).hexdigest()
+        return hashlib.sha1(self.blob).hexdigest()

src/docx/parts/settings.py

@@ -1,38 +1,51 @@
 """|SettingsPart| and closely related objects."""
 
+from __future__ import annotations
+
 import os
+from typing import TYPE_CHECKING, cast
 
 from docx.opc.constants import CONTENT_TYPE as CT
 from docx.opc.packuri import PackURI
 from docx.opc.part import XmlPart
 from docx.oxml.parser import parse_xml
 from docx.settings import Settings
 
+if TYPE_CHECKING:
+    from docx.oxml.settings import CT_Settings
+    from docx.package import Package
+
 
 class SettingsPart(XmlPart):
     """Document-level settings part of a WordprocessingML (WML) package."""
 
+    def __init__(
+        self, partname: PackURI, content_type: str, element: CT_Settings, package: Package
+    ):
+        super().__init__(partname, content_type, element, package)
+        self._settings = element
+
     @classmethod
-    def default(cls, package):
+    def default(cls, package: Package):
         """Return a newly created settings part, containing a default `w:settings`
         element tree."""
         partname = PackURI("/word/settings.xml")
         content_type = CT.WML_SETTINGS
-        element = parse_xml(cls._default_settings_xml())
+        element = cast("CT_Settings", parse_xml(cls._default_settings_xml()))
         return cls(partname, content_type, element, package)
 
     @property
-    def settings(self):
-        """A |Settings| proxy object for the `w:settings` element in this part,
-        containing the document-level settings for this document."""
-        return Settings(self.element)
+    def settings(self) -> Settings:
+        """A |Settings| proxy object for the `w:settings` element in this part.
+
+        Contains the document-level settings for this document.
+        """
+        return Settings(self._settings)
 
     @classmethod
     def _default_settings_xml(cls):
         """Return a bytestream containing XML for a default settings part."""
-        path = os.path.join(
-            os.path.split(__file__)[0], "..", "templates", "default-settings.xml"
-        )
+        path = os.path.join(os.path.split(__file__)[0], "..", "templates", "default-settings.xml")
         with open(path, "rb") as f:
             xml_bytes = f.read()
         return xml_bytes

src/docx/parts/story.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import IO, TYPE_CHECKING, Tuple
+from typing import IO, TYPE_CHECKING, Tuple, cast
 
 from docx.opc.constants import RELATIONSHIP_TYPE as RT
 from docx.opc.part import XmlPart
@@ -60,8 +60,8 @@ def get_style_id(
     def new_pic_inline(
         self,
         image_descriptor: str | IO[bytes],
-        width: Length | None = None,
-        height: Length | None = None,
+        width: int | Length | None = None,
+        height: int | Length | None = None,
     ) -> CT_Inline:
         """Return a newly-created `w:inline` element.
 
@@ -92,4 +92,4 @@ def _document_part(self) -> DocumentPart:
         """|DocumentPart| object for this package."""
         package = self.package
         assert package is not None
-        return package.main_document_part
+        return cast("DocumentPart", package.main_document_part)

src/docx/section.py

@@ -160,11 +160,7 @@ def iter_inner_content(self) -> Iterator[Paragraph | Table]:
         Items appear in document order.
         """
         for element in self._sectPr.iter_inner_content():
-            yield (
-                Paragraph(element, self)  # pyright: ignore[reportGeneralTypeIssues]
-                if isinstance(element, CT_P)
-                else Table(element, self)
-            )
+            yield (Paragraph(element, self) if isinstance(element, CT_P) else Table(element, self))
 
     @property
     def left_margin(self) -> Length | None:
@@ -269,12 +265,10 @@ def __init__(self, document_elm: CT_Document, document_part: DocumentPart):
         self._document_part = document_part
 
     @overload
-    def __getitem__(self, key: int) -> Section:
-        ...
+    def __getitem__(self, key: int) -> Section: ...
 
     @overload
-    def __getitem__(self, key: slice) -> List[Section]:
-        ...
+    def __getitem__(self, key: slice) -> List[Section]: ...
 
     def __getitem__(self, key: int | slice) -> Section | List[Section]:
         if isinstance(key, slice):

src/docx/settings.py

@@ -1,22 +1,35 @@
 """Settings object, providing access to document-level settings."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
 from docx.shared import ElementProxy
 
+if TYPE_CHECKING:
+    import docx.types as t
+    from docx.oxml.settings import CT_Settings
+    from docx.oxml.xmlchemy import BaseOxmlElement
+
 
 class Settings(ElementProxy):
     """Provides access to document-level settings for a document.
 
     Accessed using the :attr:`.Document.settings` property.
     """
 
+    def __init__(self, element: BaseOxmlElement, parent: t.ProvidesXmlPart | None = None):
+        super().__init__(element, parent)
+        self._settings = cast("CT_Settings", element)
+
     @property
-    def odd_and_even_pages_header_footer(self):
+    def odd_and_even_pages_header_footer(self) -> bool:
         """True if this document has distinct odd and even page headers and footers.
 
         Read/write.
         """
-        return self._element.evenAndOddHeaders_val
+        return self._settings.evenAndOddHeaders_val
 
     @odd_and_even_pages_header_footer.setter
-    def odd_and_even_pages_header_footer(self, value):
-        self._element.evenAndOddHeaders_val = value
+    def odd_and_even_pages_header_footer(self, value: bool):
+        self._settings.evenAndOddHeaders_val = value

src/docx/shape.py

@@ -3,26 +3,36 @@
 A shape is a visual object that appears on the drawing layer of a document.
 """
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 from docx.enum.shape import WD_INLINE_SHAPE
 from docx.oxml.ns import nsmap
 from docx.shared import Parented
 
+if TYPE_CHECKING:
+    from docx.oxml.document import CT_Body
+    from docx.oxml.shape import CT_Inline
+    from docx.parts.story import StoryPart
+    from docx.shared import Length
+
 
 class InlineShapes(Parented):
-    """Sequence of |InlineShape| instances, supporting len(), iteration, and indexed
-    access."""
+    """Sequence of |InlineShape| instances, supporting len(), iteration, and indexed access."""
 
-    def __init__(self, body_elm, parent):
+    def __init__(self, body_elm: CT_Body, parent: StoryPart):
         super(InlineShapes, self).__init__(parent)
         self._body = body_elm
 
-    def __getitem__(self, idx):
+    def __getitem__(self, idx: int):
         """Provide indexed access, e.g. 'inline_shapes[idx]'."""
         try:
             inline = self._inline_lst[idx]
         except IndexError:
             msg = "inline shape index [%d] out of range" % idx
             raise IndexError(msg)
+
         return InlineShape(inline)
 
     def __iter__(self):
@@ -42,20 +52,20 @@ class InlineShape:
     """Proxy for an ``<wp:inline>`` element, representing the container for an inline
     graphical object."""
 
-    def __init__(self, inline):
+    def __init__(self, inline: CT_Inline):
         super(InlineShape, self).__init__()
         self._inline = inline
 
     @property
-    def height(self):
+    def height(self) -> Length:
         """Read/write.
 
         The display height of this inline shape as an |Emu| instance.
         """
         return self._inline.extent.cy
 
     @height.setter
-    def height(self, cy):
+    def height(self, cy: Length):
         self._inline.extent.cy = cy
         self._inline.graphic.graphicData.pic.spPr.cy = cy
 
@@ -88,6 +98,6 @@ def width(self):
         return self._inline.extent.cx
 
     @width.setter
-    def width(self, cx):
+    def width(self, cx: Length):
         self._inline.extent.cx = cx
         self._inline.graphic.graphicData.pic.spPr.cx = cx

src/docx/text/run.py

@@ -59,8 +59,8 @@ def add_break(self, break_type: WD_BREAK = WD_BREAK.LINE):
     def add_picture(
         self,
         image_path_or_stream: str | IO[bytes],
-        width: Length | None = None,
-        height: Length | None = None,
+        width: int | Length | None = None,
+        height: int | Length | None = None,
     ) -> InlineShape:
         """Return |InlineShape| containing image identified by `image_path_or_stream`.
 

tests/opc/parts/test_coreprops.py

@@ -5,22 +5,32 @@
 import pytest
 
 from docx.opc.coreprops import CoreProperties
+from docx.opc.package import OpcPackage
+from docx.opc.packuri import PackURI
 from docx.opc.parts.coreprops import CorePropertiesPart
-from docx.oxml.coreprops import CT_CoreProperties
 
-from ...unitutil.mock import class_mock, instance_mock
+from ...unitutil.cxml import element
+from ...unitutil.mock import FixtureRequest, Mock, class_mock, instance_mock
 
 
 class DescribeCorePropertiesPart:
-    def it_provides_access_to_its_core_props_object(self, coreprops_fixture):
-        core_properties_part, CoreProperties_ = coreprops_fixture
+    """Unit-test suite for `docx.opc.parts.coreprops.CorePropertiesPart` objects."""
+
+    def it_provides_access_to_its_core_props_object(self, CoreProperties_: Mock, package_: Mock):
+        core_properties_part = CorePropertiesPart(
+            PackURI("/part/name"), "content/type", element("cp:coreProperties"), package_
+        )
+
         core_properties = core_properties_part.core_properties
+
         CoreProperties_.assert_called_once_with(core_properties_part.element)
         assert isinstance(core_properties, CoreProperties)
 
-    def it_can_create_a_default_core_properties_part(self):
-        core_properties_part = CorePropertiesPart.default(None)
+    def it_can_create_a_default_core_properties_part(self, package_: Mock):
+        core_properties_part = CorePropertiesPart.default(package_)
+
         assert isinstance(core_properties_part, CorePropertiesPart)
+        # --
         core_properties = core_properties_part.core_properties
         assert core_properties.title == "Word Document"
         assert core_properties.last_modified_by == "python-docx"
@@ -32,16 +42,9 @@ def it_can_create_a_default_core_properties_part(self):
     # fixtures ---------------------------------------------
 
     @pytest.fixture
-    def coreprops_fixture(self, element_, CoreProperties_):
-        core_properties_part = CorePropertiesPart(None, None, element_, None)
-        return core_properties_part, CoreProperties_
-
-    # fixture components -----------------------------------
-
-    @pytest.fixture
-    def CoreProperties_(self, request):
+    def CoreProperties_(self, request: FixtureRequest):
         return class_mock(request, "docx.opc.parts.coreprops.CoreProperties")
 
     @pytest.fixture
-    def element_(self, request):
-        return instance_mock(request, CT_CoreProperties)
+    def package_(self, request: FixtureRequest):
+        return instance_mock(request, OpcPackage)

tests/opc/test_coreprops.py

@@ -1,160 +1,153 @@
+# pyright: reportPrivateUsage=false
+
 """Unit test suite for the docx.opc.coreprops module."""
 
-from datetime import datetime
+from __future__ import annotations
+
+import datetime as dt
+from typing import TYPE_CHECKING, cast
 
 import pytest
 
 from docx.opc.coreprops import CoreProperties
 from docx.oxml.parser import parse_xml
 
+if TYPE_CHECKING:
+    from docx.oxml.coreprops import CT_CoreProperties
+
 
 class DescribeCoreProperties:
-    def it_knows_the_string_property_values(self, text_prop_get_fixture):
-        core_properties, prop_name, expected_value = text_prop_get_fixture
+    """Unit-test suite for `docx.opc.coreprops.CoreProperties` objects."""
+
+    @pytest.mark.parametrize(
+        ("prop_name", "expected_value"),
+        [
+            ("author", "python-docx"),
+            ("category", ""),
+            ("comments", ""),
+            ("content_status", "DRAFT"),
+            ("identifier", "GXS 10.2.1ab"),
+            ("keywords", "foo bar baz"),
+            ("language", "US-EN"),
+            ("last_modified_by", "Steve Canny"),
+            ("subject", "Spam"),
+            ("title", "Word Document"),
+            ("version", "1.2.88"),
+        ],
+    )
+    def it_knows_the_string_property_values(
+        self, prop_name: str, expected_value: str, core_properties: CoreProperties
+    ):
         actual_value = getattr(core_properties, prop_name)
         assert actual_value == expected_value
 
-    def it_can_change_the_string_property_values(self, text_prop_set_fixture):
-        core_properties, prop_name, value, expected_xml = text_prop_set_fixture
-        setattr(core_properties, prop_name, value)
-        assert core_properties._element.xml == expected_xml
-
-    def it_knows_the_date_property_values(self, date_prop_get_fixture):
-        core_properties, prop_name, expected_datetime = date_prop_get_fixture
-        actual_datetime = getattr(core_properties, prop_name)
-        assert actual_datetime == expected_datetime
+    @pytest.mark.parametrize(
+        ("prop_name", "tagname", "value"),
+        [
+            ("author", "dc:creator", "scanny"),
+            ("category", "cp:category", "silly stories"),
+            ("comments", "dc:description", "Bar foo to you"),
+            ("content_status", "cp:contentStatus", "FINAL"),
+            ("identifier", "dc:identifier", "GT 5.2.xab"),
+            ("keywords", "cp:keywords", "dog cat moo"),
+            ("language", "dc:language", "GB-EN"),
+            ("last_modified_by", "cp:lastModifiedBy", "Billy Bob"),
+            ("subject", "dc:subject", "Eggs"),
+            ("title", "dc:title", "Dissertation"),
+            ("version", "cp:version", "81.2.8"),
+        ],
+    )
+    def it_can_change_the_string_property_values(self, prop_name: str, tagname: str, value: str):
+        coreProperties = self.coreProperties(tagname="", str_val="")
+        core_properties = CoreProperties(cast("CT_CoreProperties", parse_xml(coreProperties)))
 
-    def it_can_change_the_date_property_values(self, date_prop_set_fixture):
-        core_properties, prop_name, value, expected_xml = date_prop_set_fixture
         setattr(core_properties, prop_name, value)
-        assert core_properties._element.xml == expected_xml
-
-    def it_knows_the_revision_number(self, revision_get_fixture):
-        core_properties, expected_revision = revision_get_fixture
-        assert core_properties.revision == expected_revision
-
-    def it_can_change_the_revision_number(self, revision_set_fixture):
-        core_properties, revision, expected_xml = revision_set_fixture
-        core_properties.revision = revision
-        assert core_properties._element.xml == expected_xml
 
-    # fixtures -------------------------------------------------------
+        assert core_properties._element.xml == self.coreProperties(tagname, value)
 
-    @pytest.fixture(
-        params=[
-            ("created", datetime(2012, 11, 17, 16, 37, 40)),
-            ("last_printed", datetime(2014, 6, 4, 4, 28)),
+    @pytest.mark.parametrize(
+        ("prop_name", "expected_datetime"),
+        [
+            ("created", dt.datetime(2012, 11, 17, 16, 37, 40)),
+            ("last_printed", dt.datetime(2014, 6, 4, 4, 28)),
             ("modified", None),
-        ]
+        ],
     )
-    def date_prop_get_fixture(self, request, core_properties):
-        prop_name, expected_datetime = request.param
-        return core_properties, prop_name, expected_datetime
+    def it_knows_the_date_property_values(
+        self, prop_name: str, expected_datetime: dt.datetime, core_properties: CoreProperties
+    ):
+        actual_datetime = getattr(core_properties, prop_name)
+        assert actual_datetime == expected_datetime
 
-    @pytest.fixture(
-        params=[
+    @pytest.mark.parametrize(
+        ("prop_name", "tagname", "value", "str_val", "attrs"),
+        [
             (
                 "created",
                 "dcterms:created",
-                datetime(2001, 2, 3, 4, 5),
+                dt.datetime(2001, 2, 3, 4, 5),
                 "2001-02-03T04:05:00Z",
                 ' xsi:type="dcterms:W3CDTF"',
             ),
             (
                 "last_printed",
                 "cp:lastPrinted",
-                datetime(2014, 6, 4, 4),
+                dt.datetime(2014, 6, 4, 4),
                 "2014-06-04T04:00:00Z",
                 "",
             ),
             (
                 "modified",
                 "dcterms:modified",
-                datetime(2005, 4, 3, 2, 1),
+                dt.datetime(2005, 4, 3, 2, 1),
                 "2005-04-03T02:01:00Z",
                 ' xsi:type="dcterms:W3CDTF"',
             ),
-        ]
+        ],
     )
-    def date_prop_set_fixture(self, request):
-        prop_name, tagname, value, str_val, attrs = request.param
-        coreProperties = self.coreProperties(None, None)
-        core_properties = CoreProperties(parse_xml(coreProperties))
+    def it_can_change_the_date_property_values(
+        self, prop_name: str, tagname: str, value: dt.datetime, str_val: str, attrs: str
+    ):
+        coreProperties = self.coreProperties(tagname="", str_val="")
+        core_properties = CoreProperties(cast("CT_CoreProperties", parse_xml(coreProperties)))
         expected_xml = self.coreProperties(tagname, str_val, attrs)
-        return core_properties, prop_name, value, expected_xml
 
-    @pytest.fixture(
-        params=[("42", 42), (None, 0), ("foobar", 0), ("-17", 0), ("32.7", 0)]
-    )
-    def revision_get_fixture(self, request):
-        str_val, expected_revision = request.param
-        tagname = "" if str_val is None else "cp:revision"
-        coreProperties = self.coreProperties(tagname, str_val)
-        core_properties = CoreProperties(parse_xml(coreProperties))
-        return core_properties, expected_revision
-
-    @pytest.fixture(
-        params=[
-            (42, "42"),
-        ]
+        setattr(core_properties, prop_name, value)
+
+        assert core_properties._element.xml == expected_xml
+
+    @pytest.mark.parametrize(
+        ("str_val", "expected_value"),
+        [("42", 42), (None, 0), ("foobar", 0), ("-17", 0), ("32.7", 0)],
     )
-    def revision_set_fixture(self, request):
-        value, str_val = request.param
-        coreProperties = self.coreProperties(None, None)
-        core_properties = CoreProperties(parse_xml(coreProperties))
+    def it_knows_the_revision_number(self, str_val: str | None, expected_value: int):
+        tagname, str_val = ("cp:revision", str_val) if str_val else ("", "")
+        coreProperties = self.coreProperties(tagname, str_val or "")
+        core_properties = CoreProperties(cast("CT_CoreProperties", parse_xml(coreProperties)))
+
+        assert core_properties.revision == expected_value
+
+    @pytest.mark.parametrize(("value", "str_val"), [(42, "42")])
+    def it_can_change_the_revision_number(self, value: int, str_val: str):
+        coreProperties = self.coreProperties(tagname="", str_val="")
+        core_properties = CoreProperties(cast("CT_CoreProperties", parse_xml(coreProperties)))
         expected_xml = self.coreProperties("cp:revision", str_val)
-        return core_properties, value, expected_xml
 
-    @pytest.fixture(
-        params=[
-            ("author", "python-docx"),
-            ("category", ""),
-            ("comments", ""),
-            ("content_status", "DRAFT"),
-            ("identifier", "GXS 10.2.1ab"),
-            ("keywords", "foo bar baz"),
-            ("language", "US-EN"),
-            ("last_modified_by", "Steve Canny"),
-            ("subject", "Spam"),
-            ("title", "Word Document"),
-            ("version", "1.2.88"),
-        ]
-    )
-    def text_prop_get_fixture(self, request, core_properties):
-        prop_name, expected_value = request.param
-        return core_properties, prop_name, expected_value
+        core_properties.revision = value
 
-    @pytest.fixture(
-        params=[
-            ("author", "dc:creator", "scanny"),
-            ("category", "cp:category", "silly stories"),
-            ("comments", "dc:description", "Bar foo to you"),
-            ("content_status", "cp:contentStatus", "FINAL"),
-            ("identifier", "dc:identifier", "GT 5.2.xab"),
-            ("keywords", "cp:keywords", "dog cat moo"),
-            ("language", "dc:language", "GB-EN"),
-            ("last_modified_by", "cp:lastModifiedBy", "Billy Bob"),
-            ("subject", "dc:subject", "Eggs"),
-            ("title", "dc:title", "Dissertation"),
-            ("version", "cp:version", "81.2.8"),
-        ]
-    )
-    def text_prop_set_fixture(self, request):
-        prop_name, tagname, value = request.param
-        coreProperties = self.coreProperties(None, None)
-        core_properties = CoreProperties(parse_xml(coreProperties))
-        expected_xml = self.coreProperties(tagname, value)
-        return core_properties, prop_name, value, expected_xml
+        assert core_properties._element.xml == expected_xml
 
-    # fixture components ---------------------------------------------
+    # fixtures -------------------------------------------------------
 
-    def coreProperties(self, tagname, str_val, attrs=""):
+    def coreProperties(self, tagname: str, str_val: str, attrs: str = "") -> str:
         tmpl = (
-            '<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/'
-            'package/2006/metadata/core-properties" xmlns:dc="http://purl.or'
-            'g/dc/elements/1.1/" xmlns:dcmitype="http://purl.org/dc/dcmitype'
-            '/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="http://'
-            'www.w3.org/2001/XMLSchema-instance">%s</cp:coreProperties>\n'
+            "<cp:coreProperties"
+            ' xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties"'
+            ' xmlns:dc="http://purl.org/dc/elements/1.1/"'
+            ' xmlns:dcmitype="http://purl.org/dc/dcmitype/"'
+            ' xmlns:dcterms="http://purl.org/dc/terms/"'
+            ' xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"'
+            ">%s</cp:coreProperties>\n"
         )
         if not tagname:
             child_element = ""
@@ -166,27 +159,30 @@ def coreProperties(self, tagname, str_val, attrs=""):
 
     @pytest.fixture
     def core_properties(self):
-        element = parse_xml(
-            b"<?xml version='1.0' encoding='UTF-8' standalone='yes'?>"
-            b'\n<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.o'
-            b'rg/package/2006/metadata/core-properties" xmlns:dc="http://pur'
-            b'l.org/dc/elements/1.1/" xmlns:dcmitype="http://purl.org/dc/dcm'
-            b'itype/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="h'
-            b'ttp://www.w3.org/2001/XMLSchema-instance">\n'
-            b"  <cp:contentStatus>DRAFT</cp:contentStatus>\n"
-            b"  <dc:creator>python-docx</dc:creator>\n"
-            b'  <dcterms:created xsi:type="dcterms:W3CDTF">2012-11-17T11:07:'
-            b"40-05:30</dcterms:created>\n"
-            b"  <dc:description/>\n"
-            b"  <dc:identifier>GXS 10.2.1ab</dc:identifier>\n"
-            b"  <dc:language>US-EN</dc:language>\n"
-            b"  <cp:lastPrinted>2014-06-04T04:28:00Z</cp:lastPrinted>\n"
-            b"  <cp:keywords>foo bar baz</cp:keywords>\n"
-            b"  <cp:lastModifiedBy>Steve Canny</cp:lastModifiedBy>\n"
-            b"  <cp:revision>4</cp:revision>\n"
-            b"  <dc:subject>Spam</dc:subject>\n"
-            b"  <dc:title>Word Document</dc:title>\n"
-            b"  <cp:version>1.2.88</cp:version>\n"
-            b"</cp:coreProperties>\n"
+        element = cast(
+            "CT_CoreProperties",
+            parse_xml(
+                b"<?xml version='1.0' encoding='UTF-8' standalone='yes'?>"
+                b'\n<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.o'
+                b'rg/package/2006/metadata/core-properties" xmlns:dc="http://pur'
+                b'l.org/dc/elements/1.1/" xmlns:dcmitype="http://purl.org/dc/dcm'
+                b'itype/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="h'
+                b'ttp://www.w3.org/2001/XMLSchema-instance">\n'
+                b"  <cp:contentStatus>DRAFT</cp:contentStatus>\n"
+                b"  <dc:creator>python-docx</dc:creator>\n"
+                b'  <dcterms:created xsi:type="dcterms:W3CDTF">2012-11-17T11:07:'
+                b"40-05:30</dcterms:created>\n"
+                b"  <dc:description/>\n"
+                b"  <dc:identifier>GXS 10.2.1ab</dc:identifier>\n"
+                b"  <dc:language>US-EN</dc:language>\n"
+                b"  <cp:lastPrinted>2014-06-04T04:28:00Z</cp:lastPrinted>\n"
+                b"  <cp:keywords>foo bar baz</cp:keywords>\n"
+                b"  <cp:lastModifiedBy>Steve Canny</cp:lastModifiedBy>\n"
+                b"  <cp:revision>4</cp:revision>\n"
+                b"  <dc:subject>Spam</dc:subject>\n"
+                b"  <dc:title>Word Document</dc:title>\n"
+                b"  <cp:version>1.2.88</cp:version>\n"
+                b"</cp:coreProperties>\n"
+            ),
         )
         return CoreProperties(element)

tests/opc/test_part.py

@@ -28,99 +28,54 @@
 
 
 class DescribePart:
-    def it_can_be_constructed_by_PartFactory(
-        self, partname_, content_type_, blob_, package_, __init_
-    ):
-        part = Part.load(partname_, content_type_, blob_, package_)
+    """Unit-test suite for `docx.opc.part.Part` objects."""
 
-        __init_.assert_called_once_with(ANY, partname_, content_type_, blob_, package_)
+    def it_can_be_constructed_by_PartFactory(self, package_: Mock, init__: Mock):
+        part = Part.load(PackURI("/part/name"), "content/type", b"1be2", package_)
+
+        init__.assert_called_once_with(ANY, "/part/name", "content/type", b"1be2", package_)
         assert isinstance(part, Part)
 
-    def it_knows_its_partname(self, partname_get_fixture):
-        part, expected_partname = partname_get_fixture
-        assert part.partname == expected_partname
+    def it_knows_its_partname(self):
+        part = Part(PackURI("/part/name"), "content/type")
+        assert part.partname == "/part/name"
 
-    def it_can_change_its_partname(self, partname_set_fixture):
-        part, new_partname = partname_set_fixture
-        part.partname = new_partname
-        assert part.partname == new_partname
+    def it_can_change_its_partname(self):
+        part = Part(PackURI("/old/part/name"), "content/type")
+        part.partname = PackURI("/new/part/name")
+        assert part.partname == "/new/part/name"
 
-    def it_knows_its_content_type(self, content_type_fixture):
-        part, expected_content_type = content_type_fixture
-        assert part.content_type == expected_content_type
+    def it_knows_its_content_type(self):
+        part = Part(PackURI("/part/name"), "content/type")
+        assert part.content_type == "content/type"
 
-    def it_knows_the_package_it_belongs_to(self, package_get_fixture):
-        part, expected_package = package_get_fixture
-        assert part.package == expected_package
+    def it_knows_the_package_it_belongs_to(self, package_: Mock):
+        part = Part(PackURI("/part/name"), "content/type", package=package_)
+        assert part.package is package_
 
-    def it_can_be_notified_after_unmarshalling_is_complete(self, part):
+    def it_can_be_notified_after_unmarshalling_is_complete(self):
+        part = Part(PackURI("/part/name"), "content/type")
         part.after_unmarshal()
 
-    def it_can_be_notified_before_marshalling_is_started(self, part):
+    def it_can_be_notified_before_marshalling_is_started(self):
+        part = Part(PackURI("/part/name"), "content/type")
         part.before_marshal()
 
-    def it_uses_the_load_blob_as_its_blob(self, blob_fixture):
-        part, load_blob = blob_fixture
-        assert part.blob is load_blob
+    def it_uses_the_load_blob_as_its_blob(self):
+        blob = b"abcde"
+        part = Part(PackURI("/part/name"), "content/type", blob)
+        assert part.blob is blob
 
     # fixtures ---------------------------------------------
 
     @pytest.fixture
-    def blob_fixture(self, blob_):
-        part = Part(None, None, blob_, None)
-        return part, blob_
-
-    @pytest.fixture
-    def content_type_fixture(self):
-        content_type = "content/type"
-        part = Part(None, content_type, None, None)
-        return part, content_type
-
-    @pytest.fixture
-    def package_get_fixture(self, package_):
-        part = Part(None, None, None, package_)
-        return part, package_
-
-    @pytest.fixture
-    def part(self):
-        part = Part(None, None)
-        return part
-
-    @pytest.fixture
-    def partname_get_fixture(self):
-        partname = PackURI("/part/name")
-        part = Part(partname, None, None, None)
-        return part, partname
-
-    @pytest.fixture
-    def partname_set_fixture(self):
-        old_partname = PackURI("/old/part/name")
-        new_partname = PackURI("/new/part/name")
-        part = Part(old_partname, None, None, None)
-        return part, new_partname
-
-    # fixture components ---------------------------------------------
-
-    @pytest.fixture
-    def blob_(self, request):
-        return instance_mock(request, bytes)
-
-    @pytest.fixture
-    def content_type_(self, request):
-        return instance_mock(request, str)
-
-    @pytest.fixture
-    def __init_(self, request):
+    def init__(self, request: FixtureRequest):
         return initializer_mock(request, Part)
 
     @pytest.fixture
-    def package_(self, request):
+    def package_(self, request: FixtureRequest):
         return instance_mock(request, OpcPackage)
 
-    @pytest.fixture
-    def partname_(self, request):
-        return instance_mock(request, PackURI)
-
 
 class DescribePartRelationshipManagementInterface:
     """Unit-test suite for `docx.opc.package.Part` relationship behaviors."""