feat(table): add _Cell.grid_span

scanny · scanny · commit 382d43e41964 · 2024-04-29T16:06:02.000-07:00
diff --git a/features/steps/table.py b/features/steps/table.py
@@ -13,7 +13,7 @@
     WD_TABLE_DIRECTION,
 )
 from docx.shared import Inches
-from docx.table import Table, _Column, _Columns, _Row, _Rows
+from docx.table import Table, _Cell, _Column, _Columns, _Row, _Rows
 
 from helpers import test_docx
 
@@ -37,6 +37,13 @@ def given_a_3x3_table_having_span_state(context: Context, span_state: str):
     context.table_ = document.tables[table_idx]
 
 
+@given("a _Cell object spanning {count} layout-grid cells")
+def given_a_Cell_object_spanning_count_layout_grid_cells(context: Context, count: str):
+    document = Document(test_docx("tbl-cell-props"))
+    table = document.tables[0]
+    context.cell = _Cell(table._tbl.tr_lst[int(count)].tc_lst[0], table)
+
+
 @given("a _Cell object with {state} vertical alignment as cell")
 def given_a_Cell_object_with_vertical_alignment_as_cell(context: Context, state: str):
     table_idx = {
@@ -292,6 +299,13 @@ def when_I_set_the_table_autofit_to_setting(context: Context, setting: str):
 # then =====================================================
 
 
+@then("cell.grid_span is {count}")
+def then_cell_grid_span_is_count(context: Context, count: str):
+    expected = int(count)
+    actual = context.cell.grid_span
+    assert actual == expected, f"expected {expected}, got {actual}"
+
+
 @then("cell.tables[0] is a 2 x 2 table")
 def then_cell_tables_0_is_a_2x2_table(context: Context):
     cell = context.cell
diff --git a/features/steps/test_files/tbl-cell-props.docx b/features/steps/test_files/tbl-cell-props.docx
diff --git a/features/tbl-cell-props.feature b/features/tbl-cell-props.feature
@@ -4,6 +4,17 @@ Feature: Get and set table cell properties
   I need a way to get and set the properties of a table cell
 
 
+  Scenario Outline: Get _Cell.grid_span
+    Given a _Cell object spanning <count> layout-grid cells
+     Then cell.grid_span is <count>
+
+    Examples: Cell.grid_span value cases
+      | count |
+      | 1     |
+      | 2     |
+      | 4     |
+
+
   Scenario Outline: Get _Cell.vertical_alignment
     Given a _Cell object with <state> vertical alignment as cell
      Then cell.vertical_alignment is <value>
diff --git a/src/docx/table.py b/src/docx/table.py
@@ -222,6 +222,15 @@ def add_table(  # pyright: ignore[reportIncompatibleMethodOverride]
         self.add_paragraph()
         return table
 
+    @property
+    def grid_span(self) -> int:
+        """Number of layout-grid cells this cell spans horizontally.
+
+        A "normal" cell has a grid-span of 1. A horizontally merged cell has a grid-span of 2 or
+        more.
+        """
+        return self._tc.grid_span
+
     def merge(self, other_cell: _Cell):
         """Return a merged cell created by spanning the rectangular region having this
         cell and `other_cell` as diagonal corners.
diff --git a/tests/test_table.py b/tests/test_table.py
@@ -326,6 +326,19 @@ def table(self, document_: Mock):
 class Describe_Cell:
     """Unit-test suite for `docx.table._Cell` objects."""
 
+    @pytest.mark.parametrize(
+        ("tc_cxml", "expected_value"),
+        [
+            ("w:tc", 1),
+            ("w:tc/w:tcPr", 1),
+            ("w:tc/w:tcPr/w:gridSpan{w:val=1}", 1),
+            ("w:tc/w:tcPr/w:gridSpan{w:val=4}", 4),
+        ],
+    )
+    def it_knows_its_grid_span(self, tc_cxml: str, expected_value: int, parent_: Mock):
+        cell = _Cell(cast(CT_Tc, element(tc_cxml)), parent_)
+        assert cell.grid_span == expected_value
+
     @pytest.mark.parametrize(
         ("tc_cxml", "expected_text"),
         [
