footnotes: add footnote properties

Author: tiberlas

src/docx/oxml/__init__.py

@@ -105,20 +105,29 @@
 register_element_cls("w:startOverride", CT_DecimalNumber)
 
 from .section import (  # noqa
+    CT_FtnProps,
+    CT_FtnPos,
     CT_HdrFtr,
     CT_HdrFtrRef,
     CT_PageMar,
     CT_PageSz,
+    CT_NumFmt,
+    CT_NumRestart,
     CT_SectPr,
     CT_SectType,
 )
 
+register_element_cls('w:footnotePr',           CT_FtnProps)
 register_element_cls("w:footerReference", CT_HdrFtrRef)
 register_element_cls("w:ftr", CT_HdrFtr)
 register_element_cls("w:hdr", CT_HdrFtr)
 register_element_cls("w:headerReference", CT_HdrFtrRef)
+register_element_cls('w:numFmt',           CT_NumFmt)
+register_element_cls('w:numStart',           CT_DecimalNumber)
+register_element_cls('w:numRestart',           CT_NumRestart)
 register_element_cls("w:pgMar", CT_PageMar)
 register_element_cls("w:pgSz", CT_PageSz)
+register_element_cls('w:pos',           CT_FtnPos)
 register_element_cls("w:sectPr", CT_SectPr)
 register_element_cls("w:type", CT_SectType)
 

src/docx/oxml/section.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from warnings import warn
+
 from copy import deepcopy
 from typing import Callable, Iterator, List, Sequence, cast
 
@@ -11,7 +13,7 @@
 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
+from docx.oxml.simpletypes import ST_SignedTwipsMeasure, ST_TwipsMeasure, XsdString, ST_FtnPos, ST_NumberFormat, ST_RestartNumber
 from docx.oxml.table import CT_Tbl
 from docx.oxml.text.paragraph import CT_P
 from docx.oxml.xmlchemy import (
@@ -26,6 +28,22 @@
 BlockElement: TypeAlias = "CT_P | CT_Tbl"
 
 
+class CT_FtnPos(BaseOxmlElement):
+    """``<w:pos>`` element, footnote placement"""
+    val = RequiredAttribute('w:val', ST_FtnPos)
+
+
+class CT_FtnProps(BaseOxmlElement):
+    """``<w:footnotePr>`` element, section wide footnote properties"""
+    _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:])
+
+
 class CT_HdrFtr(BaseOxmlElement):
     """`w:hdr` and `w:ftr`, the root element for header and footer part respectively."""
 
@@ -57,6 +75,16 @@ class CT_HdrFtrRef(BaseOxmlElement):
     rId: str = RequiredAttribute("r:id", XsdString)  # pyright: ignore[reportAssignmentType]
 
 
+class CT_NumFmt(BaseOxmlElement):
+    """``<w:numFmt>`` element, footnote numbering format"""
+    val = RequiredAttribute('w:val', ST_NumberFormat)
+
+
+class CT_NumRestart(BaseOxmlElement):
+    """``<w:numStart>`` element, footnote numbering restart location"""
+    val = RequiredAttribute('w:val', ST_RestartNumber)
+
+
 class CT_PageMar(BaseOxmlElement):
     """``<w:pgMar>`` element, defining page margins."""
 
@@ -145,6 +173,7 @@ 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:])
     del _tag_seq
 
     def add_footerReference(self, type_: WD_HEADER_FOOTER, rId: str) -> CT_HdrFtrRef:
@@ -211,6 +240,92 @@ def footer(self, value: int | Length | None):
         pgMar = self.get_or_add_pgMar()
         pgMar.footer = value if value is None or isinstance(value, Length) else Length(value)
 
+    @property
+    def footnote_number_format(self):
+        """
+        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
+        attribute is not present.
+        """
+        fPr = self.footnotePr
+        if fPr is None or fPr.numFmt:
+            return None
+        return fPr.numFmt.val
+
+    @footnote_number_format.setter
+    def footnote_number_format(self, value):
+        fPr = self.get_or_add_footnotePr()
+        numFmt = fPr.get_or_add_numFmt()
+        numFmt.val = value
+
+    @property
+    def footnote_numbering_restart_location(self):
+        """
+        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
+        attribute is not present.
+        """
+        fPr = self.footnotePr
+        if fPr is None or fPr.numRestart:
+            return None
+        return fPr.numRestart.val
+
+    @footnote_numbering_restart_location.setter
+    def footnote_numbering_restart_location(self, value):
+        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:
+            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):
+        """
+        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
+        attribute is not present.
+        """
+        fPr = self.footnotePr
+        if fPr is None or fPr.numStart:
+            return None
+        return fPr.numStart.val
+
+    @footnote_numbering_start_value.setter
+    def footnote_numbering_start_value(self, value):
+        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:
+            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):
+        """
+        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
+        attribute is not present.
+        """
+        fPr = self.footnotePr
+        if fPr is None or fPr.pos is None:
+            return None
+        return fPr.pos.val
+
+    @footnote_position.setter
+    def footnote_position(self, value):
+        fPr = self.get_or_add_footnotePr()
+        pos = fPr.get_or_add_pos()
+        pos.val = value
+
     def get_footerReference(self, type_: WD_HEADER_FOOTER) -> CT_HdrFtrRef | None:
         """Return footerReference element of `type_` or None if not present."""
         path = "./w:footerReference[@w:type='%s']" % WD_HEADER_FOOTER.to_xml(type_)

src/docx/oxml/simpletypes.py

@@ -221,6 +221,18 @@ class ST_DrawingElementId(XsdUnsignedInt):
     pass
 
 
+class ST_FtnPos(XsdString):
+
+    @classmethod
+    def validate(cls, value):
+        cls.validate_string(value)
+        valid_values = ('pageBottom', 'beneathText', 'sectEnd', 'docEnd')
+        if value not in valid_values:
+            raise ValueError(
+                "must be one of %s, got '%s'" % (valid_values, value)
+            )
+
+
 class ST_HexColor(BaseStringType):
     @classmethod
     def convert_from_xml(  # pyright: ignore[reportIncompatibleMethodOverride]
@@ -271,6 +283,10 @@ def convert_to_xml(cls, value: int | Length) -> str:
         return str(half_points)
 
 
+class ST_NumberFormat(XsdString):
+    pass
+
+
 class ST_Merge(XsdStringEnumeration):
     """Valid values for <w:xMerge val=""> attribute."""
 
@@ -305,6 +321,17 @@ class ST_RelationshipId(XsdString):
     pass
 
 
+class ST_RestartNumber(XsdString):
+
+    @classmethod
+    def validate(cls, value):
+        cls.validate_string(value)
+        valid_values = ('continuous', 'eachSect', 'eachPage')
+        if value not in valid_values:
+            raise ValueError(
+                "must be one of %s, got '%s'" % (valid_values, value)
+            )
+
 class ST_SignedTwipsMeasure(XsdInt):
     @classmethod
     def convert_from_xml(cls, str_value: str) -> Length:

src/docx/section.py

@@ -115,6 +115,56 @@ def footer_distance(self) -> Length | None:
     def footer_distance(self, value: int | Length | None):
         self._sectPr.footer = value
 
+    @property
+    def footnote_number_format(self):
+        """The number format property for the |Footnotes|.
+
+        Read/write. |None| if no setting is present in the XML.
+        """
+        return self._sectPr.footnote_number_format
+
+    @footnote_number_format.setter
+    def footnote_number_format(self, value):
+        self._sectPr.footnote_number_format = value
+
+    @property
+    def footnote_numbering_restart_location(self):
+        """The number restart location property for the |Footnotes|.
+
+        If the value is not |continuous| then the footnote number start value property is set to |1|.
+        Read/write. |None| if no setting is present in the XML.
+        """
+        return self._sectPr.footnote_numbering_restart_location
+
+    @footnote_numbering_restart_location.setter
+    def footnote_numbering_restart_location(self, value):
+        self._sectPr.footnote_numbering_restart_location = value
+
+    @property
+    def footnote_numbering_start_value(self):
+        """The number start value property for the |Footnotes|.
+
+        If the value is not |1| then footnote number restart position property is set to |continuous|.
+        Read/write. |None| if no setting is present in the XML.
+        """
+        return self._sectPr.footnote_numbering_start_value
+
+    @footnote_numbering_start_value.setter
+    def footnote_numbering_start_value(self, value):
+        self._sectPr.footnote_numbering_start_value = value
+
+    @property
+    def footnote_position(self):
+        """The position property for the |Footnotes|.
+
+        Read/write. |None| if no setting is present in the XML.
+        """
+        return self._sectPr.footnote_position
+
+    @footnote_position.setter
+    def footnote_position(self, value):
+        self._sectPr.footnote_position = value
+
     @property
     def gutter(self) -> Length | None:
         """|Length| object representing page gutter size in English Metric Units.