tbl: add _Cell.merge()

Apteryks · Steve Canny · commit 3a447d37d97b · 2014-11-28T21:45:43.000-05:00
diff --git a/docx/oxml/table.py b/docx/oxml/table.py
@@ -225,6 +225,14 @@ def grid_span(self):
             return 1
         return tcPr.grid_span
 
+    def merge(self, other_tc):
+        """
+        Return the top-left ``<w:tc>`` element of the span formed by merging
+        the rectangular region defined by using this tc element and
+        *other_tc* as diagonal corners.
+        """
+        raise NotImplementedError
+
     @classmethod
     def new(cls):
         """
diff --git a/docx/table.py b/docx/table.py
@@ -179,6 +179,17 @@ def add_table(self, rows, cols):
         self.add_paragraph()
         return new_table
 
+    def merge(self, other_cell):
+        """
+        Return a merged cell created by spanning the rectangular region
+        demarcated by using the extents of this cell and *other_cell* as
+        diagonal corners. Raises |InvalidSpanError| if the cells do not
+        define a rectangular region.
+        """
+        tc, tc_2 = self._tc, other_cell._tc
+        merged_tc = tc.merge(tc_2)
+        return _Cell(merged_tc, self._parent)
+
     @property
     def paragraphs(self):
         """
diff --git a/tests/test_table.py b/tests/test_table.py
@@ -9,6 +9,7 @@
 import pytest
 
 from docx.oxml import parse_xml
+from docx.oxml.table import CT_Tc
 from docx.shared import Inches
 from docx.table import _Cell, _Column, _Columns, _Row, _Rows, Table
 from docx.text import Paragraph
@@ -289,6 +290,14 @@ def it_can_add_a_table(self, add_table_fixture):
         assert cell._tc.xml == expected_xml
         assert isinstance(table, Table)
 
+    def it_can_merge_itself_with_other_cells(self, merge_fixture):
+        cell, other_cell, merged_tc_ = merge_fixture
+        merged_cell = cell.merge(other_cell)
+        cell._tc.merge.assert_called_once_with(other_cell._tc)
+        assert isinstance(merged_cell, _Cell)
+        assert merged_cell._tc is merged_tc_
+        assert merged_cell._parent is cell._parent
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture(params=[
@@ -317,6 +326,12 @@ def add_table_fixture(self, request):
         expected_xml = xml(after_tc_cxml)
         return cell, expected_xml
 
+    @pytest.fixture
+    def merge_fixture(self, tc_, tc_2_, parent_, merged_tc_):
+        cell, other_cell = _Cell(tc_, parent_), _Cell(tc_2_, parent_)
+        tc_.merge.return_value = merged_tc_
+        return cell, other_cell, merged_tc_
+
     @pytest.fixture
     def paragraphs_fixture(self):
         return _Cell(element('w:tc/(w:p, w:p)'), None)
@@ -383,6 +398,24 @@ def width_set_fixture(self, request):
         expected_xml = xml(expected_cxml)
         return cell, new_value, expected_xml
 
+    # fixture components ---------------------------------------------
+
+    @pytest.fixture
+    def merged_tc_(self, request):
+        return instance_mock(request, CT_Tc)
+
+    @pytest.fixture
+    def parent_(self, request):
+        return instance_mock(request, Table)
+
+    @pytest.fixture
+    def tc_(self, request):
+        return instance_mock(request, CT_Tc)
+
+    @pytest.fixture
+    def tc_2_(self, request):
+        return instance_mock(request, CT_Tc)
+
 
 class Describe_Column(object):
 
