api: add _Document.add_inline_picture()

Steve Canny · Steve Canny · commit 031c8b5b150d · 2013-12-26T15:27:02.000-08:00
Along the way:

* rename _pkg to _package in api._Document
* remove no-op return from api._Document.save()
diff --git a/docx/api.py b/docx/api.py
@@ -37,10 +37,18 @@ class _Document(object):
     """
     API class representing a Word document.
     """
-    def __init__(self, pkg, document_part):
+    def __init__(self, package, document_part):
         super(_Document, self).__init__()
         self._document = document_part
-        self._pkg = pkg
+        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)
 
     @property
     def body(self):
@@ -61,4 +69,4 @@ def save(self, file_):
         Save this document to *file_*, where *file_* can be either a path to
         a file (a string) or a file-like object.
         """
-        return self._pkg.save(file_)
+        self._package.save(file_)
diff --git a/docx/parts.py b/docx/parts.py
@@ -151,6 +151,13 @@ def __iter__(self):
     def __len__(self):
         return len(self._inline_lst)
 
+    def add_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.
+        """
+
     @property
     def _inline_lst(self):
         body = self._body
diff --git a/features/steps/shape.py b/features/steps/shape.py
@@ -52,7 +52,7 @@ def given_inline_shape_known_to_be_shape_of_type(context, shp_of_type):
 def when_add_inline_picture_to_document(context):
     document = context.document
     context.inline_shape = (
-        document.add_picture(test_file_path('monty-truth.png'))
+        document.add_inline_picture(test_file_path('monty-truth.png'))
     )
 
 
diff --git a/tests/test_api.py b/tests/test_api.py
@@ -10,6 +10,7 @@
 from docx.api import Document, _Document
 from docx.opc.constants import CONTENT_TYPE as CT
 from docx.opc.package import OpcPackage
+from docx.parts import InlineShapes
 
 from .unitutil import class_mock, instance_mock, var_mock
 
@@ -82,13 +83,32 @@ def it_provides_access_to_the_document_inline_shapes(self, document):
         body = document.inline_shapes
         assert body is document._document.inline_shapes
 
+    def it_can_add_an_inline_picture(self, add_picture_fixture):
+        document, inline_shapes, image_path_or_stream_, picture_shape_ = (
+            add_picture_fixture
+        )
+        picture_shape = document.add_inline_picture(image_path_or_stream_)
+        inline_shapes.add_picture.assert_called_once_with(
+            image_path_or_stream_
+        )
+        assert picture_shape is picture_shape_
+
     def it_can_save_the_package(self, save_fixture):
         document, package_, file_ = save_fixture
         document.save(file_)
         package_.save.assert_called_once_with(file_)
 
     # fixtures -------------------------------------------------------
 
+    @pytest.fixture
+    def add_picture_fixture(self, request, document_part_):
+        document = _Document(None, document_part_)
+        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_
+
     @pytest.fixture
     def document(self, request, package_, document_part_):
         return _Document(package_, document_part_)

Original file line number	Diff line number	Diff line change
`@@ -52,7 +52,7 @@ def given_inline_shape_known_to_be_shape_of_type(context, shp_of_type):`
`52`	`52`	`def when_add_inline_picture_to_document(context):`
`53`	`53`	`document = context.document`
`54`	`54`	`context.inline_shape = (`
`55`		`- document.add_picture(test_file_path('monty-truth.png'))`
	`55`	`+ document.add_inline_picture(test_file_path('monty-truth.png'))`
`56`	`56`	`)`
`57`	`57`
`58`	`58`