footnotes

footnotes

Collections providing access to the footnotes and endnotes of the document.

Footnotes and endnotes are the same feature placed differently — a footnote at the foot of its page, an endnote at the end of the document or section. They share a complex type in the schema and share their implementation here; see docx.oxml.footnotes.

_Notes

_Notes(
    notes_elm: _CT_FtnEdnCollection, notes_part: StoryPart
)

Common behavior of the Footnotes and Endnotes collections.

Only the notes an author wrote are in the collection. Word keeps two more in the same part, at ids -1 and 0, which hold the rule it draws above the note area and its continuation on the next page; those are structural and never appear here.

Source code in src/docx/footnotes.py

def __init__(self, notes_elm: _CT_FtnEdnCollection, notes_part: StoryPart):
    self._notes_elm = notes_elm
    self._notes_part = notes_part

_Note

_Note(note_elm: CT_FtnEdn, notes_part: StoryPart)

Bases: BlockItemContainer

Common behavior of the Footnote and Endnote proxies.

A note is a block-item container, like a table cell, so it can hold both paragraphs and tables and its paragraphs can hold rich text, hyperlinks and images. The common case is a single paragraph of plain text.

Source code in src/docx/footnotes.py

def __init__(self, note_elm: CT_FtnEdn, notes_part: StoryPart):
    super().__init__(note_elm, notes_part)
    self._note_elm = note_elm

text property

text: str

The text content of this note as a string.

Only content in paragraphs is included, and all emphasis and styling is stripped. Paragraph boundaries are indicated with a newline ("\\n").

add_paragraph

add_paragraph(
    text: str = "",
    style: str | ParagraphStyle | None = None,
) -> Paragraph

Return a paragraph newly added to the end of this note.

The paragraph holds text in a single run if present and is given paragraph style style. When style is omitted or None, the style Word uses for this kind of note's content is applied — "FootnoteText" or "EndnoteText".

Source code in src/docx/footnotes.py

def add_paragraph(self, text: str = "", style: str | ParagraphStyle | None = None) -> Paragraph:
    """Return a paragraph newly added to the end of this note.

    The paragraph holds `text` in a single run if present and is given paragraph
    style `style`. When `style` is omitted or |None|, the style Word uses for this
    kind of note's content is applied — "FootnoteText" or "EndnoteText".
    """
    paragraph = super().add_paragraph(text, style)

    # -- assign the style directly to the element, since `paragraph.style` raises
    # -- when the style is not defined in the styles part and Word supplies this one
    # -- as a latent style
    if style is None:
        paragraph._p.style = self._para_style  # pyright: ignore[reportPrivateUsage]

    return paragraph

Footnote

Footnote(note_elm: CT_FtnEdn, notes_part: StoryPart)

Bases: _Note

Proxy for a single footnote in the document.

Source code in src/docx/footnotes.py

def __init__(self, note_elm: CT_FtnEdn, notes_part: StoryPart):
    super().__init__(note_elm, notes_part)
    self._note_elm = note_elm

footnote_id property

footnote_id: int

The identifier a w:footnoteReference uses to cite this footnote.

Endnote

Endnote(note_elm: CT_FtnEdn, notes_part: StoryPart)

Bases: _Note

Proxy for a single endnote in the document.

Source code in src/docx/footnotes.py

def __init__(self, note_elm: CT_FtnEdn, notes_part: StoryPart):
    super().__init__(note_elm, notes_part)
    self._note_elm = note_elm

endnote_id property

endnote_id: int

The identifier a w:endnoteReference uses to cite this endnote.

Footnotes

Footnotes(
    notes_elm: _CT_FtnEdnCollection, notes_part: StoryPart
)

Bases: _Notes

Collection containing the footnotes of this document.

Only the footnotes an author wrote are in the collection. Word keeps two more in the same part, at ids -1 and 0, which hold the rule it draws above the footnote area and its continuation on the next page; those are structural and never appear here.

Source code in src/docx/footnotes.py

def __init__(self, notes_elm: _CT_FtnEdnCollection, notes_part: StoryPart):
    self._notes_elm = notes_elm
    self._notes_part = notes_part

add_footnote

add_footnote(text: str = '') -> Footnote

Add a new footnote to the document and return it.

The footnote is added to the end of the footnotes collection and is assigned an id unique within it. Adding it does not place a reference to it in the body text; use Run.add_footnote_reference() for that. A footnote no run references does not appear in the rendered document.

If text is provided it is added to the footnote, after the reference mark that Word renders as the footnote number. Multiple paragraphs can be added by separating their text with newlines ("\\n"); between newlines, text is interpreted as it is in Document.add_paragraph(text=...).

The default is a footnote holding only the reference mark, to which runs can be added with footnote.paragraphs[0].add_run() and further paragraphs with .add_paragraph().

Source code in src/docx/footnotes.py

def add_footnote(self, text: str = "") -> Footnote:
    """Add a new footnote to the document and return it.

    The footnote is added to the end of the footnotes collection and is assigned an
    id unique within it. Adding it does not place a reference to it in the body
    text; use `Run.add_footnote_reference()` for that. A footnote no run references
    does not appear in the rendered document.

    If `text` is provided it is added to the footnote, after the reference mark that
    Word renders as the footnote number. Multiple paragraphs can be added by
    separating their text with newlines (`"\\\\n"`); between newlines, text is
    interpreted as it is in `Document.add_paragraph(text=...)`.

    The default is a footnote holding only the reference mark, to which runs can be
    added with `footnote.paragraphs[0].add_run()` and further paragraphs with
    `.add_paragraph()`.
    """
    return self._add_note(text)  # pyright: ignore[reportReturnType]

get

get(footnote_id: int) -> Footnote | None

The footnote identified by footnote_id, or None if there is none.

None is also returned for the ids of Word's structural separator footnotes, which are not footnotes of this document in any sense an author would mean.

Source code in src/docx/footnotes.py

def get(self, footnote_id: int) -> Footnote | None:
    """The footnote identified by `footnote_id`, or |None| if there is none.

    |None| is also returned for the ids of Word's structural separator footnotes,
    which are not footnotes of this document in any sense an author would mean.
    """
    return self._get(footnote_id)  # pyright: ignore[reportReturnType]

Endnotes

Endnotes(
    notes_elm: _CT_FtnEdnCollection, notes_part: StoryPart
)

Bases: _Notes

Collection containing the endnotes of this document.

The endnote counterpart of Footnotes, and identical to it in behavior. Where an endnote appears — end of section or end of document — is a document setting, in w:sectPr/w:endnotePr and w:settings/w:endnotePr, and is not exposed here.

Source code in src/docx/footnotes.py

def __init__(self, notes_elm: _CT_FtnEdnCollection, notes_part: StoryPart):
    self._notes_elm = notes_elm
    self._notes_part = notes_part

add_endnote

add_endnote(text: str = '') -> Endnote

Add a new endnote to the document and return it.

As for Footnotes.add_footnote(): the endnote is given an id unique within the collection, and adding it does not place a reference to it in the body text — use Run.add_endnote_reference() for that. An endnote no run references does not appear in the rendered document.

Source code in src/docx/footnotes.py

def add_endnote(self, text: str = "") -> Endnote:
    """Add a new endnote to the document and return it.

    As for `Footnotes.add_footnote()`: the endnote is given an id unique within the
    collection, and adding it does not place a reference to it in the body text —
    use `Run.add_endnote_reference()` for that. An endnote no run references does
    not appear in the rendered document.
    """
    return self._add_note(text)  # pyright: ignore[reportReturnType]

get

get(endnote_id: int) -> Endnote | None

The endnote identified by endnote_id, or None if there is none.

Source code in src/docx/footnotes.py

def get(self, endnote_id: int) -> Endnote | None:
    """The endnote identified by `endnote_id`, or |None| if there is none."""
    return self._get(endnote_id)  # pyright: ignore[reportReturnType]