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, col_idx)

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].

property first_col

Read/write boolean property which, when true, indicates the first column should be formatted differently, as for a side-heading column at the far left of the table.

property first_row

Read/write boolean property which, when true, indicates the first row should be formatted differently, e.g. for column headings.

property horz_banding

Read/write boolean property which, when true, indicates the rows of the table should appear with alternating shading.

iter_cells()

Generate _Cell object for each cell in this table.

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

property last_col

Read/write boolean property which, when true, indicates the last column should be formatted differently, as for a row totals column at the far right of the table.

property last_row

Read/write boolean property which, when true, indicates the last row should be formatted differently, as for a totals row at the bottom of the table.

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].

property vert_banding

Read/write boolean property which, when true, indicates the columns of the table should appear with alternating shading.

_Column objects

class pptx.table._Column

Table column

property width

Width of column in EMU.

_Row objects

class pptx.table._Row

Table row

property cells

Read-only reference to collection of cells in row. An individual cell is referenced using list notation, e.g. cell = row.cells[0].

property 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, parent)

Table cell

fill

FillFormat instance for this cell, providing access to fill properties such as foreground color.

property is_merge_origin

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

property 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.

property margin_left

Read/write integer value of left margin of cell as a Length value object. If assigned None, the default value is used, 0.1 inches for left and right margins and 0.05 inches for top and bottom.

property margin_right

Right margin of cell.

property margin_top

Top margin of cell.

property margin_bottom

Bottom margin of cell.

merge(other_cell)

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.

property 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.

property 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()

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.

property text

Unicode (str in Python 3) representation of cell contents.

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.)

Either bytes (Python 2 str) or unicode (Python 3 str) can be assigned. Bytes can be 7-bit ASCII or UTF-8 encoded 8-bit bytes. Bytes values are converted to unicode assuming UTF-8 encoding (which correctly decodes ASCII).

property text_frame

TextFrame instance containing the text that appears in the cell.

property 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.