Source code for pptx.table

# encoding: utf-8

"""Table-related objects such as Table and Cell."""

from __future__ import (
    absolute_import, division, print_function, unicode_literals
)

from pptx.compat import is_integer, to_unicode
from pptx.dml.fill import FillFormat
from pptx.oxml.table import TcRange
from pptx.shapes import Subshape
from pptx.text.text import TextFrame
from pptx.util import lazyproperty


[docs]class Table(object): """A DrawingML table object. Not intended to be constructed directly, use :meth:`.Slide.shapes.add_table` to add a table to a slide. """ def __init__(self, tbl, graphic_frame): super(Table, self).__init__() self._tbl = tbl self._graphic_frame = graphic_frame
[docs] def cell(self, 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. """ return _Cell(self._tbl.tc(row_idx, col_idx), self)
@lazyproperty def columns(self): """ Read-only reference to collection of |_Column| objects representing the table's columns. |_Column| objects are accessed using list notation, e.g. ``col = tbl.columns[0]``. """ return _ColumnCollection(self._tbl, self) @property def first_col(self): """ 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. """ return self._tbl.firstCol @first_col.setter def first_col(self, value): self._tbl.firstCol = value @property def first_row(self): """ Read/write boolean property which, when true, indicates the first row should be formatted differently, e.g. for column headings. """ return self._tbl.firstRow @first_row.setter def first_row(self, value): self._tbl.firstRow = value @property def horz_banding(self): """ Read/write boolean property which, when true, indicates the rows of the table should appear with alternating shading. """ return self._tbl.bandRow @horz_banding.setter def horz_banding(self, value): self._tbl.bandRow = value
[docs] def iter_cells(self): """Generate _Cell object for each cell in this table. Each grid cell is generated in left-to-right, top-to-bottom order. """ return (_Cell(tc, self) for tc in self._tbl.iter_tcs())
@property def last_col(self): """ 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. """ return self._tbl.lastCol @last_col.setter def last_col(self, value): self._tbl.lastCol = value @property def last_row(self): """ 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. """ return self._tbl.lastRow @last_row.setter def last_row(self, value): self._tbl.lastRow = value def notify_height_changed(self): """ Called by a row when its height changes, triggering the graphic frame to recalculate its total height (as the sum of the row heights). """ new_table_height = sum([row.height for row in self.rows]) self._graphic_frame.height = new_table_height def notify_width_changed(self): """ Called by a column when its width changes, triggering the graphic frame to recalculate its total width (as the sum of the column widths). """ new_table_width = sum([col.width for col in self.columns]) self._graphic_frame.width = new_table_width @property def part(self): """ The package part containing this table. """ return self._graphic_frame.part @lazyproperty def rows(self): """ Read-only reference to collection of |_Row| objects representing the table's rows. |_Row| objects are accessed using list notation, e.g. ``col = tbl.rows[0]``. """ return _RowCollection(self._tbl, self) @property def vert_banding(self): """ Read/write boolean property which, when true, indicates the columns of the table should appear with alternating shading. """ return self._tbl.bandCol @vert_banding.setter def vert_banding(self, value): self._tbl.bandCol = value
[docs]class _Cell(Subshape): """Table cell""" def __init__(self, tc, parent): super(_Cell, self).__init__(parent) self._tc = tc def __eq__(self, other): """|True| if this object proxies the same element as *other*. Equality for proxy objects is defined as referring to the same XML element, whether or not they are the same proxy object instance. """ if not isinstance(other, type(self)): return False return self._tc is other._tc def __ne__(self, other): if not isinstance(other, type(self)): return True return self._tc is not other._tc @lazyproperty def fill(self): """ |FillFormat| instance for this cell, providing access to fill properties such as foreground color. """ tcPr = self._tc.get_or_add_tcPr() return FillFormat.from_fill_parent(tcPr) @property def is_merge_origin(self): """True if this cell is the top-left grid cell in a merged cell.""" return self._tc.is_merge_origin @property def is_spanned(self): """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. """ return self._tc.is_spanned @property def margin_left(self): """ 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. """ return self._tc.marL @margin_left.setter def margin_left(self, margin_left): self._validate_margin_value(margin_left) self._tc.marL = margin_left @property def margin_right(self): """ Right margin of cell. """ return self._tc.marR @margin_right.setter def margin_right(self, margin_right): self._validate_margin_value(margin_right) self._tc.marR = margin_right @property def margin_top(self): """ Top margin of cell. """ return self._tc.marT @margin_top.setter def margin_top(self, margin_top): self._validate_margin_value(margin_top) self._tc.marT = margin_top @property def margin_bottom(self): """ Bottom margin of cell. """ return self._tc.marB @margin_bottom.setter def margin_bottom(self, margin_bottom): self._validate_margin_value(margin_bottom) self._tc.marB = margin_bottom
[docs] def merge(self, 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*. """ tc_range = TcRange(self._tc, other_cell._tc) if not tc_range.in_same_table: raise ValueError('other_cell from different table') if tc_range.contains_merged_cell: raise ValueError('range contains one or more merged cells') tc_range.move_content_to_origin() row_count, col_count = tc_range.dimensions for tc in tc_range.iter_top_row_tcs(): tc.rowSpan = row_count for tc in tc_range.iter_left_col_tcs(): tc.gridSpan = col_count for tc in tc_range.iter_except_left_col_tcs(): tc.hMerge = True for tc in tc_range.iter_except_top_row_tcs(): tc.vMerge = True
@property def span_height(self): """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`. """ return self._tc.rowSpan @property def span_width(self): """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`. """ return self._tc.gridSpan
[docs] def split(self): """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. """ if not self.is_merge_origin: raise ValueError( 'not a merge-origin cell; only a merge-origin cell can be sp' 'lit' ) tc_range = TcRange.from_merge_origin(self._tc) for tc in tc_range.iter_tcs(): tc.rowSpan = tc.gridSpan = 1 tc.hMerge = tc.vMerge = False
@property def text(self): """str representation of cell contents. The returned string will contain a newline character (``'\\n'``) for each new paragraph (after the first) and line break in the cell. Assignment to *text* replaces all text currently contained in the cell, resulting in a text frame containing exactly one paragraph. Each newline character in an assigned string will be replaced with a line break in the resulting paragraph. The assigned value can be a 7-bit ASCII string, a UTF-8 encoded 8-bit string, or unicode. String values are converted to unicode assuming UTF-8 encoding. """ return self.text_frame.text @text.setter def text(self, text): self.text_frame.text = to_unicode(text) @property def text_frame(self): """ |TextFrame| instance containing the text that appears in the cell. """ txBody = self._tc.get_or_add_txBody() return TextFrame(txBody, self) @property def vertical_anchor(self): """Vertical alignment of this cell. This value is a member of the :ref:`MsoVerticalAnchor` 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. """ return self._tc.anchor @vertical_anchor.setter def vertical_anchor(self, mso_anchor_idx): self._tc.anchor = mso_anchor_idx @staticmethod def _validate_margin_value(margin_value): """ Raise ValueError if *margin_value* is not a positive integer value or |None|. """ if (not is_integer(margin_value) and margin_value is not None): tmpl = "margin value must be integer or None, got '%s'" raise TypeError(tmpl % margin_value)
[docs]class _Column(Subshape): """Table column""" def __init__(self, gridCol, parent): super(_Column, self).__init__(parent) self._gridCol = gridCol @property def width(self): """ Width of column in EMU. """ return self._gridCol.w @width.setter def width(self, width): self._gridCol.w = width self._parent.notify_width_changed()
[docs]class _Row(Subshape): """Table row""" def __init__(self, tr, parent): super(_Row, self).__init__(parent) self._tr = tr @property def cells(self): """ Read-only reference to collection of cells in row. An individual cell is referenced using list notation, e.g. ``cell = row.cells[0]``. """ return _CellCollection(self._tr, self) @property def height(self): """ Height of row in EMU. """ return self._tr.h @height.setter def height(self, height): self._tr.h = height self._parent.notify_height_changed()
class _CellCollection(Subshape): """Horizontal sequence of row cells""" def __init__(self, tr, parent): super(_CellCollection, self).__init__(parent) self._tr = tr def __getitem__(self, idx): """Provides indexed access, (e.g. 'cells[0]').""" if idx < 0 or idx >= len(self._tr.tc_lst): msg = "cell index [%d] out of range" % idx raise IndexError(msg) return _Cell(self._tr.tc_lst[idx], self) def __iter__(self): """Provides iterability.""" return (_Cell(tc, self) for tc in self._tr.tc_lst) def __len__(self): """Supports len() function (e.g. 'len(cells) == 1').""" return len(self._tr.tc_lst) class _ColumnCollection(Subshape): """Sequence of table columns.""" def __init__(self, tbl, parent): super(_ColumnCollection, self).__init__(parent) self._tbl = tbl def __getitem__(self, idx): """ Provides indexed access, (e.g. 'columns[0]'). """ if idx < 0 or idx >= len(self._tbl.tblGrid.gridCol_lst): msg = "column index [%d] out of range" % idx raise IndexError(msg) return _Column(self._tbl.tblGrid.gridCol_lst[idx], self) def __len__(self): """ Supports len() function (e.g. 'len(columns) == 1'). """ return len(self._tbl.tblGrid.gridCol_lst) def notify_width_changed(self): """ Called by a column when its width changes. Pass along to parent. """ self._parent.notify_width_changed() class _RowCollection(Subshape): """Sequence of table rows""" def __init__(self, tbl, parent): super(_RowCollection, self).__init__(parent) self._tbl = tbl def __getitem__(self, idx): """ Provides indexed access, (e.g. 'rows[0]'). """ if idx < 0 or idx >= len(self): msg = "row index [%d] out of range" % idx raise IndexError(msg) return _Row(self._tbl.tr_lst[idx], self) def __len__(self): """ Supports len() function (e.g. 'len(rows) == 1'). """ return len(self._tbl.tr_lst) def notify_height_changed(self): """ Called by a row when its height changes. Pass along to parent. """ self._parent.notify_height_changed()