feat(typing): add py.typed, improve public types

src/docx/api.py

@@ -6,21 +6,25 @@
 from __future__ import annotations
 
 import os
-from typing import IO
+from typing import IO, TYPE_CHECKING, cast
 
 from docx.opc.constants import CONTENT_TYPE as CT
 from docx.package import Package
 
+if TYPE_CHECKING:
+ from docx.document import Document as DocumentObject
+ from docx.parts.document import DocumentPart
 
-def Document(docx: str | IO[bytes] | None = None):
+
+def Document(docx: str | IO[bytes] | None = None) -> DocumentObject:
  """Return a |Document| object loaded from `docx`, where `docx` can be either a path
  to a ``.docx`` file (a string) or a file-like object.
 
  If `docx` is missing or ``None``, the built-in default document "template" is
  loaded.
  """
  docx = _default_docx_path() if docx is None else docx
- document_part = Package.open(docx).main_document_part
+ document_part = cast("DocumentPart", Package.open(docx).main_document_part)
  if document_part.content_type != CT.WML_DOCUMENT_MAIN:
  tmpl = "file '%s' is not a Word file, content type is '%s'"
  raise ValueError(tmpl % (docx, document_part.content_type))

src/docx/oxml/text/parfmt.py

@@ -28,10 +28,18 @@
 class CT_Ind(BaseOxmlElement):
  """``<w:ind>`` element, specifying paragraph indentation."""
 
- left = OptionalAttribute("w:left", ST_SignedTwipsMeasure)
- right = OptionalAttribute("w:right", ST_SignedTwipsMeasure)
- firstLine = OptionalAttribute("w:firstLine", ST_TwipsMeasure)
- hanging = OptionalAttribute("w:hanging", ST_TwipsMeasure)
+ left: Length | None = OptionalAttribute( # pyright: ignore[reportAssignmentType]
+ "w:left", ST_SignedTwipsMeasure
+ )
+ right: Length | None = OptionalAttribute( # pyright: ignore[reportAssignmentType]
+ "w:right", ST_SignedTwipsMeasure
+ )
+ firstLine: Length | None = OptionalAttribute( # pyright: ignore[reportAssignmentType]
+ "w:firstLine", ST_TwipsMeasure
+ )
+ hanging: Length | None = OptionalAttribute( # pyright: ignore[reportAssignmentType]
+ "w:hanging", ST_TwipsMeasure
+ )
 
 
 class CT_Jc(BaseOxmlElement):
@@ -45,6 +53,7 @@ class CT_Jc(BaseOxmlElement):
 class CT_PPr(BaseOxmlElement):
  """``<w:pPr>`` element, containing the properties for a paragraph."""
 
+ get_or_add_ind: Callable[[], CT_Ind]
  get_or_add_pStyle: Callable[[], CT_String]
  _insert_sectPr: Callable[[CT_SectPr], None]
  _remove_pStyle: Callable[[], None]
@@ -98,13 +107,15 @@ class CT_PPr(BaseOxmlElement):
  numPr = ZeroOrOne("w:numPr", successors=_tag_seq[7:])
  tabs = ZeroOrOne("w:tabs", successors=_tag_seq[11:])
  spacing = ZeroOrOne("w:spacing", successors=_tag_seq[22:])
- ind = ZeroOrOne("w:ind", successors=_tag_seq[23:])
+ ind: CT_Ind | None = ZeroOrOne( # pyright: ignore[reportAssignmentType]
+ "w:ind", successors=_tag_seq[23:]
+ )
  jc = ZeroOrOne("w:jc", successors=_tag_seq[27:])
  sectPr = ZeroOrOne("w:sectPr", successors=_tag_seq[35:])
  del _tag_seq
 
  @property
- def first_line_indent(self):
+ def first_line_indent(self) -> Length | None:
  """A |Length| value calculated from the values of `w:ind/@w:firstLine` and
  `w:ind/@w:hanging`.
 
@@ -122,7 +133,7 @@ def first_line_indent(self):
  return firstLine
 
  @first_line_indent.setter
- def first_line_indent(self, value):
+ def first_line_indent(self, value: Length | None):
  if self.ind is None and value is None:
  return
  ind = self.get_or_add_ind()
@@ -135,30 +146,30 @@ def first_line_indent(self, value):
  ind.firstLine = value
 
  @property
- def ind_left(self):
+ def ind_left(self) -> Length | None:
  """The value of `w:ind/@w:left` or |None| if not present."""
  ind = self.ind
  if ind is None:
  return None
  return ind.left
 
  @ind_left.setter
- def ind_left(self, value):
+ def ind_left(self, value: Length | None):
  if value is None and self.ind is None:
  return
  ind = self.get_or_add_ind()
  ind.left = value
 
  @property
- def ind_right(self):
+ def ind_right(self) -> Length | None:
  """The value of `w:ind/@w:right` or |None| if not present."""
  ind = self.ind
  if ind is None:
  return None
  return ind.right
 
  @ind_right.setter
- def ind_right(self, value):
+ def ind_right(self, value: Length | None):
  if value is None and self.ind is None:
  return
  ind = self.get_or_add_ind()
@@ -340,9 +351,15 @@ class CT_TabStop(BaseOxmlElement):
  only needs a __str__ method.
  """
 
- val = RequiredAttribute("w:val", WD_TAB_ALIGNMENT)
- leader = OptionalAttribute("w:leader", WD_TAB_LEADER, default=WD_TAB_LEADER.SPACES)
- pos = RequiredAttribute("w:pos", ST_SignedTwipsMeasure)
+ val: WD_TAB_ALIGNMENT = RequiredAttribute( # pyright: ignore[reportAssignmentType]
+ "w:val", WD_TAB_ALIGNMENT
+ )
+ leader: WD_TAB_LEADER | None = OptionalAttribute( # pyright: ignore[reportAssignmentType]
+ "w:leader", WD_TAB_LEADER, default=WD_TAB_LEADER.SPACES
+ )
+ pos: Length = RequiredAttribute( # pyright: ignore[reportAssignmentType]
+ "w:pos", ST_SignedTwipsMeasure
+ )
 
  def __str__(self) -> str:
  """Text equivalent of a `w:tab` element appearing in a run.

src/docx/parts/document.py

@@ -16,6 +16,7 @@
 from docx.shared import lazyproperty
 
 if TYPE_CHECKING:
+ from docx.opc.coreprops import CoreProperties
  from docx.styles.style import BaseStyle
 
 
@@ -41,7 +42,7 @@ def add_header_part(self):
  return header_part, rId
 
  @property
- def core_properties(self):
+ def core_properties(self) -> CoreProperties:
  """A |CoreProperties| object providing read/write access to the core properties
  of this document."""
  return self.package.core_properties