feat(table): add _Row.grid_cols_after

Author: scanny

features/steps/table.py

@@ -154,6 +154,13 @@ def given_a_table_having_two_rows(context: Context):
     context.table_ = document.tables[0]
 
 
+@given("a table row ending with {count} empty grid columns")
+def given_a_table_row_ending_with_count_empty_grid_columns(context: Context, count: str):
+    document = Document(test_docx("tbl-props"))
+    table = document.tables[8]
+    context.row = table.rows[int(count)]
+
+
 @given("a table row having height of {state}")
 def given_a_table_row_having_height_of_state(context: Context, state: str):
     table_idx = {"no explicit setting": 0, "2 inches": 2, "3 inches": 3}[state]
@@ -354,6 +361,13 @@ def then_can_iterate_over_row_collection(context: Context):
     assert actual_count == 2
 
 
+@then("row.grid_cols_after is {value}")
+def then_row_grid_cols_after_is_value(context: Context, value: str):
+    expected = int(value)
+    actual = context.row.grid_cols_after
+    assert actual == expected, "expected %s, got %s" % (expected, actual)
+
+
 @then("row.grid_cols_before is {value}")
 def then_row_grid_cols_before_is_value(context: Context, value: str):
     expected = 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_after
+    Given a table row ending with <count> empty grid columns
+     Then row.grid_cols_after is <count>
+
+    Examples: Row.grid_cols_after value cases
+      | count |
+      | 0     |
+      | 1     |
+      | 2     |
+
+
   Scenario Outline: Get Row.grid_cols_before
     Given a table row starting with <count> empty grid columns
      Then row.grid_cols_before is <count>

features/tbl-row-props.feature

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

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_after(self) -> int:
+        """The number of unpopulated layout-grid cells at the end of this row."""
+        trPr = self.trPr
+        if trPr is None:
+            return 0
+        return trPr.grid_after
+
     @property
     def grid_before(self) -> int:
         """The number of unpopulated layout-grid cells at the start of this row."""
@@ -893,6 +901,9 @@ class CT_TrPr(BaseOxmlElement):
         "w:del",
         "w:trPrChange",
     )
+    gridAfter: CT_DecimalNumber | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
+        "w:gridAfter", successors=_tag_seq[4:]
+    )
     gridBefore: CT_DecimalNumber | None = ZeroOrOne(  # pyright: ignore[reportAssignmentType]
         "w:gridBefore", successors=_tag_seq[3:]
     )
@@ -901,6 +912,12 @@ class CT_TrPr(BaseOxmlElement):
     )
     del _tag_seq
 
+    @property
+    def grid_after(self) -> int:
+        """The number of unpopulated layout-grid cells at the end of this row."""
+        gridAfter = self.gridAfter
+        return 0 if gridAfter is None else gridAfter.val
+
     @property
     def grid_before(self) -> int:
         """The number of unpopulated layout-grid cells at the start of this row."""

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_after(self) -> int:
+        """Count of unpopulated grid-columns after the last cell in this row.
+
+        Word allows a row to "end early", meaning that one or more cells are not present at the
+        end of that row.
+
+        Note these are not simply "empty" cells. The renderer reads this value and "skips" this
+        many columns after drawing the last 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. Visually this appears as a column (at the beginning or end, not in the middle) with
+        one or more cells missing.
+        """
+        return self._tr.grid_after
+
     @property
     def grid_cols_before(self) -> int:
         """Count of unpopulated grid-columns before the first cell in this row.

src/docx/table.py

@@ -645,6 +645,19 @@ 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:gridAfter{w:val=0}", 0),
+            ("w:tr/w:trPr/w:gridAfter{w:val=4}", 4),
+        ],
+    )
+    def it_knows_its_grid_cols_after(self, tr_cxml: str, expected_value: int | None, parent_: Mock):
+        row = _Row(cast(CT_Row, element(tr_cxml)), parent_)
+        assert row.grid_cols_after == expected_value
+
     @pytest.mark.parametrize(
         ("tr_cxml", "expected_value"),
         [