spike: implement 'Bookmarks is a sequence'

Author: scanny

docx/__init__.py

@@ -12,6 +12,10 @@
 from docx.opc.parts.coreprops import CorePropertiesPart
 
 from docx.parts.document import DocumentPart
+from docx.parts.endnotes import EndnotesPart
+from docx.parts.footer import FooterPart
+from docx.parts.footnotes import FootnotesPart
+from docx.parts.header import HeaderPart
 from docx.parts.image import ImagePart
 from docx.parts.numbering import NumberingPart
 from docx.parts.settings import SettingsPart
@@ -27,11 +31,16 @@ def part_class_selector(content_type, reltype):
 PartFactory.part_class_selector = part_class_selector
 PartFactory.part_type_for[CT.OPC_CORE_PROPERTIES] = CorePropertiesPart
 PartFactory.part_type_for[CT.WML_DOCUMENT_MAIN] = DocumentPart
+PartFactory.part_type_for[CT.WML_ENDNOTES] = EndnotesPart
+PartFactory.part_type_for[CT.WML_FOOTER] = FooterPart
+PartFactory.part_type_for[CT.WML_FOOTNOTES] = FootnotesPart
+PartFactory.part_type_for[CT.WML_HEADER] = HeaderPart
 PartFactory.part_type_for[CT.WML_NUMBERING] = NumberingPart
 PartFactory.part_type_for[CT.WML_SETTINGS] = SettingsPart
 PartFactory.part_type_for[CT.WML_STYLES] = StylesPart
 
 del (
-    CT, CorePropertiesPart, DocumentPart, NumberingPart, PartFactory,
-    StylesPart, part_class_selector
+    CT, CorePropertiesPart, DocumentPart, EndnotesPart, FooterPart,
+    FootnotesPart, HeaderPart, NumberingPart, PartFactory, StylesPart,
+    part_class_selector
 )

docx/bookmark.py

@@ -6,17 +6,28 @@
     absolute_import, division, print_function, unicode_literals
 )
 
+from collections import Sequence
 from itertools import chain
 
+from docx.oxml.ns import qn
 from docx.shared import lazyproperty
 
 
-class Bookmarks(object):
+class Bookmarks(Sequence):
     """Sequence of |Bookmark| objects."""
 
     def __init__(self, document_part):
         self._document_part = document_part
 
+    def __getitem__(self, idx):
+        bookmark_pair = self._finder.bookmark_pairs[idx]
+        return _Bookmark(bookmark_pair)
+
+    def __iter__(self):
+        # ---not strictly required, but improves performance over default
+        # ---implementation that makes repeated calls to __getitem__()
+        return (_Bookmark(pair) for pair in self._finder.bookmark_pairs)
+
     def __len__(self):
         return len(self._finder.bookmark_pairs)
 
@@ -26,6 +37,13 @@ def _finder(self):
         return _DocumentBookmarkFinder(self._document_part)
 
 
+class _Bookmark(object):
+    """Proxy for a (w:bookmarkStart, w:bookmarkEnd) element pair."""
+
+    def __init__(self, bookmark_pair):
+        self._bookmarkStart, self._bookmarkEnd = bookmark_pair
+
+
 class _DocumentBookmarkFinder(object):
     """Provides access to bookmark oxml elements in an overall document."""
 
@@ -58,7 +76,58 @@ def bookmark_pairs(self):
 class _PartBookmarkFinder(object):
     """Provides access to bookmark oxml elements in a story part."""
 
+    def __init__(self, part):
+        self._part = part
+
     @classmethod
     def iter_start_end_pairs(cls, part):
         """Generate each (bookmarkStart, bookmarkEnd) in *part*."""
-        raise NotImplementedError
+        return cls(part)._iter_start_end_pairs()
+
+    def _iter_start_end_pairs(self):
+        """Generate each (bookmarkStart, bookmarkEnd) in this part."""
+        for idx, bookmarkStart in self._iter_starts():
+            # ---skip open pairs---
+            bookmarkEnd = self._matching_end(bookmarkStart, idx)
+            if bookmarkEnd is None:
+                continue
+            # ---skip duplicate names---
+            if not self._add_to_names_so_far(bookmarkStart.name):
+                continue
+            yield (bookmarkStart, bookmarkEnd)
+
+    def _iter_starts(self):
+        """Generate (idx, bookmarkStart) elements in story.
+
+        The *idx* value indicates the location of the bookmarkStart element
+        among all the bookmarkStart and bookmarkEnd elements in the story.
+        """
+        for idx, element in enumerate(self._all_starts_and_ends):
+            if element.tag == qn('w:bookmarkStart'):
+                yield idx, element
+
+    @lazyproperty
+    def _all_starts_and_ends(self):
+        return self._part.element.xpath('//w:bookmarkStart|//w:bookmarkEnd')
+
+    def _matching_end(self, bookmarkStart, idx):
+        for element in self._all_starts_and_ends[idx + 1:]:
+            # ---skip bookmark starts---
+            if element.tag == qn('w:bookmarkStart'):
+                continue
+            bookmarkEnd = element
+            if bookmarkEnd.id == bookmarkStart.id:
+                return bookmarkEnd
+        return None
+
+    def _add_to_names_so_far(self, name):
+        """Return True if name was added, False if name already present."""
+        names_so_far = self._names_so_far
+        if name in names_so_far:
+            return False
+        names_so_far.add(name)
+        return True
+
+    @lazyproperty
+    def _names_so_far(self):
+        return set()

docx/opc/part.py

@@ -74,6 +74,17 @@ def drop_rel(self, rId):
         if self._rel_ref_count(rId) < 2:
             del self.rels[rId]
 
+    def iter_parts_related_by(self, reltypes):
+        """Generate each part related to this by one of *reltypes*.
+
+        *reltypes* must be a container; `set` is convenient but list or other
+        sequence types work fine.
+        """
+        return (
+            rel.target_part for rel in self.rels.values()
+            if rel.reltype in reltypes
+        )
+
     @classmethod
     def load(cls, partname, content_type, blob, package):
         return cls(partname, content_type, blob, package)

docx/opc/rel.py

@@ -13,7 +13,7 @@
 
 class Relationships(dict):
     """
-    Collection object for |_Relationship| instances, having list semantics.
+    Collection object for |_Relationship| instances, having dict semantics.
     """
     def __init__(self, baseURI):
         super(Relationships, self).__init__()

docx/oxml/__init__.py

@@ -64,17 +64,27 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 # custom element class mappings
 # ===========================================================================
 
-from .shared import CT_DecimalNumber, CT_OnOff, CT_String
+from docx.oxml.shared import CT_DecimalNumber, CT_OnOff, CT_String
 
 
-from .coreprops import CT_CoreProperties
+from docx.oxml.bookmark import CT_Bookmark, CT_MarkupRange
+register_element_cls('w:bookmarkEnd',   CT_MarkupRange)
+register_element_cls('w:bookmarkStart', CT_Bookmark)
+
+from docx.oxml.coreprops import CT_CoreProperties
 register_element_cls('cp:coreProperties', CT_CoreProperties)
 
-from .document import CT_Body, CT_Document
+from docx.oxml.document import CT_Body, CT_Document
 register_element_cls('w:body',     CT_Body)
 register_element_cls('w:document', CT_Document)
 
-from .numbering import (
+from docx.oxml.endnotes import CT_Endnotes
+register_element_cls('w:endnotes', CT_Endnotes)
+
+from docx.oxml.footnotes import CT_Footnotes
+register_element_cls('w:footnotes', CT_Footnotes)
+
+from docx.oxml.numbering import (
     CT_Num, CT_Numbering, CT_NumLvl, CT_NumPr
 )
 register_element_cls('w:abstractNumId', CT_DecimalNumber)
@@ -86,13 +96,13 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 register_element_cls('w:numbering',     CT_Numbering)
 register_element_cls('w:startOverride', CT_DecimalNumber)
 
-from .section import CT_PageMar, CT_PageSz, CT_SectPr, CT_SectType
+from docx.oxml.section import CT_PageMar, CT_PageSz, CT_SectPr, CT_SectType
 register_element_cls('w:pgMar',  CT_PageMar)
 register_element_cls('w:pgSz',   CT_PageSz)
 register_element_cls('w:sectPr', CT_SectPr)
 register_element_cls('w:type',   CT_SectType)
 
-from .shape import (
+from docx.oxml.shape import (
     CT_Blip, CT_BlipFillProperties, CT_GraphicalObject,
     CT_GraphicalObjectData, CT_Inline, CT_NonVisualDrawingProps, CT_Picture,
     CT_PictureNonVisual, CT_Point2D, CT_PositiveSize2D, CT_ShapeProperties,
@@ -113,7 +123,9 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 register_element_cls('wp:extent',     CT_PositiveSize2D)
 register_element_cls('wp:inline',     CT_Inline)
 
-from .styles import CT_LatentStyles, CT_LsdException, CT_Style, CT_Styles
+from docx.oxml.styles import (
+    CT_LatentStyles, CT_LsdException, CT_Style, CT_Styles
+)
 register_element_cls('w:basedOn',        CT_String)
 register_element_cls('w:latentStyles',   CT_LatentStyles)
 register_element_cls('w:locked',         CT_OnOff)
@@ -127,7 +139,7 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 register_element_cls('w:uiPriority',     CT_DecimalNumber)
 register_element_cls('w:unhideWhenUsed', CT_OnOff)
 
-from .table import (
+from docx.oxml.table import (
     CT_Height, CT_Row, CT_Tbl, CT_TblGrid, CT_TblGridCol, CT_TblLayoutType,
     CT_TblPr, CT_TblWidth, CT_Tc, CT_TcPr, CT_TrPr, CT_VerticalJc, CT_VMerge
 )
@@ -148,7 +160,7 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 register_element_cls('w:vAlign',     CT_VerticalJc)
 register_element_cls('w:vMerge',     CT_VMerge)
 
-from .text.font import (
+from docx.oxml.text.font import (
     CT_Color, CT_Fonts, CT_Highlight, CT_HpsMeasure, CT_RPr, CT_Underline,
     CT_VerticalAlignRun
 )
@@ -181,10 +193,10 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 register_element_cls('w:vertAlign',  CT_VerticalAlignRun)
 register_element_cls('w:webHidden',  CT_OnOff)
 
-from .text.paragraph import CT_P
+from docx.oxml.text.paragraph import CT_P
 register_element_cls('w:p', CT_P)
 
-from .text.parfmt import (
+from docx.oxml.text.parfmt import (
     CT_Ind, CT_Jc, CT_PPr, CT_Spacing, CT_TabStop, CT_TabStops
 )
 register_element_cls('w:ind',             CT_Ind)
@@ -199,7 +211,11 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 register_element_cls('w:tabs',            CT_TabStops)
 register_element_cls('w:widowControl',    CT_OnOff)
 
-from .text.run import CT_Br, CT_R, CT_Text
+from docx.oxml.text.run import CT_Br, CT_R, CT_Text
 register_element_cls('w:br', CT_Br)
 register_element_cls('w:r',  CT_R)
 register_element_cls('w:t',  CT_Text)
+
+from docx.oxml.header import CT_HdrFtr
+register_element_cls('w:hdr', CT_HdrFtr)
+register_element_cls('w:ftr', CT_HdrFtr)

docx/oxml/bookmark.py

@@ -0,0 +1,21 @@
+# encoding: utf-8
+
+"""Custom element classes related to bookmarks."""
+
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
+
+from docx.oxml.simpletypes import ST_DecimalNumber, ST_String
+from docx.oxml.xmlchemy import BaseOxmlElement, RequiredAttribute
+
+
+class CT_Bookmark(BaseOxmlElement):
+    """w:bookmarkStart element"""
+    id = RequiredAttribute('w:id', ST_DecimalNumber)
+    name = RequiredAttribute('w:name', ST_String)
+
+
+class CT_MarkupRange(BaseOxmlElement):
+    """w:bookmarkEnd element"""
+    id = RequiredAttribute('w:id', ST_DecimalNumber)

docx/oxml/endnotes.py

@@ -0,0 +1,13 @@
+# encoding: utf-8
+
+"""Custom element classes related to end-notes."""
+
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
+
+from docx.oxml.xmlchemy import BaseOxmlElement
+
+
+class CT_Endnotes(BaseOxmlElement):
+    """w:endnotes element"""

docx/oxml/footnotes.py

@@ -0,0 +1,13 @@
+# encoding: utf-8
+
+"""Custom element classes related to footnotes."""
+
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
+
+from docx.oxml.xmlchemy import BaseOxmlElement
+
+
+class CT_Footnotes(BaseOxmlElement):
+    """w:footnotes element"""

docx/oxml/header.py

@@ -0,0 +1,9 @@
+# encoding: utf-8
+
+"""Custom element classes related to headers and footers."""
+
+from .xmlchemy import BaseOxmlElement
+
+
+class CT_HdrFtr(BaseOxmlElement):
+    """Used for w:hdr and w:ftr."""

docx/parts/document.py

@@ -1,33 +1,34 @@
 # encoding: utf-8
 
-"""
-|DocumentPart| and closely related objects
-"""
+"""|DocumentPart| and closely related objects."""
 
 from __future__ import (
     absolute_import, division, print_function, unicode_literals
 )
 
-from ..document import Document
-from .numbering import NumberingPart
-from ..opc.constants import RELATIONSHIP_TYPE as RT
-from ..opc.part import XmlPart
-from ..oxml.shape import CT_Inline
-from ..shape import InlineShapes
-from ..shared import lazyproperty
-from .settings import SettingsPart
-from .styles import StylesPart
+from itertools import chain
+
+from docx.document import Document
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
+from docx.opc.part import XmlPart
+from docx.oxml.shape import CT_Inline
+from docx.parts.numbering import NumberingPart
+from docx.parts.settings import SettingsPart
+from docx.parts.styles import StylesPart
+from docx.shape import InlineShapes
+from docx.shared import lazyproperty
 
 
 class DocumentPart(XmlPart):
-    """
-    Main document part of a WordprocessingML (WML) package, aka a .docx file.
+    """Main document part of a WordprocessingML (WML) package.
+
     Acts as broker to other parts such as image, core properties, and style
     parts. It also acts as a convenient delegate when a mid-document object
     needs a service involving a remote ancestor. The `Parented.part` property
     inherited by many content objects provides access to this part object for
     that purpose.
     """
+
     @property
     def core_properties(self):
         """
@@ -90,7 +91,12 @@ def iter_story_parts(self):
         Story parts include this main document part, headers, footers,
         footnotes, and endnotes.
         """
-        raise NotImplementedError
+        return chain(
+            (self,),
+            self.iter_parts_related_by(
+                {RT.HEADER, RT.FOOTER, RT.FOOTNOTES, RT.ENDNOTES}
+            )
+        )
 
     def new_pic_inline(self, image_descriptor, width, height):
         """