blkcntnr: add BlockItemContainer.start_bookmark()

scanny · scanny · commit aaf7987f7df1 · 2019-09-02T16:10:51.000-07:00
diff --git a/docx/blkcntnr.py b/docx/blkcntnr.py
@@ -8,8 +8,9 @@
 
 from __future__ import absolute_import, division, print_function, unicode_literals
 
+from docx.bookmark import _Bookmark
 from docx.oxml.table import CT_Tbl
-from docx.shared import Parented
+from docx.shared import lazyproperty, Parented
 from docx.text.paragraph import Paragraph
 
 
@@ -60,11 +61,18 @@ def paragraphs(self):
         return [Paragraph(p, self) for p in self._element.p_lst]
 
     def start_bookmark(self, name):
-        """Return _Bookmark object identified by `name`.
+        """Return newly-added |_Bookmark| object identified by `name`.
 
-        The returned bookmark is anchored at the end of this block-item container.
+        The returned bookmark is anchored at the end of this block-item container, for
+        example, after the last paragraph in the document when the document body is the
+        block-item container.
         """
-        raise NotImplementedError
+        if name in self._bookmarks:
+            raise KeyError("Document already contains bookmark with name %s" % name)
+
+        return _Bookmark(
+            (self._element.add_bookmarkStart(name, self._bookmarks.next_id), None)
+        )
 
     @property
     def tables(self):
@@ -82,3 +90,8 @@ def _add_paragraph(self):
         container.
         """
         return Paragraph(self._element.add_p(), self)
+
+    @lazyproperty
+    def _bookmarks(self):
+        """Global |Bookmarks| object for overall document."""
+        raise NotImplementedError
diff --git a/docx/bookmark.py b/docx/bookmark.py
@@ -21,6 +21,10 @@ class Bookmarks(Sequence):
     def __init__(self, document_part):
         self._document_part = document_part
 
+    def __contains__(self, name):
+        """Supports `in` operator to test for presence of bookmark by `name`."""
+        raise NotImplementedError
+
     def __getitem__(self, idx):
         """Supports indexed and sliced access."""
         bookmark_pairs = self._finder.bookmark_pairs
@@ -47,6 +51,11 @@ def get(self, name):
                 return bookmark
         raise KeyError("Requested bookmark not found.")
 
+    @property
+    def next_id(self):
+        """Return the next available int bookmark-id, unique in document-wide scope."""
+        raise NotImplementedError
+
 
 class _Bookmark(object):
     """Proxy for a (w:bookmarkStart, w:bookmarkEnd) element pair."""
diff --git a/docx/oxml/document.py b/docx/oxml/document.py
@@ -12,25 +12,37 @@ class CT_Document(BaseOxmlElement):
     """
     ``<w:document>`` element, the root element of a document.xml file.
     """
-    body = ZeroOrOne('w:body')
+
+    body = ZeroOrOne("w:body")
 
     @property
     def sectPr_lst(self):
         """
         Return a list containing a reference to each ``<w:sectPr>`` element
         in the document, in the order encountered.
         """
-        return self.xpath('.//w:sectPr')
+        return self.xpath(".//w:sectPr")
 
 
 class CT_Body(BaseOxmlElement):
-    """
-    ``<w:body>``, the container element for the main document story in
-    ``document.xml``.
-    """
-    p = ZeroOrMore('w:p', successors=('w:sectPr',))
-    tbl = ZeroOrMore('w:tbl', successors=('w:sectPr',))
-    sectPr = ZeroOrOne('w:sectPr', successors=())
+    """`w:body`, the container element for the main document story in `document.xml`"""
+
+    p = ZeroOrMore("w:p", successors=("w:sectPr",))
+    tbl = ZeroOrMore("w:tbl", successors=("w:sectPr",))
+    bookmarkStart = ZeroOrMore("w:bookmarkStart", successors=("w:sectPr",))
+    sectPr = ZeroOrOne("w:sectPr", successors=())
+
+    def add_bookmarkStart(self, name, bookmark_id):
+        """Return `w:bookmarkStart` element added at end of document.
+
+        The newly added `w:bookmarkStart` element is identified by both `name` and
+        `bookmark_id`. It is the caller's responsibility to determine that both `name`
+        and `bookmark_id` are unique, document-wide.
+        """
+        bookmarkStart = self._add_bookmarkStart()
+        bookmarkStart.name = name
+        bookmarkStart.id = bookmark_id
+        return bookmarkStart
 
     def add_section_break(self):
         """Return `w:sectPr` element for new section added at end of document.
diff --git a/docx/oxml/section.py b/docx/oxml/section.py
@@ -22,6 +22,19 @@ class CT_HdrFtr(BaseOxmlElement):
 
     p = ZeroOrMore("w:p", successors=())
     tbl = ZeroOrMore("w:tbl", successors=())
+    bookmarkStart = ZeroOrMore("w:bookmarkStart", successors=())
+
+    def add_bookmarkStart(self, name, bookmark_id):
+        """Return `w:bookmarkStart` element added at the end of this header or footer.
+
+        The newly added `w:bookmarkStart` element is identified by both `name` and
+        `bookmark_id`. It is the caller's responsibility to determine that both `name`
+        and `bookmark_id` are unique, document-wide.
+        """
+        bookmarkStart = self._add_bookmarkStart()
+        bookmarkStart.name = name
+        bookmarkStart.id = bookmark_id
+        return bookmarkStart
 
 
 class CT_HdrFtrRef(BaseOxmlElement):
diff --git a/docx/oxml/table.py b/docx/oxml/table.py
diff --git a/tests/test_blkcntnr.py b/tests/test_blkcntnr.py
