api: add Document.add_picture()

Steve Canny · Steve Canny · commit 086f2194230b · 2014-01-03T23:39:55.000-08:00
diff --git a/docs/conf.py b/docs/conf.py
@@ -112,6 +112,8 @@
 .. |Table| replace:: :class:`Table`
 
 .. |Text| replace:: :class:`Text`
+
+.. |ValueError| replace:: :class:`ValueError`
 """
 
 
diff --git a/docx/api.py b/docx/api.py
@@ -6,6 +6,8 @@
 OpcPackage graph.
 """
 
+from __future__ import absolute_import, division, print_function
+
 import os
 
 from docx.opc.constants import CONTENT_TYPE as CT
@@ -29,14 +31,6 @@ def __init__(self, docx=None):
         self._document_part = document_part
         self._package = package
 
-    def add_inline_picture(self, image_path_or_stream):
-        """
-        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.
-        """
-        return self.inline_shapes.add_picture(image_path_or_stream)
-
     def add_heading(self, text='', level=1):
         """
         Return a heading paragraph newly added to the end of the document,
@@ -64,6 +58,34 @@ def add_paragraph(self, text='', style=None):
             p.style = style
         return p
 
+    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.
+        """
+        picture = self.inline_shapes.add_picture(image_path_or_stream)
+
+        # 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
+
+        return picture
+
     @property
     def body(self):
         """
diff --git a/features/api-add-picture.feature b/features/api-add-picture.feature
@@ -0,0 +1,26 @@
+Feature: Append an inline picture on its own paragraph
+  In order add an image to a document
+  As a programmer using the basic python-docx API
+  I need a method that adds a picture in its own paragraph
+
+  Scenario: Add a picture at native size
+    Given a document
+     When I add a picture specifying only the image file
+     Then the document contains the inline picture
+      And the picture has its native width and height
+
+  Scenario: Add a picture specifying both width and height
+    Given a document
+     When I add a picture specifying 1.75" width and 2.5" height
+     Then the picture width is 1.75 inches
+      And the picture height is 2.5 inches
+
+  Scenario: Add a picture specifying only width
+    Given a document
+     When I add a picture specifying a width of 1.5 inches
+     Then the picture height is 2.14 inches
+
+  Scenario: Add a picture specifying only height
+    Given a document
+     When I add a picture specifying a height of 1.5 inches
+     Then the picture width is 1.05 inches
diff --git a/features/steps/api.py b/features/steps/api.py
@@ -6,6 +6,10 @@
 
 from behave import then, when
 
+from docx.shared import Inches
+
+from .helpers import test_file_path
+
 
 # when ====================================================
 
@@ -43,6 +47,37 @@ def when_add_paragraph_without_specifying_text_or_style(context):
     document.add_paragraph()
 
 
+@when('I add a picture specifying 1.75" width and 2.5" height')
+def when_add_picture_specifying_width_and_height(context):
+    document = context.document
+    context.picture = document.add_picture(
+        test_file_path('monty-truth.png'),
+        width=Inches(1.75), height=Inches(2.5)
+    )
+
+
+@when('I add a picture specifying a height of 1.5 inches')
+def when_add_picture_specifying_height(context):
+    document = context.document
+    context.picture = document.add_picture(
+        test_file_path('monty-truth.png'), height=Inches(1.5)
+    )
+
+
+@when('I add a picture specifying a width of 1.5 inches')
+def when_add_picture_specifying_width(context):
+    document = context.document
+    context.picture = document.add_picture(
+        test_file_path('monty-truth.png'), width=Inches(1.5)
+    )
+
+
+@when('I add a picture specifying only the image file')
+def when_add_picture_specifying_only_image_file(context):
+    document = context.document
+    context.picture = document.add_picture(test_file_path('monty-truth.png'))
+
+
 # then =====================================================
 
 @then('the last paragraph contains the heading text')
@@ -76,6 +111,37 @@ def then_last_p_is_empty_paragraph_added(context):
     assert p.text == ''
 
 
+@then('the picture has its native width and height')
+def then_picture_has_native_width_and_height(context):
+    picture = context.picture
+    assert picture.width == 1905000, 'got %d' % picture.width
+    assert picture.height == 2717800, 'got %d' % picture.height
+
+
+@then('the picture height is 2.14 inches')
+def then_picture_height_is_value_2(context):
+    picture = context.picture
+    assert picture.height == 1956816, 'got %d' % picture.height
+
+
+@then('the picture height is 2.5 inches')
+def then_picture_height_is_value(context):
+    picture = context.picture
+    assert picture.height == 2286000, 'got %d' % picture.height
+
+
+@then('the picture width is 1.05 inches')
+def then_picture_width_is_value_2(context):
+    picture = context.picture
+    assert picture.width == 961402, 'got %d' % picture.width
+
+
+@then('the picture width is 1.75 inches')
+def then_picture_width_is_value(context):
+    picture = context.picture
+    assert picture.width == 1600200, 'got %d' % picture.width
+
+
 @then('the style of the last paragraph is \'{style}\'')
 def then_style_of_last_paragraph_is_style(context, style):
     document = context.document
diff --git a/features/steps/shape.py b/features/steps/shape.py
@@ -59,17 +59,15 @@ def given_inline_shape_known_to_be_shape_of_type(context, shp_of_type):
 def when_add_inline_picture_from_file_like_object(context):
     document = context.document
     with open(test_file_path('monty-truth.png')) as f:
-        context.inline_shape = (
-            document.add_inline_picture(f)
-        )
+        context.inline_shape = document.inline_shapes.add_picture(f)
 
 
 @when('I add an inline picture to the document')
 def when_add_inline_picture_to_document(context):
     document = context.document
-    context.inline_shape = (
-        document.add_inline_picture(test_file_path('monty-truth.png'))
-    )
+    context.inline_shape = (document.inline_shapes.add_picture(
+        test_file_path('monty-truth.png')
+    ))
 
 
 @when('I change the dimensions of the inline shape')
diff --git a/tests/test_api.py b/tests/test_api.py
@@ -12,7 +12,9 @@
 from docx.parts.document import DocumentPart, InlineShapes
 from docx.text import Paragraph, Run
 
-from .unitutil import class_mock, instance_mock, method_mock, var_mock
+from .unitutil import (
+    instance_mock, class_mock, method_mock, property_mock, var_mock
+)
 
 
 class DescribeDocument(object):
@@ -69,6 +71,15 @@ def it_can_add_a_styled_paragraph(self, add_styled_paragraph_fixture):
         p = document.add_paragraph(style=style)
         assert p.style == style
 
+    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)
+        assert picture.width == expected_width
+        assert picture.height == expected_height
+        assert picture is picture_
+
     def it_provides_access_to_the_document_body(self, document):
         body = document.body
         assert body is document._document_part.body
@@ -83,16 +94,6 @@ def it_provides_access_to_the_document_paragraphs(
         paragraphs = document.paragraphs
         assert paragraphs is paragraphs_
 
-    def it_can_add_an_inline_picture(self, add_picture_fixture):
-        document, inline_shapes, image_path_or_stream_, inline_picture_ = (
-            add_picture_fixture
-        )
-        inline_picture = document.add_inline_picture(image_path_or_stream_)
-        inline_shapes.add_picture.assert_called_once_with(
-            image_path_or_stream_
-        )
-        assert inline_picture is inline_picture_
-
     def it_can_save_the_package(self, save_fixture):
         document, package_, file_ = save_fixture
         document.save(file_)
@@ -117,14 +118,23 @@ def add_paragraph_(self, request, p_):
             request, Document, 'add_paragraph', return_value=p_
         )
 
-    @pytest.fixture
-    def add_picture_fixture(self, request, open_, document_part_):
+    @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
         document = Document()
-        inline_shapes = instance_mock(request, InlineShapes)
-        document_part_.inline_shapes = inline_shapes
-        image_path_ = instance_mock(request, str)
-        picture_shape_ = inline_shapes.add_picture.return_value
-        return document, inline_shapes, image_path_, picture_shape_
+        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_
+        )
 
     @pytest.fixture
     def add_styled_paragraph_fixture(self, document, p_):
@@ -140,6 +150,12 @@ def add_text_paragraph_fixture(self, document, p_, r_):
     def default_docx_(self, request):
         return var_mock(request, 'docx.api._default_docx_path')
 
+    @pytest.fixture
+    def Document_inline_shapes_(self, request, inline_shapes_):
+        return property_mock(
+            request, Document, 'inline_shapes', return_value=inline_shapes_
+        )
+
     @pytest.fixture
     def document(self, open_):
         return Document()
@@ -161,6 +177,10 @@ def docx_(self, request):
     def init_fixture(self, docx_, open_):
         return docx_, open_
 
+    @pytest.fixture
+    def inline_shapes_(self, request):
+        return instance_mock(request, InlineShapes)
+
     @pytest.fixture
     def open_(self, request, document_part_, package_):
         return method_mock(
