rfctr: improve typing

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