feat(table): add CT_Tc.grid_offset

scanny · scanny · commit 7508051c7664 · 2024-04-29T16:06:02.000-07:00
This property was formerly known as `._grid_col` but that didn't account
for `.grid_before` in the computation.
diff --git a/src/docx/oxml/table.py b/src/docx/oxml/table.py
@@ -450,6 +450,18 @@ def clear_content(self):
         for e in self.xpath("./*[not(self::w:tcPr)]"):
             self.remove(e)
 
+    @property
+    def grid_offset(self) -> int:
+        """Starting offset of `tc` in the layout-grid columns of its table.
+
+        A cell in the leftmost grid-column has offset 0.
+        """
+        grid_before = self._tr.grid_before
+        preceding_tc_grid_spans = sum(
+            tc.grid_span for tc in self.xpath("./preceding-sibling::w:tc")
+        )
+        return grid_before + preceding_tc_grid_spans
+
     @property
     def grid_span(self) -> int:
         """The integer number of columns this cell spans.
@@ -484,7 +496,7 @@ def iter_block_items(self):
     @property
     def left(self) -> int:
         """The grid column index at which this ``<w:tc>`` element appears."""
-        return self._grid_col
+        return self.grid_offset
 
     def merge(self, other_tc: CT_Tc) -> CT_Tc:
         """Return top-left `w:tc` element of a new span.
@@ -510,7 +522,7 @@ def right(self) -> int:
         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
+        return self.grid_offset + self.grid_span
 
     @property
     def top(self) -> int:
@@ -553,14 +565,6 @@ def _add_width_of(self, other_tc: CT_Tc):
         if self.width and other_tc.width:
             self.width = Length(self.width + other_tc.width)
 
-    @property
-    def _grid_col(self) -> int:
-        """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: int, height: int, top_tc: CT_Tc | None = None):
         """Grow this cell to `width` grid columns and `height` rows.
 
@@ -727,15 +731,15 @@ def _tbl(self) -> CT_Tbl:
     @property
     def _tc_above(self) -> CT_Tc:
         """The `w:tc` element immediately above this one in its grid column."""
-        return self._tr_above.tc_at_grid_col(self._grid_col)
+        return self._tr_above.tc_at_grid_col(self.grid_offset)
 
     @property
     def _tc_below(self) -> CT_Tc | None:
         """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)
+        return tr_below.tc_at_grid_col(self.grid_offset)
 
     @property
     def _tr(self) -> CT_Row:
diff --git a/tests/oxml/test_table.py b/tests/oxml/test_table.py
@@ -52,6 +52,22 @@ def it_raises_on_tc_at_grid_col(
 class DescribeCT_Tc:
     """Unit-test suite for `docx.oxml.table.CT_Tc` objects."""
 
+    @pytest.mark.parametrize(
+        ("tr_cxml", "tc_idx", "expected_value"),
+        [
+            ("w:tr/(w:tc/w:p,w:tc/w:p)", 0, 0),
+            ("w:tr/(w:tc/w:p,w:tc/w:p)", 1, 1),
+            ("w:tr/(w:trPr/w:gridBefore{w:val=2},w:tc/w:p,w:tc/w:p)", 0, 2),
+            ("w:tr/(w:trPr/w:gridBefore{w:val=2},w:tc/w:p,w:tc/w:p)", 1, 3),
+            ("w:tr/(w:trPr/w:gridBefore{w:val=4},w:tc/w:p,w:tc/w:p,w:tc/w:p,w:tc/w:p)", 2, 6),
+        ],
+    )
+    def it_knows_its_grid_offset(self, tr_cxml: str, tc_idx: int, expected_value: int):
+        tr = cast(CT_Row, element(tr_cxml))
+        tc = tr.tc_lst[tc_idx]
+
+        assert tc.grid_offset == expected_value
+
     def it_can_merge_to_another_tc(
         self, tr_: Mock, _span_dimensions_: Mock, _tbl_: Mock, _grow_to_: Mock, top_tc_: Mock
     ):
