Table-related objects

Table objects

A Table object is added to a slide using the add_table() method on SlideShapes.

class pptx.table.Table

A DrawingML table object.

Not intended to be constructed directly, use Slide.shapes.add_table() to add a table to a slide.

cell(row_idx: int, col_idx: int) → pptx.table._Cell

Return cell at row_idx, col_idx.

Return value is an instance of _Cell. row_idx and col_idx are zero-based, e.g. cell(0, 0) is the top, left cell in the table.

columns

_ColumnCollection instance for this table.

Provides access to _Column objects representing the table’s columns. _Column objects are accessed using list notation, e.g. col = tbl.columns[0].

first_col

When True, indicates first column should have distinct formatting.

Read/write. Distinct formatting is used, for example, when the first column contains row headings (is a side-heading column).

first_row

When True, indicates first row should have distinct formatting.

Read/write. Distinct formatting is used, for example, when the first row contains column headings.

horz_banding

When True, indicates rows should have alternating shading.

Read/write. Used to allow rows to be traversed more easily without losing track of which row is being read.

iter_cells() → Iterator[pptx.table._Cell]

Generate _Cell object for each cell in this table.

Each grid cell is generated in left-to-right, top-to-bottom order.

last_col

When True, indicates the rightmost column should have distinct formatting.

Read/write. Used, for example, when a row totals column appears at the far right of the table.

last_row

When True, indicates the bottom row should have distinct formatting.

Read/write. Used, for example, when a totals row appears as the bottom row.

rows

_RowCollection instance for this table.

Provides access to _Row objects representing the table’s rows. _Row objects are accessed using list notation, e.g. col = tbl.rows[0].

vert_banding

When True, indicates columns should have alternating shading.

Read/write. Used to allow columns to be traversed more easily without losing track of which column is being read.

_Column objects

class pptx.table._Column

Table column

width

Width of column in EMU.

_Row objects

class pptx.table._Row

Table row

cells

Read-only reference to collection of cells in row.

An individual cell is referenced using list notation, e.g. cell = row.cells[0].

height

Height of row in EMU.

_Cell objects

A _Cell object represents a single table cell at a particular row/column location in the table. _Cell objects are not constructed directly. A reference to a _Cell object is obtained using the Table.cell() method, specifying the cell’s row/column location. A cell object can also be obtained using the _Row.cells collection.

class pptx.table._Cell(tc: CT_TableCell, parent: ProvidesPart)

Table cell

fill

FillFormat instance for this cell.

Provides access to fill properties such as foreground color.

is_merge_origin

True if this cell is the top-left grid cell in a merged cell.

is_spanned

True if this cell is spanned by a merge-origin cell.

A merge-origin cell “spans” the other grid cells in its merge range, consuming their area and “shadowing” the spanned grid cells.

Note this value is False for a merge-origin cell. A merge-origin cell spans other grid cells, but is not itself a spanned cell.

margin_left

Left margin of cells.

Read/write. If assigned None, the default value is used, 0.1 inches for left and right margins and 0.05 inches for top and bottom.

margin_right

Right margin of cell.

margin_top

Top margin of cell.

margin_bottom

Bottom margin of cell.

merge(other_cell: pptx.table._Cell) → None

Create merged cell from this cell to other_cell.

This cell and other_cell specify opposite corners of the merged cell range. Either diagonal of the cell region may be specified in either order, e.g. self=bottom-right, other_cell=top-left, etc.

Raises ValueError if the specified range already contains merged cells anywhere within its extents or if other_cell is not in the same table as self.

span_height

int count of rows spanned by this cell.

The value of this property may be misleading (often 1) on cells where .is_merge_origin is not True, since only a merge-origin cell contains complete span information. This property is only intended for use on cells known to be a merge origin by testing .is_merge_origin.

span_width

int count of columns spanned by this cell.

The value of this property may be misleading (often 1) on cells where .is_merge_origin is not True, since only a merge-origin cell contains complete span information. This property is only intended for use on cells known to be a merge origin by testing .is_merge_origin.

split() → None

Remove merge from this (merge-origin) cell.

The merged cell represented by this object will be “unmerged”, yielding a separate unmerged cell for each grid cell previously spanned by this merge.

Raises ValueError when this cell is not a merge-origin cell. Test with .is_merge_origin before calling.

text

Textual content of cell as a single string.

The returned string will contain a newline character (“n”) separating each paragraph and a vertical-tab (“v”) character for each line break (soft carriage return) in the cell’s text.

Assignment to text replaces all text currently contained in the cell. A newline character (“n”) in the assigned text causes a new paragraph to be started. A vertical-tab (“v”) character in the assigned text causes a line-break (soft carriage-return) to be inserted. (The vertical-tab character appears in clipboard text copied from PowerPoint as its encoding of line-breaks.)

text_frame

TextFrame containing the text that appears in the cell.

vertical_anchor

Vertical alignment of this cell.

This value is a member of the MSO_VERTICAL_ANCHOR enumeration or None. A value of None indicates the cell has no explicitly applied vertical anchor setting and its effective value is inherited from its style-hierarchy ancestors.

Assigning None to this property causes any explicitly applied vertical anchor setting to be cleared and inheritance of its effective value to be restored.