"""Custom element classes for tables.""" from __future__ import annotations from typing import TYPE_CHECKING, Callable, cast from docx.enum.table import WD_CELL_VERTICAL_ALIGNMENT, WD_ROW_HEIGHT_RULE, WD_TABLE_DIRECTION from docx.exceptions import InvalidSpanError from docx.oxml.ns import nsdecls, qn from docx.oxml.parser import parse_xml from docx.oxml.shared import CT_DecimalNumber from docx.oxml.simpletypes import ( ST_Merge, ST_TblLayoutType, ST_TblWidth, ST_TwipsMeasure, XsdInt, ) from docx.oxml.text.paragraph import CT_P from docx.oxml.xmlchemy import ( BaseOxmlElement, OneAndOnlyOne, OneOrMore, OptionalAttribute, RequiredAttribute, ZeroOrMore, ZeroOrOne, ) from docx.shared import Emu, Length, Twips if TYPE_CHECKING: from docx.enum.table import WD_TABLE_ALIGNMENT from docx.enum.text import WD_ALIGN_PARAGRAPH from docx.oxml.shared import CT_OnOff, CT_String from docx.oxml.text.parfmt import CT_Jc class CT_Height(BaseOxmlElement): """Used for `w:trHeight` to specify a row height and row height rule.""" val: Length | None = OptionalAttribute( # pyright: ignore[reportAssignmentType] "w:val", ST_TwipsMeasure ) hRule: WD_ROW_HEIGHT_RULE | None = OptionalAttribute( # pyright: ignore[reportAssignmentType] "w:hRule", WD_ROW_HEIGHT_RULE ) class CT_Row(BaseOxmlElement): """```` element.""" add_tc: Callable[[], CT_Tc] get_or_add_trPr: Callable[[], CT_TrPr] _add_trPr: Callable[[], CT_TrPr] tc_lst: list[CT_Tc] # -- custom inserter below -- tblPrEx: CT_TblPrEx | None = ZeroOrOne("w:tblPrEx") # pyright: ignore[reportAssignmentType] # -- custom inserter below -- 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.""" trPr = self.trPr if trPr is None: return 0 return trPr.grid_before def tc_at_grid_offset(self, grid_offset: int) -> CT_Tc: """The `tc` element in this tr at exact `grid offset`. Raises ValueError when this `w:tr` contains no `w:tc` with exact starting `grid_offset`. """ # -- account for omitted cells at the start of the row -- remaining_offset = grid_offset - self.grid_before for tc in self.tc_lst: # -- We've gone past grid_offset without finding a tc, no sense searching further. -- if remaining_offset < 0: break # -- We've arrived at grid_offset, this is the `w:tc` we're looking for. -- if remaining_offset == 0: return tc # -- We're not there yet, skip forward the number of layout-grid cells this cell # -- occupies. remaining_offset -= tc.grid_span raise ValueError(f"no `tc` element at grid_offset={grid_offset}") @property def tr_idx(self) -> int: """Index of this `w:tr` element within its parent `w:tbl` element.""" tbl = cast(CT_Tbl, self.getparent()) return tbl.tr_lst.index(self) @property def trHeight_hRule(self) -> WD_ROW_HEIGHT_RULE | None: """The value of `./w:trPr/w:trHeight/@w:hRule`, or |None| if not present.""" trPr = self.trPr if trPr is None: return None return trPr.trHeight_hRule @trHeight_hRule.setter def trHeight_hRule(self, value: WD_ROW_HEIGHT_RULE | None): trPr = self.get_or_add_trPr() trPr.trHeight_hRule = value @property def trHeight_val(self): """Return the value of `w:trPr/w:trHeight@w:val`, or |None| if not present.""" trPr = self.trPr if trPr is None: return None return trPr.trHeight_val @trHeight_val.setter def trHeight_val(self, value: Length | None): trPr = self.get_or_add_trPr() trPr.trHeight_val = value def _insert_tblPrEx(self, tblPrEx: CT_TblPrEx): self.insert(0, tblPrEx) def _insert_trPr(self, trPr: CT_TrPr): tblPrEx = self.tblPrEx if tblPrEx is not None: tblPrEx.addnext(trPr) else: self.insert(0, trPr) def _new_tc(self): return CT_Tc.new() class CT_Tbl(BaseOxmlElement): """```` element.""" add_tr: Callable[[], CT_Row] tr_lst: list[CT_Row] tblPr: CT_TblPr = OneAndOnlyOne("w:tblPr") # pyright: ignore[reportAssignmentType] tblGrid: CT_TblGrid = OneAndOnlyOne("w:tblGrid") # pyright: ignore[reportAssignmentType] tr = ZeroOrMore("w:tr") @property def bidiVisual_val(self) -> bool | None: """Value of `./w:tblPr/w:bidiVisual/@w:val` or |None| if not present. Controls whether table cells are displayed right-to-left or left-to-right. """ bidiVisual = self.tblPr.bidiVisual if bidiVisual is None: return None return bidiVisual.val @bidiVisual_val.setter def bidiVisual_val(self, value: WD_TABLE_DIRECTION | None): tblPr = self.tblPr if value is None: tblPr._remove_bidiVisual() # pyright: ignore[reportPrivateUsage] else: tblPr.get_or_add_bidiVisual().val = bool(value) @property def col_count(self): """The number of grid columns in this table.""" return len(self.tblGrid.gridCol_lst) def iter_tcs(self): """Generate each of the `w:tc` elements in this table, left to right and top to bottom. Each cell in the first row is generated, followed by each cell in the second row, etc. """ for tr in self.tr_lst: for tc in tr.tc_lst: yield tc @classmethod def new_tbl(cls, rows: int, cols: int, width: Length) -> CT_Tbl: """Return a new `w:tbl` element having `rows` rows and `cols` columns. `width` is distributed evenly between the columns. """ return cast(CT_Tbl, parse_xml(cls._tbl_xml(rows, cols, width))) @property def tblStyle_val(self) -> str | None: """`w:tblPr/w:tblStyle/@w:val` (a table style id) or |None| if not present.""" tblStyle = self.tblPr.tblStyle if tblStyle is None: return None return tblStyle.val @tblStyle_val.setter def tblStyle_val(self, styleId: str | None) -> None: """Set the value of `w:tblPr/w:tblStyle/@w:val` (a table style id) to `styleId`. If `styleId` is None, remove the `w:tblStyle` element. """ tblPr = self.tblPr tblPr._remove_tblStyle() # pyright: ignore[reportPrivateUsage] if styleId is None: return tblPr._add_tblStyle().val = styleId # pyright: ignore[reportPrivateUsage] @classmethod def _tbl_xml(cls, rows: int, cols: int, width: Length) -> str: col_width = Emu(width // cols) if cols > 0 else Emu(0) return ( f"\n" f" \n" f' \n' f' \n' f" \n" f"{cls._tblGrid_xml(cols, col_width)}" f"{cls._trs_xml(rows, cols, col_width)}" f"\n" ) @classmethod def _tblGrid_xml(cls, col_count: int, col_width: Length) -> str: xml = " \n" for _ in range(col_count): xml += ' \n' % col_width.twips xml += " \n" return xml @classmethod def _trs_xml(cls, row_count: int, col_count: int, col_width: Length) -> str: return f" \n{cls._tcs_xml(col_count, col_width)} \n" * row_count @classmethod def _tcs_xml(cls, col_count: int, col_width: Length) -> str: return ( f" \n" f" \n" f' \n' f" \n" f" \n" f" \n" ) * col_count class CT_TblGrid(BaseOxmlElement): """`w:tblGrid` element. Child of `w:tbl`, holds `w:gridCol> elements that define column count, width, etc. """ add_gridCol: Callable[[], CT_TblGridCol] gridCol_lst: list[CT_TblGridCol] gridCol = ZeroOrMore("w:gridCol", successors=("w:tblGridChange",)) class CT_TblGridCol(BaseOxmlElement): """`w:gridCol` element, child of `w:tblGrid`, defines a table column.""" w: Length | None = OptionalAttribute( # pyright: ignore[reportAssignmentType] "w:w", ST_TwipsMeasure ) @property def gridCol_idx(self) -> int: """Index of this `w:gridCol` element within its parent `w:tblGrid` element.""" tblGrid = cast(CT_TblGrid, self.getparent()) return tblGrid.gridCol_lst.index(self) class CT_TblLayoutType(BaseOxmlElement): """`w:tblLayout` element. Specifies whether column widths are fixed or can be automatically adjusted based on content. """ type: str | None = OptionalAttribute( # pyright: ignore[reportAssignmentType] "w:type", ST_TblLayoutType ) class CT_TblPr(BaseOxmlElement): """```` element, child of ````, holds child elements that define table properties such as style and borders.""" get_or_add_bidiVisual: Callable[[], CT_OnOff] get_or_add_jc: Callable[[], CT_Jc] get_or_add_tblLayout: Callable[[], CT_TblLayoutType] _add_tblStyle: Callable[[], CT_String] _remove_bidiVisual: Callable[[], None] _remove_jc: Callable[[], None] _remove_tblStyle: Callable[[], None] _tag_seq = ( "w:tblStyle", "w:tblpPr", "w:tblOverlap", "w:bidiVisual", "w:tblStyleRowBandSize", "w:tblStyleColBandSize", "w:tblW", "w:jc", "w:tblCellSpacing", "w:tblInd", "w:tblBorders", "w:shd", "w:tblLayout", "w:tblCellMar", "w:tblLook", "w:tblCaption", "w:tblDescription", "w:tblPrChange", ) tblStyle: CT_String | None = ZeroOrOne( # pyright: ignore[reportAssignmentType] "w:tblStyle", successors=_tag_seq[1:] ) bidiVisual: CT_OnOff | None = ZeroOrOne( # pyright: ignore[reportAssignmentType] "w:bidiVisual", successors=_tag_seq[4:] ) jc: CT_Jc | None = ZeroOrOne( # pyright: ignore[reportAssignmentType] "w:jc", successors=_tag_seq[8:] ) tblLayout: CT_TblLayoutType | None = ZeroOrOne( # pyright: ignore[reportAssignmentType] "w:tblLayout", successors=_tag_seq[13:] ) del _tag_seq @property def alignment(self) -> WD_TABLE_ALIGNMENT | None: """Horizontal alignment of table, |None| if `./w:jc` is not present.""" jc = self.jc if jc is None: return None return cast("WD_TABLE_ALIGNMENT | None", jc.val) @alignment.setter def alignment(self, value: WD_TABLE_ALIGNMENT | None): self._remove_jc() if value is None: return jc = self.get_or_add_jc() jc.val = cast("WD_ALIGN_PARAGRAPH", value) @property def autofit(self) -> bool: """|False| when there is a `w:tblLayout` child with `@w:type="fixed"`. Otherwise |True|. """ tblLayout = self.tblLayout return True if tblLayout is None else tblLayout.type != "fixed" @autofit.setter def autofit(self, value: bool): tblLayout = self.get_or_add_tblLayout() tblLayout.type = "autofit" if value else "fixed" @property def style(self): """Return the value of the ``val`` attribute of the ```` child or |None| if not present.""" tblStyle = self.tblStyle if tblStyle is None: return None return tblStyle.val @style.setter def style(self, value: str | None): self._remove_tblStyle() if value is None: return self._add_tblStyle().val = value class CT_TblPrEx(BaseOxmlElement): """`w:tblPrEx` element, exceptions to table-properties. Applied at a lower level, like a `w:tr` to modify the appearance. Possibly used when two tables are merged. For more see: http://officeopenxml.com/WPtablePropertyExceptions.php """ class CT_TblWidth(BaseOxmlElement): """Used for `w:tblW` and `w:tcW` and others, specifies a table-related width.""" # the type for `w` attr is actually ST_MeasurementOrPercent, but using # XsdInt for now because only dxa (twips) values are being used. It's not # entirely clear what the semantics are for other values like -01.4mm w: int = RequiredAttribute("w:w", XsdInt) # pyright: ignore[reportAssignmentType] type = RequiredAttribute("w:type", ST_TblWidth) @property def width(self) -> Length | None: """EMU length indicated by the combined `w:w` and `w:type` attrs.""" if self.type != "dxa": return None return Twips(self.w) @width.setter def width(self, value: Length): self.type = "dxa" self.w = Emu(value).twips class CT_Tc(BaseOxmlElement): """`w:tc` table cell element.""" add_p: Callable[[], CT_P] get_or_add_tcPr: Callable[[], CT_TcPr] p_lst: list[CT_P] tbl_lst: list[CT_Tbl] _insert_tbl: Callable[[CT_Tbl], CT_Tbl] _new_p: Callable[[], CT_P] # -- tcPr has many successors, `._insert_tcPr()` is overridden below -- tcPr: CT_TcPr | None = ZeroOrOne("w:tcPr") # pyright: ignore[reportAssignmentType] p = OneOrMore("w:p") tbl = OneOrMore("w:tbl") @property def bottom(self) -> int: """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 elements, preserving `w:tcPr` element if present. Note that this leaves the `w:tc` element in an invalid state because it doesn't contain at least one block-level element. It's up to the caller to add a `w:p`child element as the last content element. """ # -- remove all cell inner-content except a `w:tcPr` when present. -- 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. Determined by ./w:tcPr/w:gridSpan/@val, it defaults to 1. """ tcPr = self.tcPr return 1 if tcPr is None else tcPr.grid_span @grid_span.setter def grid_span(self, value: int): tcPr = self.get_or_add_tcPr() tcPr.grid_span = value @property def inner_content_elements(self) -> list[CT_P | CT_Tbl]: """Generate all `w:p` and `w:tbl` elements in this document-body. Elements appear in document order. Elements shaded by nesting in a `w:ins` or other "wrapper" element will not be included. """ return self.xpath("./w:p | ./w:tbl") def iter_block_items(self): """Generate a reference to each of the block-level content elements in this cell, in the order they appear.""" block_item_tags = (qn("w:p"), qn("w:tbl"), qn("w:sdt")) for child in self: if child.tag in block_item_tags: yield child @property def left(self) -> int: """The grid column index at which this ```` element appears.""" return self.grid_offset def merge(self, other_tc: CT_Tc) -> CT_Tc: """Return top-left `w:tc` element of a new span. Span is formed by merging the rectangular region defined by using this tc element and `other_tc` as diagonal corners. """ top, left, height, width = self._span_dimensions(other_tc) top_tc = self._tbl.tr_lst[top].tc_at_grid_offset(left) top_tc._grow_to(width, height) return top_tc @classmethod def new(cls) -> CT_Tc: """A new `w:tc` element, containing an empty paragraph as the required EG_BlockLevelElt.""" return cast(CT_Tc, parse_xml("\n" " \n" "" % nsdecls("w"))) @property def right(self) -> int: """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_offset + self.grid_span @property def top(self) -> int: """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) -> str | None: """Value of ./w:tcPr/w:vMerge/@val, |None| if w:vMerge is not present.""" tcPr = self.tcPr if tcPr is None: return None return tcPr.vMerge_val @vMerge.setter def vMerge(self, value: str | None): tcPr = self.get_or_add_tcPr() tcPr.vMerge_val = value @property def width(self) -> Length | None: """EMU length represented in `./w:tcPr/w:tcW` or |None| if not present.""" tcPr = self.tcPr if tcPr is None: return None return tcPr.width @width.setter def width(self, value: Length): tcPr = self.get_or_add_tcPr() tcPr.width = value def _add_width_of(self, other_tc: CT_Tc): """Add the width of `other_tc` to this cell. Does nothing if either this tc or `other_tc` does not have a specified width. """ if self.width and other_tc.width: self.width = Length(self.width + other_tc.width) def _grow_to(self, width: int, height: int, top_tc: CT_Tc | None = None): """Grow this cell to `width` grid columns and `height` rows. This is accomplished by expanding horizontal spans and creating continuation cells to form vertical spans. """ def vMerge_val(top_tc: CT_Tc): return ( ST_Merge.CONTINUE if top_tc is not self else None if height == 1 else ST_Merge.RESTART ) top_tc = self if top_tc is None else top_tc self._span_to_width(width, top_tc, vMerge_val(top_tc)) if height > 1: tc_below = self._tc_below assert tc_below is not None tc_below._grow_to(width, height - 1, top_tc) def _insert_tcPr(self, tcPr: CT_TcPr) -> CT_TcPr: """Override default `._insert_tcPr()`.""" # -- `tcPr`` has a large number of successors, but always comes first if it appears, # -- so just using insert(0, ...) rather than spelling out successors. self.insert(0, tcPr) return tcPr @property def _is_empty(self) -> bool: """True if this cell contains only a single empty `w:p` element.""" block_items = list(self.iter_block_items()) if len(block_items) > 1: return False # -- cell must include at least one block item but can be a `w:tbl`, `w:sdt`, # -- `w:customXml` or a `w:p` only_item = block_items[0] if isinstance(only_item, CT_P) and len(only_item.r_lst) == 0: return True return False def _move_content_to(self, other_tc: CT_Tc): """Append the content of this cell to `other_tc`. Leaves this cell with a single empty ```` element. """ if other_tc is self: return if self._is_empty: return other_tc._remove_trailing_empty_p() # -- appending moves each element from self to other_tc -- for block_element in self.iter_block_items(): other_tc.append(block_element) # -- add back the required minimum single empty element -- self.append(self._new_p()) def _new_tbl(self) -> None: raise NotImplementedError( "use CT_Tbl.new_tbl() to add a new table, specifying rows and columns" ) @property def _next_tc(self) -> CT_Tc | None: """The `w:tc` element immediately following this one in this row, or |None| if this is the last `w:tc` element in the row.""" following_tcs = self.xpath("./following-sibling::w:tc") return following_tcs[0] if following_tcs else None def _remove(self): """Remove this `w:tc` element from the XML tree.""" parent_element = self.getparent() assert parent_element is not None parent_element.remove(self) def _remove_trailing_empty_p(self): """Remove last content element from this cell if it's an empty `w:p` element.""" block_items = list(self.iter_block_items()) last_content_elm = block_items[-1] if not isinstance(last_content_elm, CT_P): return p = last_content_elm if len(p.r_lst) > 0: return self.remove(p) def _span_dimensions(self, other_tc: CT_Tc) -> tuple[int, int, int, int]: """Return a (top, left, height, width) 4-tuple specifying the extents of the merged cell formed by using this tc and `other_tc` as opposite corner extents.""" def raise_on_inverted_L(a: CT_Tc, b: CT_Tc): if a.top == b.top and a.bottom != b.bottom: raise InvalidSpanError("requested span not rectangular") if a.left == b.left and a.right != b.right: raise InvalidSpanError("requested span not rectangular") def raise_on_tee_shaped(a: CT_Tc, b: CT_Tc): top_most, other = (a, b) if a.top < b.top else (b, a) if top_most.top < other.top and top_most.bottom > other.bottom: raise InvalidSpanError("requested span not rectangular") left_most, other = (a, b) if a.left < b.left else (b, a) if left_most.left < other.left and left_most.right > other.right: raise InvalidSpanError("requested span not rectangular") raise_on_inverted_L(self, other_tc) raise_on_tee_shaped(self, other_tc) top = min(self.top, other_tc.top) left = min(self.left, other_tc.left) bottom = max(self.bottom, other_tc.bottom) right = max(self.right, other_tc.right) return top, left, bottom - top, right - left def _span_to_width(self, grid_width: int, top_tc: CT_Tc, vMerge: str | None): """Incorporate `w:tc` elements to the right until this cell spans `grid_width`. Incorporated `w:tc` elements are removed (replaced by gridSpan value). Raises |ValueError| if `grid_width` cannot be exactly achieved, such as when a merged cell would drive the span width greater than `grid_width` or if not enough grid columns are available to make this cell that wide. All content from incorporated cells is appended to `top_tc`. The val attribute of the vMerge element on the single remaining cell is set to `vMerge`. If `vMerge` is |None|, the vMerge element is removed if present. """ self._move_content_to(top_tc) while self.grid_span < grid_width: self._swallow_next_tc(grid_width, top_tc) self.vMerge = vMerge def _swallow_next_tc(self, grid_width: int, top_tc: CT_Tc): """Extend the horizontal span of this `w:tc` element to incorporate the following `w:tc` element in the row and then delete that following `w:tc` element. Any content in the following `w:tc` element is appended to the content of `top_tc`. The width of the following `w:tc` element is added to this one, if present. Raises |InvalidSpanError| if the width of the resulting cell is greater than `grid_width` or if there is no next `` element in the row. """ def raise_on_invalid_swallow(next_tc: CT_Tc | None): if next_tc is None: raise InvalidSpanError("not enough grid columns") if self.grid_span + next_tc.grid_span > grid_width: raise InvalidSpanError("span is not rectangular") next_tc = self._next_tc raise_on_invalid_swallow(next_tc) assert next_tc is not None next_tc._move_content_to(top_tc) self._add_width_of(next_tc) self.grid_span += next_tc.grid_span next_tc._remove() @property def _tbl(self) -> CT_Tbl: """The tbl element this tc element appears in.""" return cast(CT_Tbl, self.xpath("./ancestor::w:tbl[position()=1]")[0]) @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_offset(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_offset(self.grid_offset) @property def _tr(self) -> CT_Row: """The tr element this tc element appears in.""" return cast(CT_Row, self.xpath("./ancestor::w:tr[position()=1]")[0]) @property def _tr_above(self) -> CT_Row: """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_aboves = self.xpath("./ancestor::w:tr[position()=1]/preceding-sibling::w:tr[1]") if not tr_aboves: raise ValueError("no tr above topmost tr in w:tbl") return tr_aboves[0] @property def _tr_below(self) -> CT_Row | None: """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) -> int: """The row index of the tr element this tc element appears in.""" return self._tbl.tr_lst.index(self._tr) class CT_TcPr(BaseOxmlElement): """```` element, defining table cell properties.""" get_or_add_gridSpan: Callable[[], CT_DecimalNumber] get_or_add_tcW: Callable[[], CT_TblWidth] get_or_add_vAlign: Callable[[], CT_VerticalJc] _add_vMerge: Callable[[], CT_VMerge] _remove_gridSpan: Callable[[], None] _remove_vAlign: Callable[[], None] _remove_vMerge: Callable[[], None] _tag_seq = ( "w:cnfStyle", "w:tcW", "w:gridSpan", "w:hMerge", "w:vMerge", "w:tcBorders", "w:shd", "w:noWrap", "w:tcMar", "w:textDirection", "w:tcFitText", "w:vAlign", "w:hideMark", "w:headers", "w:cellIns", "w:cellDel", "w:cellMerge", "w:tcPrChange", ) tcW: CT_TblWidth | None = ZeroOrOne( # pyright: ignore[reportAssignmentType] "w:tcW", successors=_tag_seq[2:] ) gridSpan: CT_DecimalNumber | None = ZeroOrOne( # pyright: ignore[reportAssignmentType] "w:gridSpan", successors=_tag_seq[3:] ) vMerge: CT_VMerge | None = ZeroOrOne( # pyright: ignore[reportAssignmentType] "w:vMerge", successors=_tag_seq[5:] ) vAlign: CT_VerticalJc | None = ZeroOrOne( # pyright: ignore[reportAssignmentType] "w:vAlign", successors=_tag_seq[12:] ) del _tag_seq @property def grid_span(self) -> int: """The integer number of columns this cell spans. Determined by ./w:gridSpan/@val, it defaults to 1. """ gridSpan = self.gridSpan return 1 if gridSpan is None else gridSpan.val @grid_span.setter def grid_span(self, value: int): self._remove_gridSpan() if value > 1: self.get_or_add_gridSpan().val = value @property def vAlign_val(self): """Value of `w:val` attribute on `w:vAlign` child. Value is |None| if `w:vAlign` child is not present. The `w:val` attribute on `w:vAlign` is required. """ vAlign = self.vAlign if vAlign is None: return None return vAlign.val @vAlign_val.setter def vAlign_val(self, value: WD_CELL_VERTICAL_ALIGNMENT | None): if value is None: self._remove_vAlign() return self.get_or_add_vAlign().val = value @property def vMerge_val(self): """The value of the ./w:vMerge/@val attribute, or |None| if the w:vMerge element is not present.""" vMerge = self.vMerge if vMerge is None: return None return vMerge.val @vMerge_val.setter def vMerge_val(self, value: str | None): self._remove_vMerge() if value is not None: self._add_vMerge().val = value @property def width(self) -> Length | None: """EMU length in `./w:tcW` or |None| if not present or its type is not 'dxa'.""" tcW = self.tcW if tcW is None: return None return tcW.width @width.setter def width(self, value: Length): tcW = self.get_or_add_tcW() tcW.width = value class CT_TrPr(BaseOxmlElement): """```` element, defining table row properties.""" get_or_add_trHeight: Callable[[], CT_Height] _tag_seq = ( "w:cnfStyle", "w:divId", "w:gridBefore", "w:gridAfter", "w:wBefore", "w:wAfter", "w:cantSplit", "w:trHeight", "w:tblHeader", "w:tblCellSpacing", "w:jc", "w:hidden", "w:ins", "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:] ) trHeight: CT_Height | None = ZeroOrOne( # pyright: ignore[reportAssignmentType] "w:trHeight", successors=_tag_seq[8:] ) 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.""" 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.""" trHeight = self.trHeight return None if trHeight is None else trHeight.hRule @trHeight_hRule.setter def trHeight_hRule(self, value: WD_ROW_HEIGHT_RULE | None): if value is None and self.trHeight is None: return trHeight = self.get_or_add_trHeight() trHeight.hRule = value @property def trHeight_val(self): """Return the value of `w:trHeight@w:val`, or |None| if not present.""" trHeight = self.trHeight return None if trHeight is None else trHeight.val @trHeight_val.setter def trHeight_val(self, value: Length | None): if value is None and self.trHeight is None: return trHeight = self.get_or_add_trHeight() trHeight.val = value class CT_VerticalJc(BaseOxmlElement): """`w:vAlign` element, specifying vertical alignment of cell.""" val: WD_CELL_VERTICAL_ALIGNMENT = RequiredAttribute( # pyright: ignore[reportAssignmentType] "w:val", WD_CELL_VERTICAL_ALIGNMENT ) class CT_VMerge(BaseOxmlElement): """```` element, specifying vertical merging behavior of a cell.""" val: str | None = OptionalAttribute( # pyright: ignore[reportAssignmentType] "w:val", ST_Merge, default=ST_Merge.CONTINUE )