doc: refactor Document.add_picture()

Steve Canny · Steve Canny · commit 158a78e6443e · 2014-07-11T21:10:34.000-07:00
Use Run.add_picture() to do the heavy lifting.
diff --git a/docx/api.py b/docx/api.py
@@ -78,31 +78,19 @@ def add_paragraph(self, text='', style=None):
 
     def add_picture(self, image_path_or_stream, width=None, height=None):
         """
-        Add the image at *image_path_or_stream* in a new paragraph at the end
-        of the document. If neither width nor height is specified, the
-        picture appears at its native size. 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. The
-        native size of the picture is calculated using the dots-per-inch
-        (dpi) value specified in the image file, defaulting to 72 dpi if no
-        value is specified, as is often the case.
+        Return a new picture shape added in its own paragraph at the end of
+        the document. The picture contains the image at
+        *image_path_or_stream*, scaled based on *width* and *height*. If
+        neither width nor height is specified, the picture appears at its
+        native size. 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. The native size of the
+        picture is calculated using the dots-per-inch (dpi) value specified
+        in the image file, defaulting to 72 dpi if no value is specified, as
+        is often the case.
         """
         run = self.add_paragraph().add_run()
-        picture = self.inline_shapes.add_picture(image_path_or_stream, run)
-
-        # scale picture dimensions if width and/or height provided
-        if width is not None or height is not None:
-            native_width, native_height = picture.width, picture.height
-            if width is None:
-                scaling_factor = float(height) / float(native_height)
-                width = int(round(native_width * scaling_factor))
-            elif height is None:
-                scaling_factor = float(width) / float(native_width)
-                height = int(round(native_height * scaling_factor))
-            # set picture to scaled dimensions
-            picture.width = width
-            picture.height = height
-
+        picture = run.add_picture(image_path_or_stream, width, height)
         return picture
 
     def add_section(self, start_type=WD_SECTION.NEW_PAGE):
diff --git a/tests/test_api.py b/tests/test_api.py
@@ -18,11 +18,12 @@
 from docx.parts.numbering import NumberingPart
 from docx.parts.styles import StylesPart
 from docx.section import Section
+from docx.shape import InlineShape
 from docx.table import Table
 from docx.text import Paragraph, Run
 
 from .unitutil.mock import (
-    ANY, instance_mock, class_mock, method_mock, property_mock, var_mock
+    instance_mock, class_mock, method_mock, property_mock, var_mock
 )
 
 
@@ -90,12 +91,11 @@ def it_can_add_a_page_break(self, add_page_break_fixture):
         assert paragraph is paragraph_
 
     def it_can_add_a_picture(self, add_picture_fixture):
-        (document, image_path, width, height, inline_shapes_, expected_width,
-         expected_height, picture_) = add_picture_fixture
-        picture = document.add_picture(image_path, width, height)
-        inline_shapes_.add_picture.assert_called_once_with(image_path, ANY)
-        assert picture.width == expected_width
-        assert picture.height == expected_height
+        document, image_path_, width, height, run_, picture_ = (
+            add_picture_fixture
+        )
+        picture = document.add_picture(image_path_, width, height)
+        run_.add_picture.assert_called_once_with(image_path_, width, height)
         assert picture is picture_
 
     def it_can_add_a_section(self, add_section_fixture):
@@ -195,23 +195,14 @@ def add_page_break_fixture(
             self, document, document_part_, paragraph_, run_):
         return document, document_part_, paragraph_, run_
 
-    @pytest.fixture(params=[
-        (None, None,  200,  100),
-        (1000, 500,  1000,  500),
-        (2000, None, 2000, 1000),
-        (None, 2000, 4000, 2000),
-    ])
-    def add_picture_fixture(
-            self, request, Document_inline_shapes_, inline_shapes_):
-        width, height, expected_width, expected_height = request.param
+    @pytest.fixture
+    def add_picture_fixture(self, request, run_, picture_):
         document = Document()
         image_path_ = instance_mock(request, str, name='image_path_')
-        picture_ = inline_shapes_.add_picture.return_value
-        picture_.width, picture_.height = 200, 100
-        return (
-            document, image_path_, width, height, inline_shapes_,
-            expected_width, expected_height, picture_
-        )
+        width, height = 100, 200
+        class_mock(request, 'docx.text.Run', return_value=run_)
+        run_.add_picture.return_value = picture_
+        return (document, image_path_, width, height, run_, picture_)
 
     @pytest.fixture
     def add_section_fixture(self, document, start_type_, section_):
@@ -330,12 +321,6 @@ def open_(self, request, document_part_, package_):
             return_value=(document_part_, package_)
         )
 
-    @pytest.fixture
-    def paragraph_(self, request, run_):
-        paragraph_ = instance_mock(request, Paragraph)
-        paragraph_.add_run.return_value = run_
-        return paragraph_
-
     @pytest.fixture
     def Package_(self, request, package_):
         Package_ = class_mock(request, 'docx.api.Package')
@@ -348,10 +333,20 @@ def package_(self, request, document_part_):
         package_.main_document = document_part_
         return package_
 
+    @pytest.fixture
+    def paragraph_(self, request, run_):
+        paragraph_ = instance_mock(request, Paragraph)
+        paragraph_.add_run.return_value = run_
+        return paragraph_
+
     @pytest.fixture
     def paragraphs_(self, request):
         return instance_mock(request, list)
 
+    @pytest.fixture
+    def picture_(self, request):
+        return instance_mock(request, InlineShape)
+
     @pytest.fixture
     def run_(self, request):
         return instance_mock(request, Run)
