docx.tableops
paper-docx 0.2.0 API reference
Narrow, guarded table operations (paper-docx).
Guards are CELL-WISE: an operation refuses when the cells or rows
it actually touches participate in a merge or hold a nested table — a merged
header row (the default shape of real tables) no longer blocks edits to plain
data cells. The failure mode this module exists to prevent is unchanged: a
"clever" edit that silently reshuffles a complex region. Cell updates route
through Span.replace, so formatting preservation, tracked changes and
refusal atomicity all come from the same machinery as body text.
check_install
funccheck_install() -> NoneRefuse when paper-docx and python-docx are both installed.
Returns
Nonedelete_row
funcdelete_row(table: 'Table', row: int) -> NoneDelete row row (0-based).
Refuses the last remaining row, since a rowless table is not valid WordprocessingML. Refuses a protected document, an out-of-range index, and a merged or nested target.
paramtable'Table'paramrowintReturns
Nonefind_table
funcfind_table(document: 'Document', *, near_text: str, match: str = 'exact') -> 'Table'The table with one physical cell containing near_text.
Matching is literal and exact by default; match="normalized" folds case,
typography, and whitespace. Paragraph boundaries within one cell are represented
by literal newlines, but a match never crosses from one cell into another. Only
top-level tables in the main document body are searched.
Zero matching tables raise TargetNotFoundError; more than one matching table
raises AmbiguousTargetError — make near_text more specific.
paramdocument'Document'paramnear_textstrparammatchstr= 'exact'Returns
'Table'insert_row_after
funcinsert_row_after(table: 'Table', row: int, values: Sequence[str], *, copy_format_from: Optional[int] = None) -> NoneInsert a row after row (0-based), copying formatting from copy_format_from and
filling values.
The copied template must have one direct paragraph per physical cell, containing only plain text runs with identical complete direct run properties. Cell and paragraph properties are preserved. Complex or conflicting templates refuse before population with guidance to use a simpler uniform template; they are never repaired or flattened.
Refuses a protected document, an out-of-range index, and a target row that is merged or holds a nested table.
paramtable'Table'paramrowintparamvaluesSequence[str]paramcopy_format_fromOptional[int]= NoneReturns
Nonenormalize_text
funcnormalize_text(value: str) -> strvalue normalized for matching: folded punctuation, collapsed
whitespace, casefolded. Never applied to document content on write.
ANY Unicode whitespace collapses to a single ASCII space (\s+, not just
the spaces in the table) so needles and document text normalize
identically no matter which exotic space either side carries.
paramvaluestrReturns
strupdate_cell
funcupdate_cell(table: 'Table', row: int, column: int, new_text: str, *, tracked: bool = False, author: Optional[str] = None, date: Optional[dt.datetime] = None) -> ReplaceResultReplace one cell's visible text and return a ReplaceResult (0-based row,
layout-grid column).
Runs through Span.replace, so a non-empty replacement inherits the target cell text's
starting run properties and reports whether later formatting regions were consumed. Guards
are cell-wise: a merged header elsewhere in the table does not block a plain target cell.
Refuses a protected document, an out-of-range address, and a marker-divided,
wrapper-divided, merged, multi-paragraph, or nested target.
paramtable'Table'paramrowintparamcolumnintparamnew_textstrparamtrackedbool= FalseparamauthorOptional[str]= NoneparamdateOptional[dt.datetime]= NoneReturns
docx.search.ReplaceResult