api: add Document.add_table()

Steve Canny · Steve Canny · commit 03e81d16380f · 2014-01-03T23:39:55.000-08:00
diff --git a/docx/api.py b/docx/api.py
@@ -97,6 +97,17 @@ def add_picture(self, image_path_or_stream, width=None, height=None):
 
         return picture
 
+    def add_table(self, rows, cols, style='LightShading-Accent1'):
+        """
+        Add a table having row and column counts of *rows* and *cols*
+        respectively and table style of *style*. If *style* is |None|, a
+        table with no style is produced.
+        """
+        table = self._document_part.add_table(rows, cols)
+        if style:
+            table.style = style
+        return table
+
     @property
     def body(self):
         """
diff --git a/docx/parts/document.py b/docx/parts/document.py
@@ -34,6 +34,13 @@ def add_paragraph(self):
         """
         return self.body.add_paragraph()
 
+    def add_table(self, rows, cols):
+        """
+        Return a table having *rows* rows and *cols* columns, newly appended
+        to the main document story.
+        """
+        raise NotImplementedError
+
     @property
     def blob(self):
         return serialize_part_xml(self._element)
diff --git a/tests/test_api.py b/tests/test_api.py
@@ -4,13 +4,18 @@
 Test suite for the docx.api module
 """
 
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
+
 import pytest
 
 from docx.api import Document
 from docx.enum.text import WD_BREAK
 from docx.opc.constants import CONTENT_TYPE as CT
 from docx.package import Package
 from docx.parts.document import DocumentPart, InlineShapes
+from docx.table import Table
 from docx.text import Paragraph, Run
 
 from .unitutil import (
@@ -89,6 +94,16 @@ def it_can_add_a_picture(self, add_picture_fixture):
         assert picture.height == expected_height
         assert picture is picture_
 
+    def it_can_add_a_table(self, add_table_fixture):
+        document, rows, cols, style, document_part_, expected_style, table_ = (
+            add_table_fixture
+        )
+        table = document.add_table(rows, cols, style)
+        print(table)
+        document_part_.add_table.assert_called_once_with(rows, cols)
+        assert table.style == expected_style
+        assert table == table_
+
     def it_provides_access_to_the_document_body(self, document):
         body = document.body
         assert body is document._document_part.body
@@ -154,6 +169,15 @@ def add_styled_paragraph_fixture(self, document, p_):
         style = 'foobaresque'
         return document, style, p_
 
+    @pytest.fixture(params=[None, 'LightShading-Accent1', 'foobar'])
+    def add_table_fixture(self, request, document, document_part_, table_):
+        rows, cols = 4, 2
+        style = expected_style = request.param
+        return (
+            document, rows, cols, style, document_part_, expected_style,
+            table_
+        )
+
     @pytest.fixture
     def add_text_paragraph_fixture(self, document, p_, r_):
         text = 'foobar\rbarfoo'
@@ -174,11 +198,12 @@ def document(self, open_):
         return Document()
 
     @pytest.fixture
-    def document_part_(self, request, p_, paragraphs_):
+    def document_part_(self, request, p_, paragraphs_, table_):
         document_part_ = instance_mock(
             request, DocumentPart, content_type=CT.WML_DOCUMENT_MAIN
         )
         document_part_.add_paragraph.return_value = p_
+        document_part_.add_table.return_value = table_
         document_part_.paragraphs = paragraphs_
         return document_part_
 
@@ -240,3 +265,7 @@ def save_fixture(self, request, open_, package_):
         file_ = instance_mock(request, str)
         document = Document()
         return document, package_, file_
+
+    @pytest.fixture
+    def table_(self, request):
+        return instance_mock(request, Table, style=None)
