Skip to content

footnotes

footnotes

Custom element classes related to document footnotes and endnotes.

Footnotes and endnotes are the same feature in two places. The schema gives both w:footnote and w:endnote the type CT_FtnEdn, both parts wrap a sequence of those, and w:footnoteReference and w:endnoteReference are both CT_FtnEdnRef. Only the tag names and the reference-mark element differ, so this module models the pair once and subclasses for the two spellings.

_CT_FtnEdnCollection

Bases: BaseOxmlElement

Common behavior of the w:footnotes and w:endnotes root elements.

They differ only in the tag of their children, the reference-mark element that goes in a new note, and the styles Word applies to one; _tag, _ref_tag, _para_style and _char_style name those.

note_lst property 

note_lst: List[CT_FtnEdn]

The w:footnote or w:endnote children, in document order.

add_note 

add_note() -> CT_FtnEdn

Return a newly added note child of this element.

The returned element is the minimum valid value: a w:id unique among the existing notes and a single paragraph holding the reference mark that Word renders as the note number. Content is added by adding runs to that paragraph and by adding further paragraphs.

Source code in src/docx/oxml/footnotes.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
def add_note(self) -> CT_FtnEdn:
    """Return a newly added note child of this element.

    The returned element is the minimum valid value: a `w:id` unique among the
    existing notes and a single paragraph holding the reference mark that Word
    renders as the note number. Content is added by adding runs to that paragraph
    and by adding further paragraphs.
    """
    next_id = self._next_available_note_id()
    note = cast(
        "CT_FtnEdn",
        parse_xml(
            f'<{self._tag} {nsdecls("w")} w:id="{next_id}">'
            f"  <w:p>"
            f"    <w:pPr>"
            f'      <w:pStyle w:val="{self._para_style}"/>'
            f"    </w:pPr>"
            f"    <w:r>"
            f"      <w:rPr>"
            f'        <w:rStyle w:val="{self._char_style}"/>'
            f"      </w:rPr>"
            f"      <{self._ref_tag}/>"
            f"    </w:r>"
            f"  </w:p>"
            f"</{self._tag}>"
        ),
    )
    self.append(note)
    return note

get_note_by_id 

get_note_by_id(note_id: int) -> CT_FtnEdn | None

The note element identified by note_id, or None if not found.

Source code in src/docx/oxml/footnotes.py 
82
83
84
85
def get_note_by_id(self, note_id: int) -> CT_FtnEdn | None:
    """The note element identified by `note_id`, or |None| if not found."""
    note_elms = self.xpath(f"(./{self._tag}[@w:id='{note_id}'])[1]")
    return note_elms[0] if note_elms else None

iter_authored_notes 

iter_authored_notes() -> List[CT_FtnEdn]

The note elements an author wrote, in document order.

The structural separator notes Word keeps at ids -1 and 0 are left out; see STRUCTURAL_FOOTNOTE_TYPES.

Source code in src/docx/oxml/footnotes.py 
87
88
89
90
91
92
93
def iter_authored_notes(self) -> List[CT_FtnEdn]:
    """The note elements an author wrote, in document order.

    The structural separator notes Word keeps at ids -1 and 0 are left out; see
    `STRUCTURAL_FOOTNOTE_TYPES`.
    """
    return [f for f in self.note_lst if not f.is_structural]

CT_Footnotes

Bases: _CT_FtnEdnCollection

w:footnotes element, the root element for the footnotes part.

Contains a w:footnote element for each footnote in the document, plus the structural separator footnotes Word keeps at ids -1 and 0.

CT_Endnotes

Bases: _CT_FtnEdnCollection

w:endnotes element, the root element for the endnotes part.

The endnote half of CT_Footnotes; the two are the same complex type in the schema.

CT_FtnEdn

Bases: BaseOxmlElement

w:footnote or w:endnote element, a single note.

A footnote is a "story" and can contain paragraphs and tables much like a table cell, so its content can be rich: multiple paragraphs, hyperlinks, images and tables.

inner_content_elements property 

inner_content_elements: List[CT_P | CT_Tbl]

All w:p and w:tbl elements in this footnote, in document order.

Content inside a w:sdt (content control) wrapper is included.

is_structural property 

is_structural: bool

True when this is one of Word's separator footnotes rather than an author's.

These are the footnotes Word keeps at ids -1 and 0 to draw the rule above the footnote area and its continuation.

CT_FtnEdnRef

Bases: BaseOxmlElement

w:footnoteReference or w:endnoteReference, the mark that cites a note.