doc: add Document.bookmarks

Benjamin Toornstra · scanny · commit afd1cc39c7a7 · 2019-07-13T16:34:35.000-07:00
diff --git a/docs/conf.py b/docs/conf.py
@@ -77,6 +77,10 @@
 
 .. |_Body| replace:: :class:`._Body`
 
+.. |Bookmark| replace:: :class:`.Bookmark`
+
+.. |Bookmarks| replace:: :class:`.Bookmarks`
+
 .. |_Cell| replace:: :class:`._Cell`
 
 .. |_CharacterStyle| replace:: :class:`._CharacterStyle`
diff --git a/docx/bookmark.py b/docx/bookmark.py
@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+"""Objects related to bookmarks."""
+
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
+
+
+class Bookmarks(object):
+    """Sequence of |Bookmark| objects."""
+
+    def __init__(self, document_part):
+        self._document_part = document_part
diff --git a/docx/document.py b/docx/document.py
@@ -5,10 +5,12 @@
 from __future__ import absolute_import, division, print_function, unicode_literals
 
 from docx.blkcntnr import BlockItemContainer
+
+from docx.bookmark import Bookmarks
 from docx.enum.section import WD_SECTION
 from docx.enum.text import WD_BREAK
 from docx.section import Section, Sections
-from docx.shared import ElementProxy, Emu
+from docx.shared import ElementProxy, Emu, lazyproperty
 
 
 class Document(ElementProxy):
@@ -18,7 +20,7 @@ class Document(ElementProxy):
     a document.
     """
 
-    __slots__ = ('_part', '__body')
+    __slots__ = ("__body", "_bookmarks", "_part")
 
     def __init__(self, element, part):
         super(Document, self).__init__(element)
@@ -44,7 +46,7 @@ def add_page_break(self):
         paragraph.add_run().add_break(WD_BREAK.PAGE)
         return paragraph
 
-    def add_paragraph(self, text='', style=None):
+    def add_paragraph(self, text="", style=None):
         """
         Return a paragraph newly added to the end of the document, populated
         with *text* and having paragraph style *style*. *text* can contain
@@ -93,6 +95,16 @@ def add_table(self, rows, cols, style=None):
         table.style = style
         return table
 
+    @lazyproperty
+    def bookmarks(self):
+        """|Bookmarks| object providing access to |Bookmark| objects.
+
+        A bookmark may exist in the main document story, but also in headers,
+        footers, footnotes or endnotes. This collection contains all
+        bookmarks defined in any of these parts.
+        """
+        return Bookmarks(self._part)
+
     @property
     def core_properties(self):
         """
@@ -172,9 +184,7 @@ def _block_width(self):
         space between the margins of the last section of this document.
         """
         section = self.sections[-1]
-        return Emu(
-            section.page_width - section.left_margin - section.right_margin
-        )
+        return Emu(section.page_width - section.left_margin - section.right_margin)
 
     @property
     def _body(self):
@@ -191,6 +201,7 @@ class _Body(BlockItemContainer):
     Proxy for ``<w:body>`` element in this document, having primarily a
     container role.
     """
+
     def __init__(self, body_elm, parent):
         super(_Body, self).__init__(body_elm, parent)
         self._body = body_elm
diff --git a/features/doc-access-collections.feature b/features/doc-access-collections.feature
@@ -29,7 +29,6 @@ Feature: Access document collections
      Then document.tables is a list containing three tables
 
 
-  @wip
   Scenario: Document.bookmarks
     Given a Document object as document
      Then document.bookmarks is a Bookmarks object
diff --git a/tests/test_document.py b/tests/test_document.py
@@ -6,6 +6,7 @@
 
 import pytest
 
+from docx.bookmark import Bookmarks
 from docx.document import _Body, Document
 from docx.enum.section import WD_SECTION
 from docx.enum.text import WD_BREAK
@@ -93,6 +94,16 @@ def it_can_save_the_document_to_a_file(self, save_fixture):
         document.save(file_)
         document._part.save.assert_called_once_with(file_)
 
+    def it_provides_access_to_its_bookmarks(
+            self, document_part_, Bookmarks_, bookmarks_):
+        Bookmarks_.return_value = bookmarks_
+        document = Document(None, document_part_)
+
+        bookmarks = document.bookmarks
+
+        Bookmarks_.assert_called_once_with(document_part_)
+        assert bookmarks is bookmarks_
+
     def it_provides_access_to_its_core_properties(self, core_props_fixture):
         document, core_properties_ = core_props_fixture
         core_properties = document.core_properties
@@ -272,6 +283,10 @@ def tables_fixture(self, body_prop_, tables_):
     def add_paragraph_(self, request):
         return method_mock(request, Document, 'add_paragraph')
 
+    @pytest.fixture
+    def _block_width_prop_(self, request):
+        return property_mock(request, Document, '_block_width')
+
     @pytest.fixture
     def _Body_(self, request, body_):
         return class_mock(request, 'docx.document._Body', return_value=body_)
@@ -281,12 +296,16 @@ def body_(self, request):
         return instance_mock(request, _Body)
 
     @pytest.fixture
-    def _block_width_prop_(self, request):
-        return property_mock(request, Document, '_block_width')
+    def body_prop_(self, request, body_):
+        return property_mock(request, Document, '_body')
 
     @pytest.fixture
-    def body_prop_(self, request, body_):
-        return property_mock(request, Document, '_body', return_value=body_)
+    def Bookmarks_(self, request):
+        return class_mock(request, 'docx.document.Bookmarks')
+
+    @pytest.fixture
+    def bookmarks_(self, request):
+        return instance_mock(request, Bookmarks)
 
     @pytest.fixture
     def core_properties_(self, request):
