bookmark

bookmark

The Bookmark and Bookmarks proxy objects.

A bookmark names a range of a document. It is the anchor mechanism everything that refers to a place in a document is built on: internal hyperlinks, cross-references, captions that renumber, and table-of-contents entries.

Bookmark

Bookmark(
    bookmarkStart: CT_BookmarkStart,
    parent: ProvidesStoryPart,
)

Bases: Parented

Proxy for a w:bookmarkStart element and the range it names.

Source code in src/docx/bookmark.py

def __init__(self, bookmarkStart: CT_BookmarkStart, parent: t.ProvidesStoryPart):
    super(Bookmark, self).__init__(parent)
    self._element = self._bookmarkStart = bookmarkStart

id property

id: int

The w:id pairing this bookmark's two delimiters.

Unique across the document.

is_closed property

is_closed: bool

True when this bookmark has a matching w:bookmarkEnd.

An unmatched start is invalid but appears in real documents, so it is reported rather than raised on. The .text of an unclosed bookmark is the empty string.

is_hidden property

is_hidden: bool

True for a bookmark Word maintains for itself.

_GoBack records the last edit position and _Toc… anchors a table-of-contents entry. Bookmarks leaves these out by default.

name property

name: str

The name of this bookmark, as shown in Word's bookmark dialog.

text property

text: str

The text of the content this bookmark spans.

Paragraph boundaries inside the range become newlines, as they do for a table cell. The empty string when the bookmark is unclosed or spans no text.

delete

delete() -> None

Remove this bookmark, leaving the content it named in place.

Removes both delimiters, including an unmatched one.

Source code in src/docx/bookmark.py

def delete(self) -> None:
    """Remove this bookmark, leaving the content it named in place.

    Removes both delimiters, including an unmatched one.
    """
    bookmarkEnd = self._bookmarkStart.bookmarkEnd
    if bookmarkEnd is not None:
        bookmarkEnd.getparent().remove(bookmarkEnd)
    self._bookmarkStart.getparent().remove(self._bookmarkStart)

Bookmarks

Bookmarks(
    element: ProvidesXmlPart, parent: ProvidesStoryPart
)

Bases: Parented, Sequence[Bookmark]

The bookmarks in a document, in document order.

Supports len(), iteration, indexed access and lookup by name:

document.bookmarks["Introduction"].text

Bookmarks Word maintains for itself, such as _GoBack and the _Toc… anchors, are left out; pass include_hidden=True to iter_all to see them.

Source code in src/docx/bookmark.py

def __init__(self, element: t.ProvidesXmlPart, parent: t.ProvidesStoryPart):
    super(Bookmarks, self).__init__(parent)
    self._element = element

get

get(
    name: str, default: Bookmark | None = None
) -> Bookmark | None

The bookmark named name, or default when there is none.

Source code in src/docx/bookmark.py

def get(self, name: str, default: Bookmark | None = None) -> Bookmark | None:
    """The bookmark named `name`, or `default` when there is none."""
    try:
        return self[name]
    except KeyError:
        return default

iter_all

iter_all(include_hidden: bool = True) -> Iterator[Bookmark]

Generate every bookmark in the document, in document order.

Includes Word's own bookmarks unless include_hidden is False, and includes a bookmark whose w:bookmarkEnd is missing.

Source code in src/docx/bookmark.py

def iter_all(self, include_hidden: bool = True) -> Iterator[Bookmark]:
    """Generate every bookmark in the document, in document order.

    Includes Word's own bookmarks unless `include_hidden` is |False|, and includes a
    bookmark whose `w:bookmarkEnd` is missing.
    """
    for bookmarkStart in self._element.xpath("//w:bookmarkStart"):
        bookmark = Bookmark(bookmarkStart, self._parent)
        if include_hidden or not bookmark.is_hidden:
            yield bookmark