doc: add DocumentPart.new_pic_inline()

Steve Canny · Steve Canny · commit f1368d2114e0 · 2015-02-16T02:12:36.000-08:00
diff --git a/docx/image/image.py b/docx/image/image.py
@@ -117,6 +117,22 @@ def vert_dpi(self):
         """
         return self._image_header.vert_dpi
 
+    def scaled_dimensions(self, width, height):
+        """
+        Return a (cx, cy) 2-tuple representing the native dimensions of this
+        image scaled by applying the following rules to *width* and *height*.
+        If both *width* and *height* are specified, the return value is
+        (*width*, *height*); no scaling is performed. If only one is
+        specified, it is used to compute a scaling factor that is then
+        applied to the unspecified dimension, preserving the aspect ratio of
+        the image. If both *width* and *height* are |None|, the native
+        dimensions are returned. The native dimensions are calculated using
+        the dots-per-inch (dpi) value embedded in the image, defaulting to 72
+        dpi if no value is specified, as is often the case. The returned
+        values are both |Length| objects.
+        """
+        raise NotImplementedError
+
     @lazyproperty
     def sha1(self):
         """
diff --git a/docx/oxml/shape.py b/docx/oxml/shape.py
@@ -74,6 +74,18 @@ def new(cls, cx, cy, shape_id, pic):
         inline.graphic.graphicData._insert_pic(pic)
         return inline
 
+    @classmethod
+    def new_pic_inline(cls, shape_id, rId, filename, cx, cy):
+        """
+        Return a new `wp:inline` element containing the `pic:pic` element
+        specified by the argument values.
+        """
+        pic_id = 0  # Word doesn't seem to use this, but does not omit it
+        pic = CT_Picture.new(pic_id, filename, rId, cx, cy)
+        inline = cls.new(cx, cy, shape_id, pic)
+        inline.graphic.graphicData._insert_pic(pic)
+        return inline
+
     @classmethod
     def _inline_xml(cls):
         return (
diff --git a/docx/parts/document.py b/docx/parts/document.py
@@ -12,6 +12,7 @@
 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 .styles import StylesPart
@@ -41,6 +42,16 @@ def document(self):
         """
         return Document(self._element, self)
 
+    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.
+        """
+        raise NotImplementedError
+
     def get_or_add_image_part(self, image_descriptor):
         """
         Return an ``(image_part, rId)`` 2-tuple for the image identified by
@@ -86,7 +97,10 @@ def new_pic_inline(self, image_descriptor, width, height):
         specified by *image_descriptor* and scaled based on the values of
         *width* and *height*.
         """
-        raise NotImplementedError
+        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):
diff --git a/tests/parts/test_document.py b/tests/parts/test_document.py
@@ -8,6 +8,7 @@
 
 import pytest
 
+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 ImageParts, Package
@@ -21,6 +22,7 @@
 
 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 (
     instance_mock, class_mock, method_mock, property_mock
 )
@@ -81,6 +83,16 @@ 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, new_pic_fixture):
+        document_part, path, width, height = new_pic_fixture[:4]
+        image_, expected_xml = new_pic_fixture[4:]
+
+        inline = document_part.new_pic_inline(path, width, height)
+
+        document_part.get_or_add_image.assert_called_once_with(path)
+        image_.scaled_dimensions.assert_called_once_with(width, height)
+        assert inline.xml == expected_xml
+
     def it_can_get_a_style_by_id(self, get_style_fixture):
         document_part, style_id, style_type, style_ = get_style_fixture
         style = document_part.get_style(style_id, style_type)
@@ -163,6 +175,19 @@ def next_id_fixture(self, request):
         document = DocumentPart(None, None, document_elm, None)
         return document, expected_id
 
+    @pytest.fixture
+    def new_pic_fixture(self, image_, get_or_add_image_, next_id_prop_):
+        document_part = DocumentPart(None, None, None, None)
+        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
+
+        return document_part, path, width, height, image_, expected_xml
+
     @pytest.fixture
     def nmprt_create_fixture(self, part_related_by_, relate_to_,
                              NumberingPart_, numbering_part_):
@@ -222,6 +247,14 @@ def get_or_add_image_fixture(
             image_part_, rId_
         )
 
+    @pytest.fixture
+    def get_or_add_image_(self, request):
+        return method_mock(request, DocumentPart, 'get_or_add_image')
+
+    @pytest.fixture
+    def image_(self, request):
+        return instance_mock(request, Image)
+
     @pytest.fixture
     def image_descriptor_(self, request):
         return instance_mock(request, str)
@@ -240,6 +273,10 @@ def image_parts_(self, request, image_part_):
     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')
diff --git a/tests/test_files/snippets/inline.txt b/tests/test_files/snippets/inline.txt
@@ -0,0 +1,30 @@
+<wp:inline xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+  <wp:extent cx="444" cy="888"/>
+  <wp:docPr id="24" name="Picture 24"/>
+  <wp:cNvGraphicFramePr>
+    <a:graphicFrameLocks noChangeAspect="1"/>
+  </wp:cNvGraphicFramePr>
+  <a:graphic>
+    <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
+      <pic:pic>
+        <pic:nvPicPr>
+          <pic:cNvPr id="0" name="bar.png"/>
+          <pic:cNvPicPr/>
+        </pic:nvPicPr>
+        <pic:blipFill>
+          <a:blip r:embed="rId42"/>
+          <a:stretch>
+            <a:fillRect/>
+          </a:stretch>
+        </pic:blipFill>
+        <pic:spPr>
+          <a:xfrm>
+            <a:off x="0" y="0"/>
+            <a:ext cx="444" cy="888"/>
+          </a:xfrm>
+          <a:prstGeom prst="rect"/>
+        </pic:spPr>
+      </pic:pic>
+    </a:graphicData>
+  </a:graphic>
+</wp:inline>
