rfctr: improve typing for Footnotes

Author: tiberlas

src/docx/document.py

@@ -22,6 +22,8 @@
     from docx.styles.style import ParagraphStyle, _TableStyle
     from docx.table import Table
     from docx.text.paragraph import Paragraph
+    from docx.oxml.footnote import CT_Footnotes, CT_FtnEnd
+    from docx.oxml.text.paragraph import CT_P
 
 
 class Document(ElementProxy):
@@ -113,7 +115,7 @@ def core_properties(self):
         return self._part.core_properties
 
     @property
-    def footnotes(self):
+    def footnotes(self) -> CT_Footnotes:
         """A |Footnotes| object providing access to footnote elements in this document."""
         return self._part.footnotes
 
@@ -179,7 +181,7 @@ def tables(self) -> List[Table]:
         """
         return self._body.tables
 
-    def _add_footnote(self, footnote_reference_ids):
+    def _add_footnote(self, footnote_reference_ids: int) -> CT_FtnEnd:
         """Inserts a newly created footnote to |Footnotes|."""
         return self._part.footnotes.add_footnote(footnote_reference_ids)
 
@@ -196,7 +198,7 @@ def _body(self) -> _Body:
             self.__body = _Body(self._element.body, self)
         return self.__body
 
-    def _calculate_next_footnote_reference_id(self, p):
+    def _calculate_next_footnote_reference_id(self, p: CT_P) -> int:
         """
         Return the appropriate footnote reference id number for
         a new footnote added at the end of paragraph `p`.
@@ -228,7 +230,7 @@ def _calculate_next_footnote_reference_id(self, p):
                 continue
             # These footnotes are after the new footnote, so we increment them.
             if not has_passed_containing_para:
-                self.paragraphs[p_i].increment_containing_footnote_reference_ids()
+                self.paragraphs[p_i]._increment_containing_footnote_reference_ids()
             else:
                 # This is the last footnote before the new footnote, so we use its
                 # value to determent the value of the new footnote.

src/docx/footnotes.py

@@ -2,19 +2,24 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from docx.blkcntnr import BlockItemContainer
 from docx.shared import Parented
 
+if TYPE_CHECKING:
+    from docx import types as t
+    from docx.oxml.footnote import CT_FtnEnd, CT_Footnotes
 
 class Footnotes(Parented):
     """
     Proxy object wrapping ``<w:footnotes>`` element.
     """
-    def __init__(self, footnotes, parent):
+    def __init__(self, footnotes: CT_Footnotes, parent: t.ProvidesStoryPart):
         super(Footnotes, self).__init__(parent)
         self._element = self._footnotes = footnotes
 
-    def __getitem__(self, reference_id):
+    def __getitem__(self, reference_id: int) -> Footnote:
         """
         A |Footnote| for a specific footnote of reference id, defined with ``w:id`` argument of ``<w:footnoteReference>``.
         If reference id is invalid raises an |IndexError|
@@ -24,10 +29,10 @@ def __getitem__(self, reference_id):
             raise IndexError
         return Footnote(footnote, self)
 
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self._element)
 
-    def add_footnote(self, footnote_reference_id):
+    def add_footnote(self, footnote_reference_id: int) -> Footnote:
         """
         Return a newly created |Footnote|, the new footnote will
         be inserted in the correct spot by `footnote_reference_id`.
@@ -63,20 +68,20 @@ class Footnote(BlockItemContainer):
     """
     Proxy object wrapping ``<w:footnote>`` element.
     """
-    def __init__(self, f, parent):
+    def __init__(self, f: CT_FtnEnd, parent:  t.ProvidesStoryPart):
         super(Footnote, self).__init__(f, parent)
         self._f = self._element = f
 
-    def __eq__(self, other):
+    def __eq__(self, other) -> bool:
         if isinstance(other, Footnote):
             return self._f is other._f
         return False
 
-    def __ne__(self, other):
+    def __ne__(self, other) -> bool:
         if isinstance(other, Footnote):
             return self._f is not other._f
         return True
 
     @property
-    def id(self):
+    def id(self) -> int:
         return self._f.id

src/docx/oxml/footnote.py

@@ -1,5 +1,9 @@
 """Custom element classes related to footnote (CT_FtnEnd, CT_Footnotes)."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable, List
+
 from docx.oxml.ns import qn
 from docx.oxml.parser import OxmlElement
 from docx.oxml.xmlchemy import (
@@ -9,25 +13,8 @@
     ST_DecimalNumber
 )
 
-class CT_Footnotes(BaseOxmlElement):
-    """
-    ``<w:footnotes>`` element, containing a sequence of footnote (w:footnote) elements
-    """
-    footnote_sequence = OneOrMore('w:footnote')
-
-    def add_footnote(self, footnote_reference_id):
-        """
-        Create a ``<w:footnote>`` element with `footnote_reference_id`.
-        """
-        new_f = self.add_footnote_sequence()
-        new_f.id = footnote_reference_id
-        return new_f
-
-    def get_by_id(self, id):
-        found = self.xpath(f'w:footnote[@w:id="{id}"]')
-        if not found:
-            return None
-        return found[0]
+if TYPE_CHECKING:
+    from docx.oxml.text.paragraph import CT_P
 
 
 class CT_FtnEnd(BaseOxmlElement):
@@ -37,7 +24,7 @@ class CT_FtnEnd(BaseOxmlElement):
     id = RequiredAttribute('w:id', ST_DecimalNumber)
     p = ZeroOrMore('w:p')
 
-    def add_footnote_before(self, footnote_reference_id):
+    def add_footnote_before(self, footnote_reference_id: int) -> CT_FtnEnd:
         """
         Create a ``<w:footnote>`` element with `footnote_reference_id`
         and insert it before the current element.
@@ -48,12 +35,34 @@ def add_footnote_before(self, footnote_reference_id):
         return new_footnote
 
     @property
-    def paragraphs(self):
-        """
-        Returns a list of paragraphs |CT_P|, or |None| if none paragraph is present.
-        """
+    def paragraphs(self) -> List[CT_P]:
+        """Returns a list of paragraphs |CT_P|."""
+
         paragraphs = []
         for child in self:
             if child.tag == qn('w:p'):
                 paragraphs.append(child)
         return paragraphs
+
+
+class CT_Footnotes(BaseOxmlElement):
+    """
+    ``<w:footnotes>`` element, containing a sequence of footnote (w:footnote) elements
+    """
+    add_footnote_sequence: Callable[[], CT_FtnEnd]
+
+    footnote_sequence = OneOrMore('w:footnote')
+
+    def add_footnote(self, footnote_reference_id: int) -> CT_FtnEnd:
+        """
+        Create a ``<w:footnote>`` element with `footnote_reference_id`.
+        """
+        new_f = self.add_footnote_sequence()
+        new_f.id = footnote_reference_id
+        return new_f
+
+    def get_by_id(self, id: int) -> CT_FtnEnd | None:
+        found = self.xpath(f'w:footnote[@w:id="{id}"]')
+        if not found:
+            return None
+        return found[0]

src/docx/oxml/section.py

@@ -12,8 +12,8 @@
 
 from docx.enum.section import WD_HEADER_FOOTER, WD_ORIENTATION, WD_SECTION_START
 from docx.oxml.ns import nsmap
-from docx.oxml.shared import CT_OnOff
-from docx.oxml.simpletypes import ST_SignedTwipsMeasure, ST_TwipsMeasure, XsdString, ST_FtnPos, ST_NumberFormat, ST_RestartNumber
+from docx.oxml.shared import CT_OnOff, CT_DecimalNumber
+from docx.oxml.simpletypes import ST_SignedTwipsMeasure, ST_TwipsMeasure, XsdString, ST_FtnPos, ST_NumberFormat, ST_RestartNumber, ST_DecimalNumber
 from docx.oxml.table import CT_Tbl
 from docx.oxml.text.paragraph import CT_P
 from docx.oxml.xmlchemy import (
@@ -35,13 +35,19 @@ class CT_FtnPos(BaseOxmlElement):
 
 class CT_FtnProps(BaseOxmlElement):
     """``<w:footnotePr>`` element, section wide footnote properties"""
+
+    get_or_add_pos: Callable[[], CT_FtnPos]
+    get_or_add_numFmt: Callable[[], CT_NumFmt]
+    get_or_add_numStart: Callable[[], CT_DecimalNumber]
+    get_or_add_numRestart: Callable[[], CT_NumRestart]
+
     _tag_seq = (
         'w:pos', 'w:numFmt', 'w:numStart', 'w:numRestart'
     )
-    pos = ZeroOrOne('w:pos', successors=_tag_seq)
-    numFmt = ZeroOrOne('w:numFmt', successors=_tag_seq[1:])
-    numStart = ZeroOrOne('w:numStart', successors=_tag_seq[2:])
-    numRestart = ZeroOrOne('w:numRestart', successors=_tag_seq[3:])
+    pos: CT_FtnPos | None = ZeroOrOne('w:pos', successors=_tag_seq)  # pyright: ignore[reportGeneralTypeIssues]
+    numFmt: CT_NumFmt | None = ZeroOrOne('w:numFmt', successors=_tag_seq[1:])  # pyright: ignore[reportGeneralTypeIssues]
+    numStart: CT_DecimalNumber | None = ZeroOrOne('w:numStart', successors=_tag_seq[2:])  # pyright: ignore[reportGeneralTypeIssues]
+    numRestart: CT_NumRestart | None = ZeroOrOne('w:numRestart', successors=_tag_seq[3:])  # pyright: ignore[reportGeneralTypeIssues]
 
 
 class CT_HdrFtr(BaseOxmlElement):
@@ -132,6 +138,7 @@ class CT_SectPr(BaseOxmlElement):
     get_or_add_pgSz: Callable[[], CT_PageSz]
     get_or_add_titlePg: Callable[[], CT_OnOff]
     get_or_add_type: Callable[[], CT_SectType]
+    get_or_add_footnotePr: Callable[[], CT_FtnProps]
     _add_footerReference: Callable[[], CT_HdrFtrRef]
     _add_headerReference: Callable[[], CT_HdrFtrRef]
     _remove_titlePg: Callable[[], None]
@@ -173,7 +180,9 @@ class CT_SectPr(BaseOxmlElement):
     titlePg: CT_OnOff | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
         "w:titlePg", successors=_tag_seq[14:]
     )
-    footnotePr = ZeroOrOne("w:footnotePr", successors=_tag_seq[1:])
+    footnotePr: CT_FtnProps | None = ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
+        "w:footnotePr", successors=_tag_seq[1:]
+    )
     del _tag_seq
 
     def add_footerReference(self, type_: WD_HEADER_FOOTER, rId: str) -> CT_HdrFtrRef:
@@ -241,7 +250,7 @@ def footer(self, value: int | Length | None):
         pgMar.footer = value if value is None or isinstance(value, Length) else Length(value)
 
     @property
-    def footnote_number_format(self):
+    def footnote_number_format(self) -> ST_NumberFormat | None:
         """
         The value of the ``w:val`` attribute in the ``<w:numFmt>`` child
         element of ``<w:footnotePr>`` element, as a |String|, or |None| if either the element or the
@@ -253,13 +262,13 @@ def footnote_number_format(self):
         return fPr.numFmt.val
 
     @footnote_number_format.setter
-    def footnote_number_format(self, value):
+    def footnote_number_format(self, value: ST_NumberFormat | None):
         fPr = self.get_or_add_footnotePr()
         numFmt = fPr.get_or_add_numFmt()
         numFmt.val = value
 
     @property
-    def footnote_numbering_restart_location(self):
+    def footnote_numbering_restart_location(self) -> ST_RestartNumber | None:
         """
         The value of the ``w:val`` attribute in the ``<w:numRestart>`` child
         element of ``<w:footnotePr>`` element, as a |String|, or |None| if either the element or the
@@ -271,20 +280,20 @@ def footnote_numbering_restart_location(self):
         return fPr.numRestart.val
 
     @footnote_numbering_restart_location.setter
-    def footnote_numbering_restart_location(self, value):
+    def footnote_numbering_restart_location(self, value: ST_RestartNumber | None):
         fPr = self.get_or_add_footnotePr()
         numStart = fPr.get_or_add_numStart()
         numRestart = fPr.get_or_add_numRestart()
         numRestart.val = value
-        if numStart is None or len(numStart.values()) == 0:
+        if len(numStart.values()) == 0:
             numStart.val = 1
         elif value != 'continuous':
             numStart.val = 1
             msg = "When ``<w:numRestart> is not 'continuous', then ``<w:numStart>`` must be 1."
             warn(msg, UserWarning, stacklevel=2)
 
     @property
-    def footnote_numbering_start_value(self):
+    def footnote_numbering_start_value(self) -> ST_DecimalNumber | None:
         """
         The value of the ``w:val`` attribute in the ``<w:numStart>`` child
         element of ``<w:footnotePr>`` element, as a |Number|, or |None| if either the element or the
@@ -296,20 +305,20 @@ def footnote_numbering_start_value(self):
         return fPr.numStart.val
 
     @footnote_numbering_start_value.setter
-    def footnote_numbering_start_value(self, value):
+    def footnote_numbering_start_value(self, value: ST_DecimalNumber | None):
         fPr = self.get_or_add_footnotePr()
         numStart = fPr.get_or_add_numStart()
         numRestart = fPr.get_or_add_numRestart()
         numStart.val = value
-        if numRestart is None or len(numRestart.values()) == 0:
+        if len(numRestart.values()) == 0:
             numRestart.val = 'continuous'
         elif value != 1:
             numRestart.val = 'continuous'
             msg = "When ``<w:numStart> is not 1, then ``<w:numRestart>`` must be 'continuous'."
             warn(msg, UserWarning, stacklevel=2)
 
     @property
-    def footnote_position(self):
+    def footnote_position(self) -> ST_FtnPos | None:
         """
         The value of the ``w:val`` attribute in the ``<w:pos>`` child
         element of ``<w:footnotePr>`` element, as a |String|, or |None| if either the element or the
@@ -321,7 +330,7 @@ def footnote_position(self):
         return fPr.pos.val
 
     @footnote_position.setter
-    def footnote_position(self, value):
+    def footnote_position(self, value: ST_FtnPos | None):
         fPr = self.get_or_add_footnotePr()
         pos = fPr.get_or_add_pos()
         pos.val = value

src/docx/oxml/text/paragraph.py

@@ -71,15 +71,13 @@ def lastRenderedPageBreaks(self) -> List[CT_LastRenderedPageBreak]:
         )
 
     @property
-    def footnote_reference_ids(self):
-        """
-        Return all footnote reference ids (``<w:footnoteReference>``) form the paragraph,
-        or |None| if not present.
-        """
+    def footnote_reference_ids(self) -> List[int]:
+        """Return all footnote reference ids (``<w:footnoteReference>``) form the paragraph."""
+
         footnote_ids = []
         for run in self.r_lst:
             new_footnote_ids = run.footnote_reference_ids
-            if new_footnote_ids:
+            if new_footnote_ids and len(new_footnote_ids) > 0:
                 footnote_ids.extend(new_footnote_ids)
         return footnote_ids
 

src/docx/oxml/text/run.py

@@ -15,6 +15,7 @@
     from docx.oxml.shape import CT_Anchor, CT_Inline
     from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
     from docx.oxml.text.parfmt import CT_TabStop
+    from docx.oxml.text.footnote_reference import CT_FtnEdnRef
 
 # ------------------------------------------------------------------------------------
 # Run-level elements
@@ -28,6 +29,9 @@ class CT_R(BaseOxmlElement):
     get_or_add_rPr: Callable[[], CT_RPr]
     _add_drawing: Callable[[], CT_Drawing]
     _add_t: Callable[..., CT_Text]
+    _add_rPr: Callable[[], CT_RPr]
+    _add_footnoteReference: Callable[[], CT_FtnEdnRef]
+    footnoteReference_lst: List[CT_FtnEdnRef] | None
 
     rPr: CT_RPr | None = ZeroOrOne("w:rPr")  # pyright: ignore[reportAssignmentType]
     br = ZeroOrMore("w:br")
@@ -37,7 +41,7 @@ class CT_R(BaseOxmlElement):
     tab = ZeroOrMore("w:tab")
     footnoteReference = ZeroOrMore('w:footnoteReference')
 
-    def add_footnoteReference(self, id):
+    def add_footnoteReference(self, id: int) -> CT_FtnEdnRef:
         """
         Return a newly added ``<w:footnoteReference>`` element containing
         the footnote reference id.
@@ -105,7 +109,7 @@ def lastRenderedPageBreaks(self) -> List[CT_LastRenderedPageBreak]:
         return self.xpath("./w:lastRenderedPageBreak")
 
     @property
-    def footnote_reference_ids(self):
+    def footnote_reference_ids(self) -> List[int] | None:
         """
         Return all footnote reference ids (``<w:footnoteReference>``), or |None| if not present.
         """
@@ -117,7 +121,7 @@ def footnote_reference_ids(self):
             references = None
         return references
 
-    def increment_containing_footnote_reference_ids(self):
+    def increment_containing_footnote_reference_ids(self) -> CT_FtnEdnRef | None:
         """
         Increment all footnote reference ids by one if they exist.
         Return all footnote reference ids (``<w:footnoteReference>``), or |None| if not present.