rfctr: Blacken footnote support

Author: tiberlas

features/steps/footnotes.py

@@ -1,6 +1,6 @@
 """Step implementations for footnote-related features."""
 
-from behave import given, when, then
+from behave import given, then, when
 from behave.runner import Context
 
 from docx import Document
@@ -44,7 +44,9 @@ def given_a_paragraph_in_a_document_without_footnotes(context: Context):
     context.footnotes = document.footnotes
 
 
-@given("a document with paragraphs[0] containing one, paragraphs[1] containing none, and paragraphs[2] containing two footnotes")
+@given(
+    "a document with paragraphs[0] containing one, paragraphs[1] containing none, and paragraphs[2] containing two footnotes"
+)
 def given_a_document_with_3_footnotes(context: Context):
     document = Document(test_docx("footnotes"))
     context.paragraphs = document.paragraphs
@@ -64,14 +66,18 @@ def when_I_try_to_access_a_footnote_with_invalid_reference_id(context: Context):
 
 
 @when("I add a footnote to the paragraphs[{parId}] with text '{footnoteText}'")
-def when_I_add_a_footnote_to_the_paragraph_with_text_text(context: Context, parId: str, footnoteText: str):
+def when_I_add_a_footnote_to_the_paragraph_with_text_text(
+    context: Context, parId: str, footnoteText: str
+):
     par = context.paragraphs[int(parId)]
     new_footnote = par.add_footnote()
     new_footnote.add_paragraph(footnoteText)
 
 
 @when("I change footnote property {propName} to {value}")
-def when_I_change_footnote_property_propName_to_value(context: Context, propName: str, value: str):
+def when_I_change_footnote_property_propName_to_value(
+    context: Context, propName: str, value: str
+):
     context.section.__setattr__(propName, eval(value))
 
 
@@ -81,7 +87,9 @@ def when_I_change_footnote_property_propName_to_value(context: Context, propName
 @then("len(footnotes) is {expectedLen}")
 def then_len_footnotes_is_len(context: Context, expectedLen: str):
     footnotes = context.footnotes
-    assert len(footnotes) == int(expectedLen), f"expected len(footnotes) of {expectedLen}, got {len(footnotes)}"
+    assert len(footnotes) == int(
+        expectedLen
+    ), f"expected len(footnotes) of {expectedLen}, got {len(footnotes)}"
 
 
 @then("I can access a footnote by footnote reference id")
@@ -107,35 +115,57 @@ def then_it_trows_an_IndexError(context: Context, exceptionType: str):
 
 
 @then("I can access footnote property {propName} with value {value}")
-def then_I_can_access_footnote_propery_name_with_value_value(context: Context, propName: str, value: str):
+def then_I_can_access_footnote_propery_name_with_value_value(
+    context: Context, propName: str, value: str
+):
     actual_value = context.section.__getattribute__(propName)
     expected = eval(value)
-    assert actual_value == expected, f"expected section.{propName} {value}, got {expected}"
+    assert (
+        actual_value == expected
+    ), f"expected section.{propName} {value}, got {expected}"
 
 
-@then("the document contains a footnote with footnote reference id of {refId} with text '{footnoteText}'")
-def then_the_document_contains_a_footnote_with_footnote_reference_id_of_refId_with_text_text(context: Context, refId: str, footnoteText: str):
+@then(
+    "the document contains a footnote with footnote reference id of {refId} with text '{footnoteText}'"
+)
+def then_the_document_contains_a_footnote_with_footnote_reference_id_of_refId_with_text_text(
+    context: Context, refId: str, footnoteText: str
+):
     par = context.paragraphs[1]
     f = par.footnotes[0]
     assert f.id == int(refId), f"expected {refId}, got {f.id}"
-    assert f.paragraphs[0].text == footnoteText, f"expected {footnoteText}, got {f.paragraphs[0].text}"
+    assert (
+        f.paragraphs[0].text == footnoteText
+    ), f"expected {footnoteText}, got {f.paragraphs[0].text}"
 
 
-@then("paragraphs[{parId}] has footnote reference ids of {refIds}, with footnote text {fText}")
-def then_paragraph_has_footnote_reference_ids_of_refIds_with_footnote_text_text(context: Context, parId: str, refIds: str, fText: str):
+@then(
+    "paragraphs[{parId}] has footnote reference ids of {refIds}, with footnote text {fText}"
+)
+def then_paragraph_has_footnote_reference_ids_of_refIds_with_footnote_text_text(
+    context: Context, parId: str, refIds: str, fText: str
+):
     par = context.paragraphs[int(parId)]
     refIds = eval(refIds)
     fText = eval(fText)
     if refIds is not None:
         if type(refIds) is list:
             for i in range(len(refIds)):
                 f = par.footnotes[i]
-                assert isinstance(f, Footnote), f"expected to be instance of Footnote, got {type(f)}"
+                assert isinstance(
+                    f, Footnote
+                ), f"expected to be instance of Footnote, got {type(f)}"
                 assert f.id == refIds[i], f"expected {refIds[i]}, got {f.id}"
-                assert f.paragraphs[0].text == fText[i], f"expected '{fText[i]}', got '{f.paragraphs[0].text}'"
+                assert (
+                    f.paragraphs[0].text == fText[i]
+                ), f"expected '{fText[i]}', got '{f.paragraphs[0].text}'"
         else:
             f = par.footnotes[0]
             assert f.id == int(refIds), f"expected {refIds}, got {f.id}"
-            assert f.paragraphs[0].text == fText, f"expected '{fText}', got '{f.paragraphs[0].text}'"
+            assert (
+                f.paragraphs[0].text == fText
+            ), f"expected '{fText}', got '{f.paragraphs[0].text}'"
     else:
-        assert len(par.footnotes) == 0, f"expected an empty list, got {len(par.footnotes)} elements"
+        assert (
+            len(par.footnotes) == 0
+        ), f"expected an empty list, got {len(par.footnotes)} elements"

src/docx/document.py

@@ -16,14 +16,14 @@
 if TYPE_CHECKING:
     import docx.types as t
     from docx.oxml.document import CT_Body, CT_Document
+    from docx.oxml.footnote import CT_Footnotes, CT_FtnEnd
+    from docx.oxml.text.paragraph import CT_P
     from docx.parts.document import DocumentPart
     from docx.settings import Settings
     from docx.shared import Length
     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):
@@ -199,11 +199,9 @@ def _body(self) -> _Body:
         return self.__body
 
     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`.
-        """
-        # When adding a footnote it can be inserted 
+        """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|
@@ -234,7 +232,7 @@ def _calculate_next_footnote_reference_id(self, p: CT_P) -> int:
             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
+                new_fr_id = max(self.paragraphs[p_i]._p.footnote_reference_ids) + 1
                 break
         return new_fr_id
 

src/docx/footnotes.py

@@ -9,21 +9,18 @@
 
 if TYPE_CHECKING:
     from docx import types as t
-    from docx.oxml.footnote import CT_FtnEnd, CT_Footnotes
+    from docx.oxml.footnote import CT_Footnotes, CT_FtnEnd
+
 
 class Footnotes(Parented):
-    """
-    Proxy object wrapping ``<w:footnotes>`` element.
-    """
+    """Proxy object wrapping ``<w:footnotes>`` element."""
+
     def __init__(self, footnotes: CT_Footnotes, parent: t.ProvidesStoryPart):
         super(Footnotes, self).__init__(parent)
         self._element = self._footnotes = footnotes
 
     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|
-        """
+        """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
@@ -33,15 +30,13 @@ def __len__(self) -> int:
         return len(self._element)
 
     def add_footnote(self, footnote_reference_id: int) -> Footnote:
-        """
-        Return a newly created |Footnote|, the new footnote will
+        """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
+        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) is not None:
-            # When adding a footnote it can be inserted 
+            # 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|
@@ -54,7 +49,9 @@ def add_footnote(self, footnote_reference_id: int) -> Footnote:
             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)
+                    new_footnote = elements[index].add_footnote_before(
+                        footnote_reference_id
+                    )
                     break
                 else:
                     elements[index].id += 1
@@ -65,10 +62,9 @@ def add_footnote(self, footnote_reference_id: int) -> Footnote:
 
 
 class Footnote(BlockItemContainer):
-    """
-    Proxy object wrapping ``<w:footnote>`` element.
-    """
-    def __init__(self, f: CT_FtnEnd, parent:  t.ProvidesStoryPart):
+    """Proxy object wrapping ``<w:footnote>`` element."""
+
+    def __init__(self, f: CT_FtnEnd, parent: t.ProvidesStoryPart):
         super(Footnote, self).__init__(f, parent)
         self._f = self._element = f
 

src/docx/oxml/__init__.py

@@ -117,17 +117,17 @@
     CT_SectType,
 )
 
-register_element_cls('w:footnotePr',           CT_FtnProps)
+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: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:pos", CT_FtnPos)
 register_element_cls("w:sectPr", CT_SectPr)
 register_element_cls("w:type", CT_SectType)
 
@@ -254,11 +254,9 @@
 # ---------------------------------------------------------------------------
 # footnote-related mappings
 
-from .footnote import (
-    CT_FtnEnd,
-    CT_Footnotes
-)
+from .footnote import CT_Footnotes, CT_FtnEnd
 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)
+
+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

@@ -6,30 +6,23 @@
 
 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
-)
+from docx.oxml.simpletypes import ST_DecimalNumber
+from docx.oxml.xmlchemy import BaseOxmlElement, OneOrMore, RequiredAttribute, ZeroOrMore
 
 if TYPE_CHECKING:
     from docx.oxml.text.paragraph import CT_P
 
 
 class CT_FtnEnd(BaseOxmlElement):
-    """
-    ``<w:footnote>`` element, containing the properties for a specific footnote
-    """
-    id = RequiredAttribute('w:id', ST_DecimalNumber)
-    p = ZeroOrMore('w:p')
+    """``<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: int) -> CT_FtnEnd:
-        """
-        Create a ``<w:footnote>`` element with `footnote_reference_id`
-        and insert it before the current element.
-        """
-        new_footnote = OxmlElement('w:footnote')
+        """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
@@ -40,23 +33,20 @@ def paragraphs(self) -> List[CT_P]:
 
         paragraphs = []
         for child in self:
-            if child.tag == qn('w:p'):
+            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
-    """
+    """``<w:footnotes>`` element, containing a sequence of footnote (w:footnote) elements"""
+
     add_footnote_sequence: Callable[[], CT_FtnEnd]
 
-    footnote_sequence = OneOrMore('w:footnote')
+    footnote_sequence = OneOrMore("w:footnote")
 
     def add_footnote(self, footnote_reference_id: int) -> CT_FtnEnd:
-        """
-        Create a ``<w:footnote>`` element with `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