feat(table): add _Row.grid_cols_before

Author: scanny

features/steps/table.py

@@ -170,6 +170,13 @@ def given_a_table_row_having_height_rule_state(context: Context, state: str):
     context.row = table.rows[0]
 
 
+@given("a table row starting with {count} empty grid columns")
+def given_a_table_row_starting_with_count_empty_grid_columns(context: Context, count: str):
+    document = Document(test_docx("tbl-props"))
+    table = document.tables[7]
+    context.row = table.rows[int(count)]
+
+
 # when =====================================================
 
 
@@ -347,6 +354,13 @@ def then_can_iterate_over_row_collection(context: Context):
     assert actual_count == 2
 
 
+@then("row.grid_cols_before is {value}")
+def then_row_grid_cols_before_is_value(context: Context, value: str):
+    expected = int(value)
+    actual = context.row.grid_cols_before
+    assert actual == expected, "expected %s, got %s" % (expected, actual)
+
+
 @then("row.height is {value}")
 def then_row_height_is_value(context: Context, value: str):
     expected_height = None if value == "None" else int(value)

features/steps/test_files/tbl-props.docx

@@ -4,6 +4,17 @@ Feature: Get and set table row properties
   I need a way to get and set the properties of a table row
 
 
+  Scenario Outline: Get Row.grid_cols_before
+    Given a table row starting with <count> empty grid columns
+     Then row.grid_cols_before is <count>
+
+    Examples: Row.grid_cols_before value cases
+      | count |
+      | 0     |
+      | 1     |
+      | 3     |
+
+
   Scenario Outline: Get Row.height_rule
     Given a table row having height rule <state>
      Then row.height_rule is <value>

features/tbl-row-props.feature

@@ -159,6 +159,7 @@
 )
 
 register_element_cls("w:bidiVisual", CT_OnOff)
+register_element_cls("w:gridBefore", CT_DecimalNumber)
 register_element_cls("w:gridCol", CT_TblGridCol)
 register_element_cls("w:gridSpan", CT_DecimalNumber)
 register_element_cls("w:tbl", CT_Tbl)

src/docx/oxml/__init__.py

@@ -60,6 +60,14 @@ class CT_Row(BaseOxmlElement):
     trPr: CT_TrPr | None = ZeroOrOne("w:trPr")  # pyright: ignore[reportAssignmentType]
     tc = ZeroOrMore("w:tc")
 
+    @property
+    def grid_before(self) -> int:
+        """The number of unpopulated layout-grid cells at the start of this row."""
+        trPr = self.trPr
+        if trPr is None:
+            return 0
+        return trPr.grid_before
+
     def tc_at_grid_col(self, idx: int) -> CT_Tc:
         """`<w:tc>` element appearing at grid column `idx`.
 
@@ -885,11 +893,20 @@ class CT_TrPr(BaseOxmlElement):
         "w:del",
         "w:trPrChange",
     )
+    gridBefore: CT_DecimalNumber | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "w:gridBefore", successors=_tag_seq[3:]
+    )
     trHeight: CT_Height | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
         "w:trHeight", successors=_tag_seq[8:]
     )
     del _tag_seq
 
+    @property
+    def grid_before(self) -> int:
+        """The number of unpopulated layout-grid cells at the start of this row."""
+        gridBefore = self.gridBefore
+        return 0 if gridBefore is None else gridBefore.val
+
     @property
     def trHeight_hRule(self) -> WD_ROW_HEIGHT_RULE | None:
         """Return the value of `w:trHeight@w:hRule`, or |None| if not present."""

src/docx/oxml/table.py

@@ -385,6 +385,23 @@ def cells(self) -> tuple[_Cell, ...]:
         """Sequence of |_Cell| instances corresponding to cells in this row."""
         return tuple(self.table.row_cells(self._index))
 
+    @property
+    def grid_cols_before(self) -> int:
+        """Count of unpopulated grid-columns before the first cell in this row.
+
+        Word allows a row to "start late", meaning that one or more cells are not present at the
+        beginning of that row.
+
+        Note these are not simply "empty" cells. The renderer reads this value and skips forward to
+        the table layout-grid position of the first cell in this row; the renderer "skips" this many
+        columns before drawing the first cell.
+
+        Note this also implies that not all rows are guaranteed to have the same number of cells,
+        e.g. `_Row.cells` could have length `n` for one row and `n - m` for the next row in the same
+        table.
+        """
+        return self._tr.grid_before
+
     @property
     def height(self) -> Length | None:
         """Return a |Length| object representing the height of this cell, or |None| if

src/docx/table.py

@@ -645,6 +645,21 @@ def table_(self, request: FixtureRequest):
 class Describe_Row:
     """Unit-test suite for `docx.table._Row` objects."""
 
+    @pytest.mark.parametrize(
+        ("tr_cxml", "expected_value"),
+        [
+            ("w:tr", 0),
+            ("w:tr/w:trPr", 0),
+            ("w:tr/w:trPr/w:gridBefore{w:val=0}", 0),
+            ("w:tr/w:trPr/w:gridBefore{w:val=3}", 3),
+        ],
+    )
+    def it_knows_its_grid_cols_before(
+        self, tr_cxml: str, expected_value: int | None, parent_: Mock
+    ):
+        row = _Row(cast(CT_Row, element(tr_cxml)), parent_)
+        assert row.grid_cols_before == expected_value
+
     @pytest.mark.parametrize(
         ("tr_cxml", "expected_value"),
         [