Table

Generic table structure which simplify the conversion from docx table format to CALS or HTML tables.

class benker.table.ColView(table, pos, styles=None, nature=None)

Bases: benker.table.TableView

A view on the table cells for a given column.

can_catch(cell)

Check if a cell can be caught by that view.

Parameters

cell (benker.cell.Cell) – table cell

Returns

True if the cell intercept to this view.

can_own(cell)

Check if a cell can be stored it that view.

Parameters

cell (benker.cell.Cell) – table cell

Returns

True if the cell belong to this view.

property col_pos

Column position in the table (1-based).

insert_cell(content, styles=None, nature=None, width=1, height=1)

Insert a new cell in the column at the next free position, or at the end.

Parameters
  • content – User-defined cell content. It can be of any type: None, str, int, float, a container (list), a XML element, etc. The same content can be shared by several cells, it’s your own responsibility to handle the copy (or deep copy) of the content reference when needed.

  • styles (typing.Dict[str, str]) – User-defined cell styles: a dictionary of key-value pairs. This values are useful to store some HTML-like styles (border-style, border-width, border-color, vertical-align, text-align, etc.). Of course, we are not tied to the HTML-like styles, you can use your own list of styles.

  • width (int) – Width of the cell (columns spanning), default to 1.

  • height (int) – Height of the cell (rows spanning), default to 1.

Variables

nature – a way to distinguish the body cells, from the header and the footer. The default value is None, but you can use “body”, “header”, “footer” or whatever is suitable for your needs. If set to None, the cell nature is inherited from the column nature.

Changed in version 0.4.2: The nature of a cell is inherited from its parent’s column.

class benker.table.RowView(table, pos, styles=None, nature=None)

Bases: benker.table.TableView

A view on the table cells for a given row.

can_catch(cell)

Check if a cell can be caught by that view.

Parameters

cell (benker.cell.Cell) – table cell

Returns

True if the cell intercept to this view.

can_own(cell)

Check if a cell can be stored it that view.

Parameters

cell (benker.cell.Cell) – table cell

Returns

True if the cell belong to this view.

insert_cell(content, styles=None, nature=None, width=1, height=1)

Insert a new cell in the row at the next free position, or at the end.

Parameters
  • content – User-defined cell content. It can be of any type: None, str, int, float, a container (list), a XML element, etc. The same content can be shared by several cells, it’s your own responsibility to handle the copy (or deep copy) of the content reference when needed.

  • styles (typing.Dict[str, str]) – User-defined cell styles: a dictionary of key-value pairs. This values are useful to store some HTML-like styles (border-style, border-width, border-color, vertical-align, text-align, etc.). Of course, we are not tied to the HTML-like styles, you can use your own list of styles.

  • width (int) – Width of the cell (columns spanning), default to 1.

  • height (int) – Height of the cell (rows spanning), default to 1.

Variables

nature – a way to distinguish the body cells, from the header and the footer. The default value is None, but you can use “body”, “header”, “footer” or whatever is suitable for your needs. If set to None, the cell nature is inherited from the row nature.

Changed in version 0.4.2: The nature of a cell is inherited from its parent’s row.

property row_pos

Row position in the table (1-based).

class benker.table.Table(cells=None, styles=None, nature=None)

Bases: benker.styled.Styled, collections.abc.MutableMapping

Table data structure used to simplify conversion to CALS or HTML.

Short demonstration:

>>> from benker.cell import Cell
>>> from benker.table import Table

>>> table = Table(styles={'frame': 'all'})

>>> table[(1, 1)] = Cell("one")
>>> table.rows[1].insert_cell("two")

>>> table[(2, 1)]
<Cell('two', styles={}, nature=None, x=2, y=1, width=1, height=1)>

>>> table.cols[1].insert_cell("alpha")
>>> table.cols[2].insert_cell("beta")
>>> (1, 2) in table
True

>>> del table[(1, 2)]
>>> (1, 2) in table
False

>>> len(table)
3

>>> for cell in table:
...     print(cell)
one
two
beta

>>> for row in table.rows:
...     print(row)
[one, two]
[beta]

>>> table.merge((1, 2), (2, 2))
>>> print(table)
+-----------+-----------+
|    one    |    two    |
+-----------------------+
|   beta                |
+-----------------------+

>>> table.expand((1, 1), width=3)
>>> print(table)
+-----------------------------------------------+
|              onetwo                           |
+-----------------------+-----------+-----------+
|   beta                |           |           |
+-----------------------+-----------+-----------+
property bounding_box

Bounding box of the table (None if the table is empty).

Return type

benker.box.Box

Returns

The bounding box.

cols

List of views of type ColView

expand(coord, width=0, height=0, content_appender=None)
fill_missing(bounding_box, content, styles=None, nature=None)

Fill the missing cells in the table.

This method is useful when some rows has missing cells (holes).

Parameters
  • bounding_box (Box) – The bounding box delimiting the cells/rows to fill if missing.

  • content – User-defined cell content. It can be of any type: None, str, int, float, a container (list), a XML element, etc. The same content can be shared by several cells, it’s your own responsibility to handle the copy (or deep copy) of the content reference when needed.

  • styles (typing.Dict[str, str]) – User-defined cell styles: a dictionary of key-value pairs. This values are useful to store some HTML-like styles (border-style, border-width, border-color, vertical-align, text-align, etc.). Of course, we are not tied to the HTML-like styles, you can use your own list of styles.

Variables

nature – a way to distinguish the body cells, from the header and the footer. The default value is None, but you can use “body”, “header”, “footer” or whatever is suitable for your needs. If set to None, the cell nature is inherited from the row nature.

New in version 0.5.0.

merge(start, end, content_appender=None)
nature

Cell nature used to distinguish the body cells, from the header and the footer.

rows

List of views of type RowView

class benker.table.TableView(table, pos, styles=None, nature=None)

Bases: benker.styled.Styled

Base class of RowView and ColView used to create a view on the table cells for a given row or column.

See also: TableViewList

adopt_cell(cell)

Event handler called by the system when a cell is about to be inserted in the table.

can_catch(cell)

Check if a cell can be caught by that view.

Parameters

cell (benker.cell.Cell) – table cell

Returns

True if the cell intercept to this view.

can_own(cell)

Check if a cell can be stored it that view.

Parameters

cell (benker.cell.Cell) – table cell

Returns

True if the cell belong to this view.

property caught_cells

List of cells caught (intercepted) by this view.

property owned_cells

List of cells owned by this view.

property table

Non-mutable reference to the table (instance of Table).

class benker.table.TableViewList(table, view_cls)

Bases: object

This class defined a (simplified) list of views.

Short demonstration:

>>> from benker.cell import Cell
>>> from benker.table import Table
>>> from benker.table import ColView
>>> from benker.table import RowView
>>> from benker.table import TableViewList

>>> red = Cell('red', x=1, y=1, height=2)
>>> pink = Cell('pink', x=2, y=1, width=2)
>>> blue = Cell('blue', x=2, y=2)
>>> table = Table([red, pink, blue])
>>> print(table)
+-----------+-----------------------+
|    red    |   pink                |
|           +-----------+-----------+
|           |   blue    |           |
+-----------+-----------+-----------+

>>> cols = TableViewList(table, ColView)
>>> len(cols)
3
>>> rows = TableViewList(table, RowView)
>>> len(rows)
2

>>> for pos, col in enumerate(cols, 1):
...     print("col #{pos}: {col}".format(pos=pos, col=str(col)))
col #1: [red]
col #2: [pink, blue]
col #3: []

>>> cols[3].insert_cell("yellow")
>>> print(table)
+-----------+-----------------------+
|    red    |   pink                |
|           +-----------+-----------+
|           |   blue    |  yellow   |
+-----------+-----------+-----------+
adopt_cell(cell)

Adopt a new cell in the views.

Parameters

cell (benker.cell.Cell) – New cell to adopt

refresh_all()

Cleanup and refresh all the views, taking into account the cells which are in the table grid.

class benker.table.ViewsProperty(view_cls)

Bases: object

Descriptor used to define the rows/cols properties in the class Table.