tbl: add CT_Tc.top, .left, .bottom, and .right

Author: Steve Canny

docx/oxml/table.py

@@ -29,7 +29,14 @@ 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
+        grid_col = 0
+        for tc in self.tc_lst:
+            if grid_col == idx:
+                return tc
+            grid_col += tc.grid_span
+            if grid_col > idx:
+                raise ValueError('no cell on grid column %d' % idx)
+        raise ValueError('index out of bounds')
 
     @property
     def tr_idx(self):
@@ -207,6 +214,20 @@ class CT_Tc(BaseOxmlElement):
     p = OneOrMore('w:p')
     tbl = OneOrMore('w:tbl')
 
+    @property
+    def bottom(self):
+        """
+        The row index that marks the bottom extent of the vertical span of
+        this cell. This is one greater than the index of the bottom-most row
+        of the span, similar to how a slice of the cell's rows would be
+        specified.
+        """
+        if self.vMerge is not None:
+            tc_below = self._tc_below
+            if tc_below is not None and tc_below.vMerge == ST_Merge.CONTINUE:
+                return tc_below.bottom
+        return self._tr_idx + 1
+
     def clear_content(self):
         """
         Remove all content child elements, preserving the ``<w:tcPr>``
@@ -232,6 +253,13 @@ def grid_span(self):
             return 1
         return tcPr.grid_span
 
+    @property
+    def left(self):
+        """
+        The grid column index at which this ``<w:tc>`` element appears.
+        """
+        return self._grid_col
+
     def merge(self, other_tc):
         """
         Return the top-left ``<w:tc>`` element of a new span formed by
@@ -255,6 +283,25 @@ def new(cls):
             '</w:tc>' % nsdecls('w')
         )
 
+    @property
+    def right(self):
+        """
+        The grid column index that marks the right-side extent of the
+        horizontal span of this cell. This is one greater than the index of
+        the right-most column of the span, similar to how a slice of the
+        cell's columns would be specified.
+        """
+        return self._grid_col + self.grid_span
+
+    @property
+    def top(self):
+        """
+        The top-most row index in the vertical span of this cell.
+        """
+        if self.vMerge is None or self.vMerge == ST_Merge.RESTART:
+            return self._tr_idx
+        return self._tc_above.top
+
     @property
     def vMerge(self):
         """
@@ -282,6 +329,16 @@ def width(self, value):
         tcPr = self.get_or_add_tcPr()
         tcPr.width = value
 
+    @property
+    def _grid_col(self):
+        """
+        The grid column at which this cell begins.
+        """
+        tr = self._tr
+        idx = tr.tc_lst.index(self)
+        preceding_tcs = tr.tc_lst[:idx]
+        return sum(tc.grid_span for tc in preceding_tcs)
+
     def _grow_to(self, width, height, top_tc=None):
         """
         Grow this cell to *width* grid columns and *height* rows by expanding
@@ -315,7 +372,63 @@ def _tbl(self):
         """
         The tbl element this tc element appears in.
         """
-        raise NotImplementedError
+        return self.xpath('./ancestor::w:tbl')[0]
+
+    @property
+    def _tc_above(self):
+        """
+        The `w:tc` element immediately above this one in its grid column.
+        """
+        return self._tr_above.tc_at_grid_col(self._grid_col)
+
+    @property
+    def _tc_below(self):
+        """
+        The tc element immediately below this one in its grid column.
+        """
+        tr_below = self._tr_below
+        if tr_below is None:
+            return None
+        return tr_below.tc_at_grid_col(self._grid_col)
+
+    @property
+    def _tr(self):
+        """
+        The tr element this tc element appears in.
+        """
+        return self.xpath('./ancestor::w:tr')[0]
+
+    @property
+    def _tr_above(self):
+        """
+        The tr element prior in sequence to the tr this cell appears in.
+        Raises |ValueError| if called on a cell in the top-most row.
+        """
+        tr_lst = self._tbl.tr_lst
+        tr_idx = tr_lst.index(self._tr)
+        if tr_idx == 0:
+            raise ValueError('no tr above topmost tr')
+        return tr_lst[tr_idx-1]
+
+    @property
+    def _tr_below(self):
+        """
+        The tr element next in sequence after the tr this cell appears in, or
+        |None| if this cell appears in the last row.
+        """
+        tr_lst = self._tbl.tr_lst
+        tr_idx = tr_lst.index(self._tr)
+        try:
+            return tr_lst[tr_idx+1]
+        except IndexError:
+            return None
+
+    @property
+    def _tr_idx(self):
+        """
+        The row index of the tr element this tc element appears in.
+        """
+        return self._tbl.tr_lst.index(self._tr)
 
 
 class CT_TcPr(BaseOxmlElement):

tests/oxml/test_table.py

@@ -10,12 +10,31 @@
 
 import pytest
 
+from docx.oxml import parse_xml
 from docx.oxml.table import CT_Row, CT_Tc
 
 from ..unitutil.cxml import element
+from ..unitutil.file import snippet_seq
 from ..unitutil.mock import instance_mock, method_mock, property_mock
 
 
+class DescribeCT_Row(object):
+
+    def it_raises_on_tc_at_grid_col(self, tc_raise_fixture):
+        tr, idx = tc_raise_fixture
+        with pytest.raises(ValueError):
+            tr.tc_at_grid_col(idx)
+
+    # fixtures -------------------------------------------------------
+
+    @pytest.fixture(params=[(0, 0, 3), (1, 0, 1)])
+    def tc_raise_fixture(self, request):
+        snippet_idx, row_idx, col_idx = request.param
+        tbl = parse_xml(snippet_seq('tbl-cells')[snippet_idx])
+        tr = tbl.tr_lst[row_idx]
+        return tr, col_idx
+
+
 class DescribeCT_Tc(object):
 
     def it_can_merge_to_another_tc(self, merge_fixture):
@@ -26,8 +45,34 @@ def it_can_merge_to_another_tc(self, merge_fixture):
         top_tc_._grow_to.assert_called_once_with(width, height)
         assert merged_tc is top_tc_
 
+    def it_knows_its_extents_to_help(self, extents_fixture):
+        tc, attr_name, expected_value = extents_fixture
+        extent = getattr(tc, attr_name)
+        assert extent == expected_value
+
+    def it_raises_on_tr_above(self, tr_above_raise_fixture):
+        tc = tr_above_raise_fixture
+        with pytest.raises(ValueError):
+            tc._tr_above
+
     # fixtures -------------------------------------------------------
 
+    @pytest.fixture(params=[
+        (0, 0, 0, 'top',    0), (2, 0, 1, 'top',    0),
+        (2, 1, 1, 'top',    0), (4, 2, 1, 'top',    1),
+        (0, 0, 0, 'left',   0), (1, 0, 1, 'left',   2),
+        (3, 1, 0, 'left',   0), (3, 1, 1, 'left',   2),
+        (0, 0, 0, 'bottom', 1), (1, 0, 0, 'bottom', 1),
+        (2, 0, 1, 'bottom', 2), (4, 1, 1, 'bottom', 3),
+        (0, 0, 0, 'right',  1), (1, 0, 0, 'right',  2),
+        (0, 0, 0, 'right',  1), (4, 2, 1, 'right',  3),
+    ])
+    def extents_fixture(self, request):
+        snippet_idx, row, col, attr_name, expected_value = request.param
+        tbl = parse_xml(snippet_seq('tbl-cells')[snippet_idx])
+        tc = tbl.tr_lst[row].tc_lst[col]
+        return tc, attr_name, expected_value
+
     @pytest.fixture
     def merge_fixture(
             self, tr_, _span_dimensions_, _tbl_, _grow_to_, top_tc_):
@@ -38,6 +83,13 @@ def merge_fixture(
         tr_.tc_at_grid_col.return_value = top_tc_
         return tc, other_tc, tr_, top_tc_, left, height, width
 
+    @pytest.fixture(params=[(0, 0, 0), (4, 0, 0)])
+    def tr_above_raise_fixture(self, request):
+        snippet_idx, row_idx, col_idx = request.param
+        tbl = parse_xml(snippet_seq('tbl-cells')[snippet_idx])
+        tc = tbl.tr_lst[row_idx].tc_lst[col_idx]
+        return tc
+
     # fixture components ---------------------------------------------
 
     @pytest.fixture