doc: rewrite Document.add_table()

Steve Canny · Steve Canny · commit 7ea4d297485c · 2015-02-21T14:11:35.000-08:00
* Add width parameter to BlockItemContainer.add_table()
* Temporarily stub down-call-stack methods and tests with width=None
  until they are rewritten in next commits
* add Document._block_width to calculate width of table (page width less
  margins).
diff --git a/docx/blkcntnr.py b/docx/blkcntnr.py
@@ -37,10 +37,11 @@ def add_paragraph(self, text='', style=None):
             paragraph.style = style
         return paragraph
 
-    def add_table(self, rows, cols):
+    def add_table(self, rows, cols, width):
         """
-        Return a newly added table having *rows* rows and *cols* cols,
-        appended to the content in this container.
+        Return a table of *width* having *rows* rows and *cols* columns,
+        newly appended to the content in this container. *width* is evenly
+        distributed between the table columns.
         """
         from .table import Table
         tbl = self._element.add_tbl()
diff --git a/docx/document.py b/docx/document.py
@@ -12,7 +12,7 @@
 from .enum.section import WD_SECTION
 from .enum.text import WD_BREAK
 from .section import Section, Sections
-from .shared import ElementProxy
+from .shared import ElementProxy, Emu
 
 
 class Document(ElementProxy):
@@ -96,7 +96,7 @@ def add_table(self, rows, cols, style=None):
         style object or a paragraph style name. If *style* is |None|, the
         table inherits the default table style of the document.
         """
-        table = self._body.add_table(rows, cols)
+        table = self._body.add_table(rows, cols, self._block_width)
         table.style = style
         return table
 
@@ -167,6 +167,17 @@ def tables(self):
         """
         return self._body.tables
 
+    @property
+    def _block_width(self):
+        """
+        Return a |Length| object specifying the width of available "writing"
+        space between the margins of the last section of this document.
+        """
+        section = self.sections[-1]
+        return Emu(
+            section.page_width - section.left_margin - section.right_margin
+        )
+
     @property
     def _body(self):
         """
diff --git a/docx/table.py b/docx/table.py
@@ -201,7 +201,7 @@ def add_table(self, rows, cols):
         added after the table because Word requires a paragraph element as
         the last element in every cell.
         """
-        new_table = super(_Cell, self).add_table(rows, cols)
+        new_table = super(_Cell, self).add_table(rows, cols, 914400)
         self.add_paragraph()
         return new_table
 
diff --git a/tests/test_blkcntnr.py b/tests/test_blkcntnr.py
@@ -31,7 +31,7 @@ def it_can_add_a_paragraph(self, add_paragraph_fixture):
 
     def it_can_add_a_table(self, add_table_fixture):
         blkcntnr, rows, cols, expected_xml = add_table_fixture
-        table = blkcntnr.add_table(rows, cols)
+        table = blkcntnr.add_table(rows, cols, None)
         assert blkcntnr._element.xml == expected_xml
         assert isinstance(table, Table)
 
diff --git a/tests/test_document.py b/tests/test_document.py
@@ -15,8 +15,9 @@
 from docx.enum.text import WD_BREAK
 from docx.opc.coreprops import CoreProperties
 from docx.parts.document import DocumentPart
-from docx.section import Sections
+from docx.section import Section, Sections
 from docx.shape import InlineShape, InlineShapes
+from docx.shared import Length
 from docx.styles.styles import Styles
 from docx.table import Table
 from docx.text.paragraph import Paragraph
@@ -75,9 +76,9 @@ def it_can_add_a_section(self, add_section_fixture):
         assert section is section_
 
     def it_can_add_a_table(self, add_table_fixture):
-        document, rows, cols, style, table_ = add_table_fixture
+        document, rows, cols, style, width, table_ = add_table_fixture
         table = document.add_table(rows, cols, style)
-        document._body.add_table.assert_called_once_with(rows, cols)
+        document._body.add_table.assert_called_once_with(rows, cols, width)
         assert table == table_
         assert table.style == style
 
@@ -125,6 +126,12 @@ def it_provides_access_to_the_document_body(self, body_fixture):
         _Body_.assert_called_once_with(body_elm, document)
         assert body is body_
 
+    def it_determines_block_width_to_help(self, block_width_fixture):
+        document, expected_value = block_width_fixture
+        width = document._block_width
+        assert isinstance(width, Length)
+        assert width == expected_value
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture(params=[
@@ -186,11 +193,22 @@ def add_section_fixture(self, request, Section_):
         return document, start_type, Section_, section_, expected_xml
 
     @pytest.fixture
-    def add_table_fixture(self, body_prop_, table_):
+    def add_table_fixture(self, _block_width_prop_, body_prop_, table_):
         document = Document(None, None)
         rows, cols, style = 4, 2, 'Light Shading Accent 1'
         body_prop_.return_value.add_table.return_value = table_
-        return document, rows, cols, style, table_
+        _block_width_prop_.return_value = width = 42
+        return document, rows, cols, style, width, table_
+
+    @pytest.fixture
+    def block_width_fixture(self, sections_prop_, section_):
+        document = Document(None, None)
+        sections_prop_.return_value = [None, section_]
+        section_.page_width = 6000
+        section_.left_margin = 1500
+        section_.right_margin = 1000
+        expected_value = 3500
+        return document, expected_value
 
     @pytest.fixture
     def body_fixture(self, _Body_, body_):
@@ -261,6 +279,10 @@ def _Body_(self, request, body_):
     def body_(self, request):
         return instance_mock(request, _Body)
 
+    @pytest.fixture
+    def _block_width_prop_(self, request):
+        return property_mock(request, Document, '_block_width')
+
     @pytest.fixture
     def body_prop_(self, request, body_):
         return property_mock(request, Document, '_body', return_value=body_)
@@ -297,6 +319,10 @@ def run_(self, request):
     def Section_(self, request):
         return class_mock(request, 'docx.document.Section')
 
+    @pytest.fixture
+    def section_(self, request):
+        return instance_mock(request, Section)
+
     @pytest.fixture
     def Sections_(self, request):
         return class_mock(request, 'docx.document.Sections')
@@ -305,6 +331,10 @@ def Sections_(self, request):
     def sections_(self, request):
         return instance_mock(request, Sections)
 
+    @pytest.fixture
+    def sections_prop_(self, request):
+        return property_mock(request, Document, 'sections')
+
     @pytest.fixture
     def styles_(self, request):
         return instance_mock(request, Styles)
