doc: add Document.add_picture()

Steve Canny · Steve Canny · commit 253b179e18ca · 2015-02-14T21:53:09.000-08:00
diff --git a/docx/document.py b/docx/document.py
@@ -59,6 +59,22 @@ def add_paragraph(self, text='', style=None):
         """
         return self._body.add_paragraph(text, style)
 
+    def add_picture(self, image_path_or_stream, width=None, height=None):
+        """
+        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()
+        return run.add_picture(image_path_or_stream, width, height)
+
     @property
     def part(self):
         """
diff --git a/tests/test_document.py b/tests/test_document.py
@@ -13,6 +13,7 @@
 from docx.document import _Body, Document
 from docx.enum.text import WD_BREAK
 from docx.parts.document import DocumentPart
+from docx.shape import InlineShape
 from docx.text.paragraph import Paragraph
 from docx.text.run import Run
 
@@ -51,6 +52,12 @@ def it_can_add_a_paragraph(self, add_paragraph_fixture):
         document._body.add_paragraph.assert_called_once_with(text, style)
         assert paragraph is paragraph_
 
+    def it_can_add_a_picture(self, add_picture_fixture):
+        document, path, width, height, run_, picture_ = add_picture_fixture
+        picture = document.add_picture(path, width, height)
+        run_.add_picture.assert_called_once_with(path, width, height)
+        assert picture is picture_
+
     def it_provides_access_to_the_document_part(self, part_fixture):
         document, part_ = part_fixture
         assert document.part is part_
@@ -94,6 +101,14 @@ def add_paragraph_fixture(self, request, body_prop_, paragraph_):
         body_prop_.return_value.add_paragraph.return_value = paragraph_
         return document, text, style, paragraph_
 
+    @pytest.fixture
+    def add_picture_fixture(self, request, add_paragraph_, run_, picture_):
+        document = Document(None, None)
+        path, width, height = 'foobar.png', 100, 200
+        add_paragraph_.return_value.add_run.return_value = run_
+        run_.add_picture.return_value = picture_
+        return document, path, width, height, run_, picture_
+
     @pytest.fixture
     def body_fixture(self, _Body_, body_):
         document_elm = element('w:document/w:body')
@@ -132,6 +147,10 @@ def document_part_(self, request):
     def paragraph_(self, request):
         return instance_mock(request, Paragraph)
 
+    @pytest.fixture
+    def picture_(self, request):
+        return instance_mock(request, InlineShape)
+
     @pytest.fixture
     def run_(self, request):
         return instance_mock(request, Run)
