footnotes: add footnoteReference <w:footnoteReference>, and footnotes <w:footnotes> support.

Author: tiberlas

src/docx/__init__.py

@@ -26,6 +26,7 @@
 from docx.opc.part import PartFactory
 from docx.opc.parts.coreprops import CorePropertiesPart
 from docx.parts.document import DocumentPart
+from docx.parts.footnotes import FootnotesPart
 from docx.parts.hdrftr import FooterPart, HeaderPart
 from docx.parts.image import ImagePart
 from docx.parts.numbering import NumberingPart
@@ -43,6 +44,7 @@ def part_class_selector(content_type: str, reltype: str) -> Type[Part] | None:
 PartFactory.part_type_for[CT.OPC_CORE_PROPERTIES] = CorePropertiesPart
 PartFactory.part_type_for[CT.WML_DOCUMENT_MAIN] = DocumentPart
 PartFactory.part_type_for[CT.WML_FOOTER] = FooterPart
+PartFactory.part_type_for[CT.WML_FOOTNOTES] = FootnotesPart
 PartFactory.part_type_for[CT.WML_HEADER] = HeaderPart
 PartFactory.part_type_for[CT.WML_NUMBERING] = NumberingPart
 PartFactory.part_type_for[CT.WML_SETTINGS] = SettingsPart
@@ -53,6 +55,7 @@ def part_class_selector(content_type: str, reltype: str) -> Type[Part] | None:
     CorePropertiesPart,
     DocumentPart,
     FooterPart,
+    FootnotesPart,
     HeaderPart,
     NumberingPart,
     PartFactory,

src/docx/document.py

@@ -112,6 +112,11 @@ def core_properties(self):
         """A |CoreProperties| object providing Dublin Core properties of document."""
         return self._part.core_properties
 
+    @property
+    def footnotes(self):
+        """A |Footnotes| object providing access to footnote elements in this document."""
+        return self._part.footnotes
+
     @property
     def inline_shapes(self):
         """The |InlineShapes| collection for this document.
@@ -174,6 +179,10 @@ def tables(self) -> List[Table]:
         """
         return self._body.tables
 
+    def _add_footnote(self, footnote_reference_ids):
+        """Inserts a newly created footnote to |Footnotes|."""
+        return self._part.footnotes.add_footnote(footnote_reference_ids)
+
     @property
     def _block_width(self) -> Length:
         """A |Length| object specifying the space between margins in last section."""
@@ -187,6 +196,46 @@ def _body(self) -> _Body:
             self.__body = _Body(self._element.body, self)
         return self.__body
 
+    def _calculate_next_footnote_reference_id(self, p):
+        """
+        Return the appropriate footnote reference id number for
+        a new footnote added at the end of paragraph `p`.
+        """
+        # When adding a footnote it can be inserted 
+        # in front of some other footnotes, so
+        # we need to sort footnotes by `footnote_reference_id`
+        # in |Footnotes| and in |Paragraph|
+        new_fr_id = 1
+        # If paragraph already contains footnotes
+        # append the new footnote and the end with the next reference id.
+        if p.footnote_reference_ids is not None:
+            new_fr_id = p.footnote_reference_ids[-1] + 1
+        # Read the paragraphs containing footnotes and find where the
+        # new footnote will be. Keeping in mind that the footnotes are
+        # sorted by id.
+        # The value of the new footnote id is the value of the first paragraph
+        # containing the footnote id that is before the new footnote, incremented by one.
+        # If a paragraph with footnotes is after the new footnote
+        # then increment thous footnote ids.
+        has_passed_containing_para = False
+        for p_i in reversed(range(len(self.paragraphs))):
+            # mark when we pass the paragraph containing the footnote
+            if p is self.paragraphs[p_i]._p:
+                has_passed_containing_para = True
+                continue
+            # Skip paragraphs without footnotes (they don't impact new id).
+            if self.paragraphs[p_i]._p.footnote_reference_ids is None:
+                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()
+            else:
+                # This is the last footnote before the new footnote, so we use its
+                # value to determent the value of the new footnote.
+                new_fr_id = max(self.paragraphs[p_i]._p.footnote_reference_ids)+1
+                break
+        return new_fr_id
+
 
 class _Body(BlockItemContainer):
     """Proxy for `<w:body>` element in this document.

src/docx/footnotes.py

@@ -0,0 +1,82 @@
+"""The |Footnotes| object and related proxy classes."""
+
+from __future__ import annotations
+
+from docx.blkcntnr import BlockItemContainer
+from docx.shared import Parented
+
+
+class Footnotes(Parented):
+    """
+    Proxy object wrapping ``<w:footnotes>`` element.
+    """
+    def __init__(self, footnotes, parent):
+        super(Footnotes, self).__init__(parent)
+        self._element = self._footnotes = footnotes
+
+    def __getitem__(self, reference_id):
+        """
+        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|
+        """
+        footnote = self._element.get_by_id(reference_id)
+        if footnote is None:
+            raise IndexError
+        return Footnote(footnote, self)
+
+    def __len__(self):
+        return len(self._element)
+
+    def add_footnote(self, footnote_reference_id):
+        """
+        Return a newly created |Footnote|, the new footnote will
+        be inserted in the correct spot by `footnote_reference_id`.
+        The footnotes are kept in order by `footnote_reference_id`.
+        """
+        elements = self._element # for easy access
+        new_footnote = None
+        if elements.get_by_id(footnote_reference_id):
+            # When adding a footnote it can be inserted 
+            # in front of some other footnotes, so
+            # we need to sort footnotes by `footnote_reference_id`
+            # in |Footnotes| and in |Paragraph|
+            #
+            # resolve reference ids in |Footnotes|
+            # iterate in reverse and compare the current
+            # id with the inserted id. If there are the same
+            # insert the new footnote in that place, if not
+            # increment the current footnote id.
+            for index in reversed(range(len(elements))):
+                if elements[index].id == footnote_reference_id:
+                    elements[index].id += 1
+                    new_footnote = elements[index].add_footnote_before(footnote_reference_id)
+                    break
+                else:
+                    elements[index].id += 1
+        else:
+            # append the newly created |Footnote| to |Footnotes|
+            new_footnote = elements.add_footnote(footnote_reference_id)
+        return Footnote(new_footnote, self)
+
+
+class Footnote(BlockItemContainer):
+    """
+    Proxy object wrapping ``<w:footnote>`` element.
+    """
+    def __init__(self, f, parent):
+        super(Footnote, self).__init__(f, parent)
+        self._f = self._element = f
+
+    def __eq__(self, other):
+        if isinstance(other, Footnote):
+            return self._f is other._f
+        return False
+
+    def __ne__(self, other):
+        if isinstance(other, Footnote):
+            return self._f is not other._f
+        return True
+
+    @property
+    def id(self):
+        return self._f.id

src/docx/oxml/__init__.py

@@ -241,3 +241,15 @@
 register_element_cls("w:tab", CT_TabStop)
 register_element_cls("w:tabs", CT_TabStops)
 register_element_cls("w:widowControl", CT_OnOff)
+
+# ---------------------------------------------------------------------------
+# footnote-related mappings
+
+from .footnote import (
+    CT_FtnEnd,
+    CT_Footnotes
+)
+from .text.footnote_reference import CT_FtnEdnRef
+register_element_cls('w:footnoteReference',  CT_FtnEdnRef)
+register_element_cls('w:footnote',           CT_FtnEnd)
+register_element_cls('w:footnotes',          CT_Footnotes)

src/docx/oxml/footnote.py

@@ -0,0 +1,61 @@
+"""Custom element classes related to footnote (CT_FtnEnd, CT_Footnotes)."""
+
+from docx.oxml.ns import qn
+from docx.oxml.parser import OxmlElement
+from docx.oxml.xmlchemy import (
+    BaseOxmlElement, RequiredAttribute, ZeroOrMore, OneOrMore
+)
+from docx.oxml.simpletypes import (
+    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('w:footnote[@w:id="%s"]' % id)
+        if not found:
+            return None
+        return found[0]
+
+
+class CT_FtnEnd(BaseOxmlElement):
+    """
+    ``<w:footnote>`` element, containing the properties for a specific footnote
+    """
+    id = RequiredAttribute('w:id', ST_DecimalNumber)
+    p = ZeroOrMore('w:p')
+
+    def add_footnote_before(self, footnote_reference_id):
+        """
+        Create a ``<w:footnote>`` element with `footnote_reference_id`
+        and insert it before the current element.
+        """
+        new_footnote = OxmlElement('w:footnote')
+        new_footnote.id = footnote_reference_id
+        self.addprevious(new_footnote)
+        return new_footnote
+
+    @property
+    def paragraphs(self):
+        """
+        Returns a list of paragraphs |CT_P|, or |None| if none paragraph is present.
+        """
+        paragraphs = []
+        for child in self:
+            if child.tag == qn('w:p'):
+                paragraphs.append(child)
+        if paragraphs == []:
+            paragraphs = None
+        return paragraphs

src/docx/oxml/text/footnote_reference.py

@@ -0,0 +1,15 @@
+"""Custom element classes related to footnote references (CT_FtnEdnRef)."""
+
+from docx.oxml.xmlchemy import (
+    BaseOxmlElement, RequiredAttribute, OptionalAttribute
+)
+from docx.oxml.simpletypes import (
+    ST_DecimalNumber, ST_OnOff
+)
+
+class CT_FtnEdnRef(BaseOxmlElement):
+    """
+    ``<w:footnoteReference>`` element, containing the properties for a footnote reference
+    """
+    id = RequiredAttribute('w:id', ST_DecimalNumber)
+    customMarkFollows = OptionalAttribute('w:customMarkFollows', ST_OnOff)

src/docx/oxml/text/paragraph.py

@@ -70,6 +70,21 @@ def lastRenderedPageBreaks(self) -> List[CT_LastRenderedPageBreak]:
             "./w:r/w:lastRenderedPageBreak | ./w:hyperlink/w:r/w:lastRenderedPageBreak"
         )
 
+    @property
+    def footnote_reference_ids(self):
+        """
+        Return all footnote reference ids (``<w:footnoteReference>``) form the paragraph,
+        or |None| if not present.
+        """
+        footnote_ids = []
+        for run in self.r_lst:
+            new_footnote_ids = run.footnote_reference_ids
+            if new_footnote_ids:
+                footnote_ids.extend(new_footnote_ids)
+        if footnote_ids == []:
+            footnote_ids = None
+        return footnote_ids
+
     def set_sectPr(self, sectPr: CT_SectPr):
         """Unconditionally replace or add `sectPr` as grandchild in correct sequence."""
         pPr = self.get_or_add_pPr()

src/docx/oxml/text/run.py

@@ -35,6 +35,18 @@ class CT_R(BaseOxmlElement):
     drawing = ZeroOrMore("w:drawing")
     t = ZeroOrMore("w:t")
     tab = ZeroOrMore("w:tab")
+    footnoteReference = ZeroOrMore('w:footnoteReference')
+
+    def add_footnoteReference(self, id):
+        """
+        Return a newly added ``<w:footnoteReference>`` element containing
+        the footnote reference id.
+        """
+        rPr = self._add_rPr()
+        rPr.style = 'FootnoteReference'
+        new_fr = self._add_footnoteReference()
+        new_fr.id = id
+        return new_fr
 
     def add_t(self, text: str) -> CT_Text:
         """Return a newly added `<w:t>` element containing `text`."""
@@ -92,6 +104,30 @@ def lastRenderedPageBreaks(self) -> List[CT_LastRenderedPageBreak]:
         """All `w:lastRenderedPageBreaks` descendants of this run."""
         return self.xpath("./w:lastRenderedPageBreak")
 
+    @property
+    def footnote_reference_ids(self):
+        """
+        Return all footnote reference ids (``<w:footnoteReference>``), or |None| if not present.
+        """
+        references = []
+        for child in self:
+            if child.tag == qn('w:footnoteReference'):
+               references.append(child.id)
+        if references == []:
+            references = None
+        return references
+
+    def increment_containing_footnote_reference_ids(self):
+        """
+        Increment all footnote reference ids by one if they exist.
+        Return all footnote reference ids (``<w:footnoteReference>``), or |None| if not present.
+        """
+        if self.footnoteReference_lst is not None:
+            for i in range(len(self.footnoteReference_lst)):
+                self.footnoteReference_lst[i].id += 1
+            return self.footnoteReference_lst
+        return None
+
     @property
     def style(self) -> str | None:
         """String contained in `w:val` attribute of `w:rStyle` grandchild.

src/docx/parts/document.py

@@ -7,6 +7,7 @@
 from docx.document import Document
 from docx.enum.style import WD_STYLE_TYPE
 from docx.opc.constants import RELATIONSHIP_TYPE as RT
+from docx.parts.footnotes import FootnotesPart
 from docx.parts.hdrftr import FooterPart, HeaderPart
 from docx.parts.numbering import NumberingPart
 from docx.parts.settings import SettingsPart
@@ -61,6 +62,14 @@ def footer_part(self, rId: str):
         """Return |FooterPart| related by `rId`."""
         return self.related_parts[rId]
 
+    @property
+    def footnotes(self):
+        """
+        A |Footnotes| object providing access to the footnotes in the footnotes part
+        of this document.
+        """
+        return self._footnotes_part.footnotes
+
     def get_style(self, style_id: str | None, style_type: WD_STYLE_TYPE) -> BaseStyle:
         """Return the style in this document matching `style_id`.
 
@@ -119,6 +128,19 @@ def styles(self):
         document."""
         return self._styles_part.styles
 
+    @property
+    def _footnotes_part(self):
+        """
+        Instance of |FootnotesPart| for this document. Creates an empty footnotes
+        part if one is not present.
+        """
+        try:
+            return self.part_related_by(RT.FOOTNOTES)
+        except KeyError:
+            footnotes_part = FootnotesPart.default(self.package)
+            self.relate_to(footnotes_part, RT.FOOTNOTES)
+            return footnotes_part
+
     @property
     def _settings_part(self) -> SettingsPart:
         """A |SettingsPart| object providing access to the document-level settings for