img: add ImageParts.get_or_add_image_part()

Steve Canny · Steve Canny · commit 5a4f534efaab · 2013-12-28T01:40:32.000-08:00
diff --git a/docx/package.py b/docx/package.py
@@ -8,6 +8,7 @@
 
 from docx.opc.constants import RELATIONSHIP_TYPE as RT
 from docx.opc.package import OpcPackage
+from docx.parts.image import Image
 from docx.shared import lazyproperty
 
 
@@ -45,8 +46,8 @@ def _gather_image_parts(self):
 
 class ImageParts(object):
     """
-    Collection of |ImagePart| instances containing all the image parts in the
-    package.
+    Collection of |ImagePart| instances corresponding to each image part in
+    the package.
     """
     def __init__(self):
         super(ImageParts, self).__init__()
@@ -67,3 +68,25 @@ def get_or_add_image_part(self, image_descriptor):
         *image_descriptor*, newly created if a matching one is not present in
         the collection.
         """
+        image = Image.load(image_descriptor)
+        matching_image_part = self._get_by_sha1(image.sha1)
+        if matching_image_part is not None:
+            return matching_image_part
+        return self._add_image_part(image)
+
+    def _add_image_part(self, image):
+        """
+        Return the image part in this collection having a SHA1 hash matching
+        *sha1*, or |None| if not found.
+        """
+        raise NotImplementedError
+
+    def _get_by_sha1(self, sha1):
+        """
+        Return the image part in this collection having a SHA1 hash matching
+        *sha1*, or |None| if not found.
+        """
+        for image_part in self._image_parts:
+            if image_part.sha1 == sha1:
+                return image_part
+        return None
diff --git a/docx/parts/image.py b/docx/parts/image.py
@@ -9,6 +9,25 @@
 from docx.opc.package import Part
 
 
+class Image(object):
+    """
+    A helper object that knows how to analyze an image file.
+    """
+    @classmethod
+    def load(self, image_descriptor):
+        """
+        Return a new |Image| instance loaded from the image file identified
+        by *image_descriptor*, a path or file-like object.
+        """
+
+    @property
+    def sha1(self):
+        """
+        SHA1 hash digest of the image blob
+        """
+        raise NotImplementedError
+
+
 class ImagePart(Part):
     """
     An image part. Corresponds to the target part of a relationship with type
@@ -35,6 +54,13 @@ def height(self):
         """
         raise NotImplementedError
 
+    @property
+    def sha1(self):
+        """
+        SHA1 hash digest of the blob of this image part.
+        """
+        raise NotImplementedError
+
     @property
     def width(self):
         """
diff --git a/tests/test_package.py b/tests/test_package.py
@@ -6,13 +6,84 @@
 
 from __future__ import absolute_import, print_function, unicode_literals
 
-from docx.package import Package
+import pytest
 
-from .unitutil import docx_path
+from docx.package import ImageParts, Package
+from docx.parts.image import Image, ImagePart
+
+from .unitutil import class_mock, docx_path, instance_mock, method_mock
 
 
 class DescribePackage(object):
 
     def it_gathers_package_image_parts_after_unmarshalling(self):
         package = Package.open(docx_path('having-images'))
         assert len(package.image_parts) == 3
+
+
+class DescribeImageParts(object):
+
+    def it_can_get_a_matching_image_part(self, get_image_part_fixture):
+        image_parts, image_descriptor, image_part_ = get_image_part_fixture
+        image_part = image_parts.get_or_add_image_part(image_descriptor)
+        assert image_part is image_part_
+
+    def it_can_add_a_new_image_part(self, add_image_part_fixture):
+        image_parts, image_descriptor, image_, image_part_ = (
+            add_image_part_fixture
+        )
+        image_part = image_parts.get_or_add_image_part(image_descriptor)
+        image_parts._add_image_part.assert_called_once_with(image_)
+        assert image_part is image_part_
+
+    # fixtures -------------------------------------------------------
+
+    @pytest.fixture
+    def _add_image_part_(self, request, new_image_part_):
+        return method_mock(
+            request, ImageParts, '_add_image_part',
+            return_value=new_image_part_
+        )
+
+    @pytest.fixture
+    def add_image_part_fixture(
+            self, Image_, _add_image_part_, image_descriptor_, image_,
+            new_image_part_,):
+        image_parts = ImageParts()
+        return image_parts, image_descriptor_, image_, new_image_part_
+
+    @pytest.fixture
+    def get_image_part_fixture(self, Image_, image_part_, image_descriptor_):
+        image_parts = ImageParts()
+        image_parts.append(image_part_)
+        return image_parts, image_descriptor_, image_part_
+
+    @pytest.fixture
+    def Image_(self, request, image_):
+        Image_ = class_mock(request, 'docx.package.Image')
+        Image_.load.return_value = image_
+        return Image_
+
+    @pytest.fixture
+    def image_(self, request, sha1):
+        image_ = instance_mock(request, Image)
+        image_.sha1 = sha1
+        return image_
+
+    @pytest.fixture
+    def image_descriptor_(self, request):
+        return instance_mock(request, str)
+
+    @pytest.fixture
+    def image_part_(self, request, sha1):
+        image_part_ = instance_mock(request, ImagePart)
+        image_part_.sha1 = sha1
+        return image_part_
+
+    @pytest.fixture
+    def new_image_part_(self, request):
+        return instance_mock(request, ImagePart)
+
+    @pytest.fixture
+    def sha1(self):
+        return 'F008AH'
