hdr: add BaseStoryPart.get_or_add_image()

Also extract Package.get_or_add_image_part() to avoid BaseStoryPart and
others having to know about ImageParts.

Author: scanny

docx/package.py

@@ -22,6 +22,14 @@ def after_unmarshal(self):
         """
         self._gather_image_parts()
 
+    def get_or_add_image_part(self, image_descriptor):
+        """Return |ImagePart| containing image specified by *image_descriptor*.
+
+        The image-part is newly created if a matching one is not already present in the
+        collection.
+        """
+        return self.image_parts.get_or_add_image_part(image_descriptor)
+
     @lazyproperty
     def image_parts(self):
         """|ImageParts| collection object for this package."""

docx/parts/document.py

@@ -59,20 +59,6 @@ def footer_part(self, rId):
         """Return |FooterPart| related by *rId*."""
         return self.related_parts[rId]
 
-    def get_or_add_image(self, image_descriptor):
-        """
-        Return an (rId, image) 2-tuple for the image identified by
-        *image_descriptor*. *image* is an |Image| instance providing access
-        to the properties of the image, such as dimensions and image type.
-        *rId* is the key for the relationship between this document part and
-        the image part, reused if already present, newly created if not.
-        """
-        image_part = self._package.image_parts.get_or_add_image_part(
-            image_descriptor
-        )
-        rId = self.relate_to(image_part, RT.IMAGE)
-        return rId, image_part.image
-
     def get_style(self, style_id, style_type):
         """
         Return the style in this document matching *style_id*. Returns the

docx/parts/story.py

@@ -4,6 +4,7 @@
 
 from __future__ import absolute_import, division, print_function, unicode_literals
 
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
 from docx.opc.part import XmlPart
 from docx.oxml.shape import CT_Inline
 from docx.shared import lazyproperty
@@ -25,7 +26,9 @@ def get_or_add_image(self, image_descriptor):
         *image* is an |Image| instance providing access to the properties of the image,
         such as dimensions and image type.
         """
-        raise NotImplementedError
+        image_part = self._package.get_or_add_image_part(image_descriptor)
+        rId = self.relate_to(image_part, RT.IMAGE)
+        return rId, image_part.image
 
     def get_style(self, style_id, style_type):
         """Return the style in this document matching *style_id*.

tests/parts/test_document.py

@@ -7,13 +7,11 @@
 import pytest
 
 from docx.enum.style import WD_STYLE_TYPE
-from docx.image.image import Image
 from docx.opc.constants import RELATIONSHIP_TYPE as RT
 from docx.opc.coreprops import CoreProperties
 from docx.package import Package
 from docx.parts.document import DocumentPart
 from docx.parts.hdrftr import FooterPart, HeaderPart
-from docx.parts.image import ImagePart
 from docx.parts.numbering import NumberingPart
 from docx.parts.settings import SettingsPart
 from docx.parts.styles import StylesPart
@@ -88,21 +86,6 @@ def it_can_save_the_package_to_a_file(self, save_fixture):
         document.save(file_)
         document._package.save.assert_called_once_with(file_)
 
-    def it_can_get_or_add_an_image(self, package_, image_part_, image_, relate_to_):
-        path = 'foobar.png'
-        package_.image_parts.get_or_add_image_part.return_value = image_part_
-        relate_to_.return_value = "rId42"
-        image_part_.image = image_
-        document_part = DocumentPart(None, None, None, package_)
-
-        rId, image = document_part.get_or_add_image(path)
-
-        image_parts = document_part._package.image_parts
-        image_parts.get_or_add_image_part.assert_called_once_with(path)
-        relate_to_.assert_called_once_with(document_part, image_part_, RT.IMAGE)
-        assert rId == "rId42"
-        assert image is image_
-
     def it_provides_access_to_the_document_settings(self, settings_fixture):
         document_part, settings_ = settings_fixture
         settings = document_part.settings
@@ -307,14 +290,6 @@ def HeaderPart_(self, request):
     def header_part_(self, request):
         return instance_mock(request, HeaderPart)
 
-    @pytest.fixture
-    def image_(self, request):
-        return instance_mock(request, Image)
-
-    @pytest.fixture
-    def image_part_(self, request):
-        return instance_mock(request, ImagePart)
-
     @pytest.fixture
     def InlineShapes_(self, request):
         return class_mock(request, 'docx.parts.document.InlineShapes')

tests/parts/test_story.py

@@ -8,8 +8,10 @@
 
 from docx.enum.style import WD_STYLE_TYPE
 from docx.image.image import Image
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
 from docx.package import Package
 from docx.parts.document import DocumentPart
+from docx.parts.image import ImagePart
 from docx.parts.story import BaseStoryPart
 from docx.styles.style import BaseStyle
 
@@ -19,6 +21,19 @@
 
 class DescribeBaseStoryPart(object):
 
+    def it_can_get_or_add_an_image(self, package_, image_part_, image_, relate_to_):
+        package_.get_or_add_image_part.return_value = image_part_
+        relate_to_.return_value = "rId42"
+        image_part_.image = image_
+        story_part = BaseStoryPart(None, None, None, package_)
+
+        rId, image = story_part.get_or_add_image("image.png")
+
+        package_.get_or_add_image_part.assert_called_once_with("image.png")
+        relate_to_.assert_called_once_with(story_part, image_part_, RT.IMAGE)
+        assert rId == "rId42"
+        assert image is image_
+
     def it_can_get_a_style_by_id_and_type(
         self, _document_part_prop_, document_part_, style_
     ):
@@ -86,6 +101,10 @@ def get_or_add_image_(self, request):
     def image_(self, request):
         return instance_mock(request, Image)
 
+    @pytest.fixture
+    def image_part_(self, request):
+        return instance_mock(request, ImagePart)
+
     @pytest.fixture
     def next_id_prop_(self, request):
         return property_mock(request, BaseStoryPart, "next_id")
@@ -94,6 +113,10 @@ def next_id_prop_(self, request):
     def package_(self, request):
         return instance_mock(request, Package)
 
+    @pytest.fixture
+    def relate_to_(self, request):
+        return method_mock(request, BaseStoryPart, "relate_to")
+
     @pytest.fixture
     def style_(self, request):
         return instance_mock(request, BaseStyle)

tests/test_package.py

@@ -12,18 +12,44 @@
 from docx.parts.image import ImagePart
 
 from .unitutil.file import docx_path
-from .unitutil.mock import class_mock, instance_mock, method_mock
+from .unitutil.mock import class_mock, instance_mock, method_mock, property_mock
 
 
 class DescribePackage(object):
 
+    def it_can_get_or_add_an_image_part_containing_a_specified_image(
+        self, image_parts_prop_, image_parts_, image_part_
+    ):
+        image_parts_prop_.return_value = image_parts_
+        image_parts_.get_or_add_image_part.return_value = image_part_
+        package = Package()
+
+        image_part = package.get_or_add_image_part("image.png")
+
+        image_parts_.get_or_add_image_part.assert_called_once_with("image.png")
+        assert image_part is image_part_
+
     def it_gathers_package_image_parts_after_unmarshalling(self):
         package = Package.open(docx_path('having-images'))
         image_parts = package.image_parts
         assert len(image_parts) == 3
         for image_part in image_parts:
             assert isinstance(image_part, ImagePart)
 
+    # fixture components ---------------------------------------------
+
+    @pytest.fixture
+    def image_part_(self, request):
+        return instance_mock(request, ImagePart)
+
+    @pytest.fixture
+    def image_parts_(self, request):
+        return instance_mock(request, ImageParts)
+
+    @pytest.fixture
+    def image_parts_prop_(self, request):
+        return property_mock(request, Package, "image_parts")
+
 
 class DescribeImageParts(object):