txt: add Run.add_picture()

Steve Canny · Steve Canny · commit d7001edba3fd · 2014-07-11T21:09:22.000-07:00
diff --git a/docx/parts/document.py b/docx/parts/document.py
@@ -206,7 +206,7 @@ def add_picture(self, image_descriptor, run):
     @property
     def _inline_lst(self):
         body = self._body
-        xpath = './w:p/w:r/w:drawing/wp:inline'
+        xpath = '//w:p/w:r/w:drawing/wp:inline'
         return body.xpath(xpath)
 
 
diff --git a/docx/text.py b/docx/text.py
@@ -196,6 +196,37 @@ def add_break(self, break_type=WD_BREAK.LINE):
         if clear is not None:
             br.clear = clear
 
+    def add_picture(self, image_path_or_stream, width=None, height=None):
+        """
+        Return an |InlineShape| instance containing the image identified by
+        *image_path_or_stream*, added to the end of this run.
+        *image_path_or_stream* can be a path (a string) or a file-like object
+        containing a binary image. 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.
+        """
+        inline_shapes = self.part.inline_shapes
+        picture = inline_shapes.add_picture(image_path_or_stream, self)
+
+        # 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
+
     def add_tab(self):
         """
         Add a ``<w:tab/>`` element at the end of the run, which Word
diff --git a/features/run-add-picture.feature b/features/run-add-picture.feature
@@ -3,15 +3,13 @@ Feature: Add picture to a run
   As a developer using python-docx
   I need a way to add a picture to a run
 
-  @wip
   Scenario: Add a picture to a body paragraph run
     Given a run
      When I add a picture to the run
      Then the picture appears at the end of the run
       And the document contains the inline picture
 
 
-  @wip
   Scenario Outline: Add a picture to a run in a table cell
     Given a run inside a table cell retrieved from <cell-source>
      When I add a picture to the run
diff --git a/tests/test_text.py b/tests/test_text.py
@@ -11,6 +11,8 @@
 from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_BREAK, WD_UNDERLINE
 from docx.oxml.ns import qn
 from docx.oxml.text import CT_P, CT_R
+from docx.parts.document import InlineShapes
+from docx.shape import InlineShape
 from docx.text import Paragraph, Run
 
 import pytest
@@ -280,6 +282,17 @@ def it_can_add_a_tab(self, add_tab_fixture):
         run.add_tab()
         assert run._r.xml == expected_xml
 
+    def it_can_add_a_picture(self, add_picture_fixture):
+        (run, image_descriptor_, width, height, inline_shapes_,
+         expected_width, expected_height, picture_) = add_picture_fixture
+        picture = run.add_picture(image_descriptor_, width, height)
+        inline_shapes_.add_picture.assert_called_once_with(
+            image_descriptor_, run
+        )
+        assert picture is picture_
+        assert picture.width == expected_width
+        assert picture.height == expected_height
+
     def it_can_remove_its_content_but_keep_formatting(self, clear_fixture):
         run, expected_xml = clear_fixture
         _run = run.clear()
@@ -314,6 +327,24 @@ def add_break_fixture(self, request):
         expected_xml = xml(expected_cxml)
         return run, break_type, expected_xml
 
+    @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, paragraph_, inline_shapes_, picture_):
+        width, height, expected_width, expected_height = request.param
+        paragraph_.part.inline_shapes = inline_shapes_
+        run = Run(None, paragraph_)
+        image_descriptor_ = 'image_descriptor_'
+        picture_.width, picture_.height = 200, 100
+        return (
+            run, image_descriptor_, width, height, inline_shapes_,
+            expected_width, expected_height, picture_
+        )
+
     @pytest.fixture(params=[
         ('w:r/w:t"foo"', 'w:r/(w:t"foo", w:tab)'),
     ])
@@ -529,6 +560,20 @@ def underline_raise_fixture(self, request):
 
     # fixture components ---------------------------------------------
 
+    @pytest.fixture
+    def inline_shapes_(self, request, picture_):
+        inline_shapes_ = instance_mock(request, InlineShapes)
+        inline_shapes_.add_picture.return_value = picture_
+        return inline_shapes_
+
+    @pytest.fixture
+    def paragraph_(self, request):
+        return instance_mock(request, Paragraph)
+
+    @pytest.fixture
+    def picture_(self, request):
+        return instance_mock(request, InlineShape)
+
     @pytest.fixture
     def Text_(self, request):
         return class_mock(request, 'docx.text.Text')
