tbl: add CT_Tc.merge()

Apteryks · Steve Canny · commit 538ed191cece · 2014-11-28T21:45:43.000-05:00
diff --git a/docx/oxml/table.py b/docx/oxml/table.py
@@ -24,6 +24,13 @@ class CT_Row(BaseOxmlElement):
     """
     tc = ZeroOrMore('w:tc')
 
+    def tc_at_grid_col(self, idx):
+        """
+        The ``<w:tc>`` element appearing at grid column *idx*. Raises
+        |ValueError| if no ``w:tc`` element begins at that grid column.
+        """
+        raise NotImplementedError
+
     @property
     def tr_idx(self):
         """
@@ -227,11 +234,14 @@ def grid_span(self):
 
     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
+        Return the top-left ``<w:tc>`` element of a new span formed by
+        merging the rectangular region defined by using this tc element and
         *other_tc* as diagonal corners.
         """
-        raise NotImplementedError
+        top, left, height, width = self._span_dimensions(other_tc)
+        top_tc = self._tbl.tr_lst[top].tc_at_grid_col(left)
+        top_tc._grow_to(width, height)
+        return top_tc
 
     @classmethod
     def new(cls):
@@ -272,6 +282,14 @@ def width(self, value):
         tcPr = self.get_or_add_tcPr()
         tcPr.width = value
 
+    def _grow_to(self, width, height, top_tc=None):
+        """
+        Grow this cell to *width* grid columns and *height* rows by expanding
+        horizontal spans and creating continuation cells to form vertical
+        spans.
+        """
+        raise NotImplementedError
+
     def _insert_tcPr(self, tcPr):
         """
         ``tcPr`` has a bunch of successors, but it comes first if it appears,
@@ -284,6 +302,21 @@ def _insert_tcPr(self, tcPr):
     def _new_tbl(self):
         return CT_Tbl.new()
 
+    def _span_dimensions(self, other_tc):
+        """
+        Return a (top, left, height, width) 4-tuple specifying the extents of
+        the merged cell formed by using this tc and *other_tc* as opposite
+        corner extents.
+        """
+        raise NotImplementedError
+
+    @property
+    def _tbl(self):
+        """
+        The tbl element this tc element appears in.
+        """
+        raise NotImplementedError
+
 
 class CT_TcPr(BaseOxmlElement):
     """
diff --git a/tests/oxml/test_table.py b/tests/oxml/test_table.py
@@ -0,0 +1,61 @@
+# encoding: utf-8
+
+"""
+Test suite for the docx.oxml.text module.
+"""
+
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
+
+import pytest
+
+from docx.oxml.table import CT_Row, CT_Tc
+
+from ..unitutil.cxml import element
+from ..unitutil.mock import instance_mock, method_mock, property_mock
+
+
+class DescribeCT_Tc(object):
+
+    def it_can_merge_to_another_tc(self, merge_fixture):
+        tc, other_tc, top_tr_, top_tc_, left, height, width = merge_fixture
+        merged_tc = tc.merge(other_tc)
+        tc._span_dimensions.assert_called_once_with(other_tc)
+        top_tr_.tc_at_grid_col.assert_called_once_with(left)
+        top_tc_._grow_to.assert_called_once_with(width, height)
+        assert merged_tc is top_tc_
+
+    # fixtures -------------------------------------------------------
+
+    @pytest.fixture
+    def merge_fixture(
+            self, tr_, _span_dimensions_, _tbl_, _grow_to_, top_tc_):
+        tc, other_tc = element('w:tc'), element('w:tc')
+        top, left, height, width = 0, 1, 2, 3
+        _span_dimensions_.return_value = top, left, height, width
+        _tbl_.return_value.tr_lst = [tr_]
+        tr_.tc_at_grid_col.return_value = top_tc_
+        return tc, other_tc, tr_, top_tc_, left, height, width
+
+    # fixture components ---------------------------------------------
+
+    @pytest.fixture
+    def _grow_to_(self, request):
+        return method_mock(request, CT_Tc, '_grow_to')
+
+    @pytest.fixture
+    def _span_dimensions_(self, request):
+        return method_mock(request, CT_Tc, '_span_dimensions')
+
+    @pytest.fixture
+    def _tbl_(self, request):
+        return property_mock(request, CT_Tc, '_tbl')
+
+    @pytest.fixture
+    def top_tc_(self, request):
+        return instance_mock(request, CT_Tc)
+
+    @pytest.fixture
+    def tr_(self, request):
+        return instance_mock(request, CT_Row)
