shp: add InlineShapes.add_picture()

Steve Canny · Steve Canny · commit 10e93e2882fa · 2013-12-26T21:03:01.000-08:00
diff --git a/docx/parts.py b/docx/parts.py
@@ -23,6 +23,16 @@ def __init__(self, partname, content_type, document_elm, package):
         )
         self._element = document_elm
 
+    def add_image(self, image_descriptor):
+        """
+        Return an ``(image_part, rId)`` 2-tuple for the image identified by
+        *image_descriptor*. *image_part* is an |Image| instance corresponding
+        to the image, newly created if not already present in document. *rId*
+        is the key for the relationship between this document part and the
+        image part, reused if already present, newly created if not.
+        """
+        raise NotImplementedError
+
     @property
     def blob(self):
         return serialize_part_xml(self._element)
@@ -48,6 +58,15 @@ def load(partname, content_type, blob, package):
         document = _Document(partname, content_type, document_elm, package)
         return document
 
+    @property
+    def next_id(self):
+        """
+        The next available positive integer id value in this document. Gaps
+        in id sequence are filled. The id attribute value is unique in the
+        document, without regard to the element type it appears on.
+        """
+        raise NotImplementedError
+
 
 class _Body(object):
     """
@@ -100,6 +119,13 @@ def tables(self):
         return [Table(tbl) for tbl in self._body.tbl_lst]
 
 
+class Image(Part):
+    """
+    An image part. Corresponds to the target part of a relationship with type
+    RELATIONSHIP_TYPE.IMAGE.
+    """
+
+
 class InlineShape(object):
     """
     Proxy for an ``<wp:inline>`` element, representing the container for an
@@ -109,6 +135,22 @@ def __init__(self, inline):
         super(InlineShape, self).__init__()
         self._inline = inline
 
+    @classmethod
+    def new_picture(cls, r, image, rId, shape_id):
+        """
+        Return a new |InlineShape| instance containing an inline picture
+        placement of the image part *image* appended to run *r* and
+        uniquely identified by *shape_id*.
+        """
+        # width, height, filename = (
+        #     image.width, image.height, image.filename
+        # )
+        # pic = CT_Picture.new(filename, rId, width, height)
+        # inline = CT_Inline.new_inline(width, height, shape_id, pic)
+        # r.add_drawing(inline)
+        # return cls(inline)
+        raise NotImplementedError
+
     @property
     def type(self):
         graphicData = self._inline.graphic.graphicData
@@ -151,12 +193,26 @@ def __iter__(self):
     def __len__(self):
         return len(self._inline_lst)
 
-    def add_picture(self, image_path_or_stream):
+    def add_picture(self, image_descriptor):
+        """
+        Add the image identified by *image_descriptor* to the document at its
+        native size. The picture is placed inline in a new paragraph at the
+        end of the document. *image_descriptor* can be a path (a string) or a
+        file-like object containing a binary image.
+        """
+        rId, image = self.part.add_image(image_descriptor)
+        shape_id = self.part.next_id
+        r = self._body.add_p().add_r()
+        return InlineShape.new_picture(r, image, rId, shape_id)
+
+    @property
+    def part(self):
         """
-        Add the image at *image_path_or_stream* to the document at its native
-        size. The picture is placed inline in a new paragraph at the end of
-        the document.
+        The package part containing this object, a |_Document| instance in
+        this case.
         """
+        # return self._parent.part
+        raise NotImplementedError
 
     @property
     def _inline_lst(self):
diff --git a/tests/test_parts.py b/tests/test_parts.py
@@ -11,9 +11,10 @@
 from mock import Mock
 
 from docx.enum.shape import WD_INLINE_SHAPE
-from docx.oxml.parts import CT_Document
+from docx.oxml.parts import CT_Body, CT_Document
 from docx.oxml.shared import nsmap
-from docx.parts import _Body, _Document, InlineShape, InlineShapes
+from docx.oxml.text import CT_R
+from docx.parts import _Body, _Document, Image, InlineShape, InlineShapes
 from docx.table import Table
 from docx.text import Paragraph
 
@@ -26,7 +27,7 @@
 )
 from .oxml.unitdata.text import a_p, a_sectPr, an_r
 from .unitutil import (
-    function_mock, class_mock, initializer_mock, instance_mock
+    function_mock, class_mock, initializer_mock, instance_mock, property_mock
 )
 
 
@@ -360,8 +361,57 @@ def it_raises_on_indexed_access_out_of_range(
             too_high = inline_shape_count
             inline_shapes[too_high]
 
+    def it_can_add_an_inline_picture_to_the_document(
+            self, add_picture_fixture):
+        (inline_shapes, image_descriptor_, document_, InlineShape_, r_,
+         image_, rId_, shape_id_, new_picture_shape_) = add_picture_fixture
+        picture_shape = inline_shapes.add_picture(image_descriptor_)
+        document_.add_image.assert_called_once_with(image_descriptor_)
+        InlineShape_.new_picture.assert_called_once_with(
+            r_, image_, rId_, shape_id_
+        )
+        assert picture_shape is new_picture_shape_
+
     # fixtures -------------------------------------------------------
 
+    @pytest.fixture
+    def add_picture_fixture(
+            self, request, body_, document_, image_descriptor_, InlineShape_,
+            r_, image_, rId_, shape_id_, new_picture_shape_):
+        inline_shapes = InlineShapes(body_)
+        property_mock(request, InlineShapes, 'part', return_value=document_)
+        return (
+            inline_shapes, image_descriptor_, document_, InlineShape_, r_,
+            image_, rId_, shape_id_, new_picture_shape_
+        )
+
+    @pytest.fixture
+    def body_(self, request, r_):
+        body_ = instance_mock(request, CT_Body)
+        body_.add_p.return_value.add_r.return_value = r_
+        return body_
+
+    @pytest.fixture
+    def document_(self, request, rId_, image_, shape_id_):
+        document_ = instance_mock(request, _Document, name='document_')
+        document_.add_image.return_value = rId_, image_
+        document_.next_id = shape_id_
+        return document_
+
+    @pytest.fixture
+    def image_(self, request):
+        return instance_mock(request, Image)
+
+    @pytest.fixture
+    def image_descriptor_(self, request):
+        return instance_mock(request, str)
+
+    @pytest.fixture
+    def InlineShape_(self, request, new_picture_shape_):
+        InlineShape_ = class_mock(request, 'docx.parts.InlineShape')
+        InlineShape_.new_picture.return_value = new_picture_shape_
+        return InlineShape_
+
     @pytest.fixture
     def inline_shapes_fixture(self):
         inline_shape_count = 2
@@ -380,3 +430,19 @@ def inline_shapes_fixture(self):
         ).element
         inline_shapes = InlineShapes(body)
         return inline_shapes, inline_shape_count
+
+    @pytest.fixture
+    def new_picture_shape_(self, request):
+        return instance_mock(request, InlineShape)
+
+    @pytest.fixture
+    def r_(self, request):
+        return instance_mock(request, CT_R)
+
+    @pytest.fixture
+    def rId_(self, request):
+        return instance_mock(request, str)
+
+    @pytest.fixture
+    def shape_id_(self, request):
+        return instance_mock(request, int)
diff --git a/tests/unitutil.py b/tests/unitutil.py
@@ -6,7 +6,7 @@
 
 import os
 
-from mock import create_autospec, Mock, patch
+from mock import create_autospec, Mock, patch, PropertyMock
 
 from docx.oxml.shared import serialize_for_reading
 
@@ -106,6 +106,16 @@ def method_mock(request, cls, method_name, **kwargs):
     return _patch.start()
 
 
+def property_mock(request, cls, prop_name, **kwargs):
+    """
+    Return a mock for property *prop_name* on class *cls* where the patch is
+    reversed after pytest uses it.
+    """
+    _patch = patch.object(cls, prop_name, new_callable=PropertyMock, **kwargs)
+    request.addfinalizer(_patch.stop)
+    return _patch.start()
+
+
 def var_mock(request, q_var_name, **kwargs):
     """
     Return a mock patching the variable with qualified name *q_var_name*.
