hdr: add BaseStoryPart.new_pic_inline()

This is essentially migrated "up" from DocumentPart, which now
subclasses BaseStoryPart.

Author: scanny

docx/parts/document.py

@@ -6,17 +6,16 @@
 
 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.hdrftr import FooterPart, HeaderPart
 from docx.parts.numbering import NumberingPart
 from docx.parts.settings import SettingsPart
+from docx.parts.story import BaseStoryPart
 from docx.parts.styles import StylesPart
 from docx.shape import InlineShapes
 from docx.shared import lazyproperty
 
 
-class DocumentPart(XmlPart):
+class DocumentPart(BaseStoryPart):
     """Main document part of a WordprocessingML (WML) package, aka a .docx file.
 
     Acts as broker to other parts such as image, core properties, and style parts. It
@@ -104,17 +103,6 @@ def inline_shapes(self):
         """
         return InlineShapes(self._element.body, self)
 
-    def new_pic_inline(self, image_descriptor, width, height):
-        """Return a newly-created `w:inline` element.
-
-        The element contains the image specified by *image_descriptor* and is scaled
-        based on the values of *width* and *height*.
-        """
-        rId, image = self.get_or_add_image(image_descriptor)
-        cx, cy = image.scaled_dimensions(width, height)
-        shape_id, filename = self.next_id, image.filename
-        return CT_Inline.new_pic_inline(shape_id, rId, filename, cx, cy)
-
     @property
     def next_id(self):
         """Next available positive integer id value in this document.

docx/parts/story.py

@@ -5,6 +5,7 @@
 from __future__ import absolute_import, division, print_function, unicode_literals
 
 from docx.opc.part import XmlPart
+from docx.oxml.shape import CT_Inline
 from docx.shared import lazyproperty
 
 
@@ -16,6 +17,16 @@ class BaseStoryPart(XmlPart):
     `.add_paragraph()`, `.add_table()` etc.
     """
 
+    def get_or_add_image(self, image_descriptor):
+        """Return (rId, image) pair for image identified by *image_descriptor*.
+
+        *rId* is the str key (often like "rId7") for the relationship between this story
+        part and the image part, reused if already present, newly created if not.
+        *image* is an |Image| instance providing access to the properties of the image,
+        such as dimensions and image type.
+        """
+        raise NotImplementedError
+
     def get_style(self, style_id, style_type):
         """Return the style in this document matching *style_id*.
 
@@ -33,6 +44,27 @@ def get_style_id(self, style_or_name, style_type):
         """
         return self._document_part.get_style_id(style_or_name, style_type)
 
+    def new_pic_inline(self, image_descriptor, width, height):
+        """Return a newly-created `w:inline` element.
+
+        The element contains the image specified by *image_descriptor* and is scaled
+        based on the values of *width* and *height*.
+        """
+        rId, image = self.get_or_add_image(image_descriptor)
+        cx, cy = image.scaled_dimensions(width, height)
+        shape_id, filename = self.next_id, image.filename
+        return CT_Inline.new_pic_inline(shape_id, rId, filename, cx, cy)
+
+    @property
+    def next_id(self):
+        """Next available positive integer id value in this story XML document.
+
+        The value is determined by incrementing the maximum existing id value. Gaps in
+        the existing id sequence are not filled. The id attribute value is unique in the
+        document, without regard to the element type it appears on.
+        """
+        raise NotImplementedError
+
     @lazyproperty
     def _document_part(self):
         """|DocumentPart| object for this package."""

tests/parts/test_document.py

@@ -23,7 +23,6 @@
 
 from ..oxml.parts.unitdata.document import a_body, a_document
 from ..oxml.unitdata.text import a_p
-from ..unitutil.file import snippet_text
 from ..unitutil.mock import class_mock, instance_mock, method_mock, property_mock
 
 
@@ -154,21 +153,6 @@ def it_knows_the_next_available_xml_id(self, next_id_fixture):
         document, expected_id = next_id_fixture
         assert document.next_id == expected_id
 
-    def it_can_create_a_new_pic_inline(self, image_, get_or_add_image_, next_id_prop_):
-        path, width, height, rId = 'foo/bar.png', 111, 222, 'rId42'
-        expected_xml = snippet_text('inline')
-        get_or_add_image_.return_value = rId, image_
-        image_.scaled_dimensions.return_value = 444, 888
-        image_.filename = 'bar.png'
-        next_id_prop_.return_value = 24
-        document_part = DocumentPart(None, None, None, None)
-
-        inline = document_part.new_pic_inline(path, width, height)
-
-        get_or_add_image_.assert_called_once_with(document_part, path)
-        image_.scaled_dimensions.assert_called_once_with(width, height)
-        assert inline.xml == expected_xml
-
     def it_can_get_a_style_by_id(self, styles_prop_, styles_, style_):
         styles_prop_.return_value = styles_
         styles_.get_by_id.return_value = style_
@@ -315,10 +299,6 @@ def FooterPart_(self, request):
     def footer_part_(self, request):
         return instance_mock(request, FooterPart)
 
-    @pytest.fixture
-    def get_or_add_image_(self, request):
-        return method_mock(request, DocumentPart, 'get_or_add_image')
-
     @pytest.fixture
     def HeaderPart_(self, request):
         return class_mock(request, 'docx.parts.document.HeaderPart')
@@ -339,10 +319,6 @@ def image_part_(self, request):
     def InlineShapes_(self, request):
         return class_mock(request, 'docx.parts.document.InlineShapes')
 
-    @pytest.fixture
-    def next_id_prop_(self, request):
-        return property_mock(request, DocumentPart, 'next_id')
-
     @pytest.fixture
     def NumberingPart_(self, request):
         return class_mock(request, 'docx.parts.document.NumberingPart')

tests/parts/test_story.py

@@ -7,12 +7,14 @@
 import pytest
 
 from docx.enum.style import WD_STYLE_TYPE
+from docx.image.image import Image
 from docx.package import Package
 from docx.parts.document import DocumentPart
 from docx.parts.story import BaseStoryPart
 from docx.styles.style import BaseStyle
 
-from ..unitutil.mock import instance_mock, property_mock
+from ..unitutil.file import snippet_text
+from ..unitutil.mock import instance_mock, method_mock, property_mock
 
 
 class DescribeBaseStoryPart(object):
@@ -44,6 +46,20 @@ def it_can_get_a_style_id_by_style_or_name_and_type(
         document_part_.get_style_id.assert_called_once_with(style_, style_type)
         assert style_id == "BodyText"
 
+    def it_can_create_a_new_pic_inline(self, get_or_add_image_, image_, next_id_prop_):
+        get_or_add_image_.return_value = "rId42", image_
+        image_.scaled_dimensions.return_value = 444, 888
+        image_.filename = "bar.png"
+        next_id_prop_.return_value = 24
+        expected_xml = snippet_text("inline")
+        story_part = BaseStoryPart(None, None, None, None)
+
+        inline = story_part.new_pic_inline("foo/bar.png", width=100, height=200)
+
+        get_or_add_image_.assert_called_once_with(story_part, "foo/bar.png")
+        image_.scaled_dimensions.assert_called_once_with(100, 200)
+        assert inline.xml == expected_xml
+
     def it_knows_the_main_document_part_to_help(self, package_, document_part_):
         package_.main_document_part = document_part_
         story_part = BaseStoryPart(None, None, None, package_)
@@ -62,6 +78,18 @@ def document_part_(self, request):
     def _document_part_prop_(self, request):
         return property_mock(request, BaseStoryPart, "_document_part")
 
+    @pytest.fixture
+    def get_or_add_image_(self, request):
+        return method_mock(request, BaseStoryPart, "get_or_add_image")
+
+    @pytest.fixture
+    def image_(self, request):
+        return instance_mock(request, Image)
+
+    @pytest.fixture
+    def next_id_prop_(self, request):
+        return property_mock(request, BaseStoryPart, "next_id")
+
     @pytest.fixture
     def package_(self, request):
         return instance_mock(request, Package)

tests/text/test_run.py

@@ -1,12 +1,8 @@
 # encoding: utf-8
 
-"""
-Test suite for the docx.text.run module
-"""
+"""Test suite for the docx.text.run module"""
 
-from __future__ import (
-    absolute_import, division, print_function, unicode_literals
-)
+from __future__ import absolute_import, division, print_function, unicode_literals
 
 from docx.enum.style import WD_STYLE_TYPE
 from docx.enum.text import WD_BREAK, WD_UNDERLINE