pdfme.table

class pdfme.table.PDFTable(content, fonts, x, y, width, height, widths=None, style=None, borders=None, fills=None, pdf=None)

Bases: object

Class that represents a PDF table.

The content argument is an iterable representing the rows of the table, and each row should be an iterable too, representing each of the columns in the row. The elements on a row iterable could be any of the elements that you pass to argument content list in class pdfme.content.PDFContent. Because of this you can add paragraphs, images and content boxes into a table cell.

Argument widths, if passed, should be an iterable with the width of each column in the table. If not passed, all the columns will have the same width.

Argument style, if passed, should be a dict with any of the following keys:

cell_margin: the margin of the four sides of the cells in the table. Default value is 5.
cell_margin_left: left margin of the cells in the table. Default value is cell_margin.
cell_margin_top: top margin of the cells in the table. Default value is cell_margin.
cell_margin_right: right margin of the cells in the table. Default value is cell_margin.
cell_margin_bottom: bottom margin of the cells in the table. Default value is cell_margin.
cell_fill: the color of all the cells in the table. Default value is None (transparent). See pdfme.color.parse_color() for information about this attribute.
border_width: the width of all the borders in the table. Default value is 0.5.
border_color: the color of all the borders in the table .Default value is 'black'. See pdfme.color.parse_color() for information about this attribute.
border_style: the style of all the borders in the table. It can be solid, dotted or solid. Default value is solid.

You can overwrite the default values for the cell fills and the borders with fills and borders arguments. These arguments, if passed, should be iterables of dicts. Each dict should have a pos key that contains a string with information of the vertical (rows) and horizontal (columns) position of the fills or borders you want to change, and for this, such a string should has 2 parts separated by a semi colon, the first one for the vertical position and the second one for the horizontal position. The position can be a single int, a comma-separated list of ints, or a slice (range), like the one you pass to get a slice of a python list. For borders you have to include a h or a v before the positions, to tell if you want to change vertical or horizontal borders. The indexes in this string can be negative, referring to positions from the end to the beginning.

The following are examples of valid pos strings:

'h0,1,-1;:' to modify the first, second and last horizontal lines in the table. The horizontal position is a single colon, and thus the whole horizontal lines are affected.
'::2;:' to modify all of the fills horizontally, every two rows. This would set the current fill to all the cells in the first row, the third row, the fifth row and so on.

Additional to the pos key for dicts inside fills iterable, you have to include a color key, with a valid color value. See pdfme.color.parse_color() for information about this attribute.

Additional to the pos key for dicts inside borders iterable, you can include width (border width), color (border color) and style (border style) keys.

If a cell element is a dict it’s style dict can have any of the following keys: cell_margin, cell_margin_left, cell_margin_top, cell_margin_right, cell_margin_bottom and cell_fill, to overwrite the default value of any of these parameters on its cell. In a cell dict, you can also include colspan and rowspan keys, to span it horizontally and vertically respectively. The cells being merged to this spanned cell should be None.

Here’s an example of a valid content value:

[
    ['row 1, col 1', 'row 1, col 2', 'row 1, col 3'],
    [
        'row2 col1',
        {
            'style': {'cell_margin': 10, }
            'colspan': 2, 'rowspan': 2
            '.': 'rows 2 to 3, cols 2 to 3',
        },
        None
    ],
    ['row 3, col 1', None, None],
]

Use method pdfme.table.PDFTable.run() to add as many rows as possible to the rectangle defined by x, y`, width and height. The rows are added to this rectangle, until they are all inside of it, or until all of the vertical space is used and the rest of the rows can not be added. In these two cases method run finishes, and the property finished will be True if all the elements were added, and False if the vertical space ran out. If finished is False, you can set a new rectangle (on a new page for example) and use method run again (passing the parameters of the new rectangle) to add the remaining elements that couldn’t be added in the last rectangle. You can keep doing this until all of the elements are added and therefore property finished is True.

By using this method the rows are not really added to the PDF object. After calling run, the properties fills and lines will be populated with the fills and lines of the tables that fitted inside the rectangle, and parts will be filled with the paragraphs and images that fitted inside the table rectangle too, and you have to add them by yourself to the PDF object before using method run again (in case finished is False), because they will be redefined for the next rectangle after calling it again. You can check the table method in PDF module to see how this process is done.

Parameters

content (iterable) – like the one just explained.
fonts (PDFFonts) – a PDFFonts object used to build paragraphs.
x (int, float) – the x position of the left of the table.
y (int, float) – the y position of the top of the table.
width (int, float) – the width of the table.
height (int, float) – the height of the table.
widths (Iterable, optional) – the widths of each column.
style (Union[dict, str], optional) – the default style of the table.
borders (Iterable, optional) – borders of the table.
fills (Iterable, optional) – fills of the table.
pdf (PDF, optional) – A PDF object used to get string styles inside the elements.

setup(x=None, y=None, width=None, height=None)

Method to change the size and position of the table.

Parameters

x (int, float, optional) – the x position of the left of the table.
y (int, float, optional) – the y position of the top of the table.
width (int, float, optional) – the width of the table.
height (int, float, optional) – the height of the table.

get_state()

Method to get the current state of this table. This can be used later in method pdfme.table.PDFTable.set_state() to restore this state in this table (like a checkpoint in a videogame).

Returns: a dict with the state of this table.
Return type: dict

set_state(current_index=None, delayed=None)

Method to set the state of this table.

The arguments of this method define the current state of this table, and with this method you can change that state.

Parameters

current_index (int, optional) – the index of the current row being added.
delayed (dict, optional) – a dict with delayed cells that should be added before the next row.

set_default_border(): Method to create attribute default_border containing the default border values.

parse_pos_string(pos, counts)

Method to convert a position string like the ones used in borders and fills arguments of this class, into a generator of positions obtained from this string.

For more information, see the definition of this class.

Parameters

pos (str) – position string.
counts (int) – the amount of columns or rows.

Yields

tuple – the horizontal and vertical index of each position obtained from the pos string.

parse_range_string(data, count)

Method to convert one of the parts of a position string like the ones used in borders and fills arguments of this class, into a iterator with all the positions obtained from this string.

For more information, see the definition of this class.

Parameters

data (str) – one of the parts of a position string.
counts (int) – the amount of columns or rows.

Returns

a list of indexes, or a range object.

Return type

iterable

setup_borders(borders)

Method to process the borders argument passed to this class, and populate attributes borders_h and borders_v.

Parameters: borders (iterable) – the borders argument passed to this class.

get_border(i, j, is_vert)

Method to get the border in the horizontal position i, and vertical position j. It takes a vertical border if is_vert is true, and a horizontal border if is_vert is false :param i: horizontal position. :type i: int :param j: vertical position. :type j: int :param is_vert: vertical (True) or horizontal (False) border. :type is_vert: bool

Returns: dict with description of the border in position i, j.
Return type: dict

setup_fills(fills)

Method to process the fills argument passed to this class, and populate attribute fills_defs.

Parameters: fills (iterable) – the fills argument passed to this class.

compare_borders(a, b)

Method that compares border dicts a and b and returns if they are equal (True) or not (False)

Parameters

a (dict) – first border.
b (dict) – second border.

Returns

if a and b are equal (True) or not (False).

Return type

bool

process_borders(col, border_left, border_top)

Method to setup the top and left borders of each cell

Parameters

col (int) – the columns number.
border_left (dict) – the left border dict.
border_top (dict) – the top border dict.

run(x=None, y=None, width=None, height=None)

Method to add as many rows as possible to the rectangle defined by x, y`, width and height attributes.

More information about this method in this class definition.

Parameters

x (int, float, optional) – the x position of the left of the table.
y (int, float, optional) – the y position of the top of the table.
width (int, float, optional) – the width of the table.
height (int, float, optional) – the height of the table.

add_row(row, is_delayed=False)

Method to add a row to this table.

Parameters

row (iterable) – the row iterable.
is_delayed (bool, optional) – whether this row is being added in delayed mode (True) or not (False).

Returns

string with the action that should be performed after this row is added.

Return type

str

get_cell_dimensions(col, border_left, border_top, cell_style, rowspan, colspan)

Method to get the cell dimensions at column col, taking into account the cell borders, and the column and row spans.

Parameters

col (int) – the column of the cell.
border_left (dict) – left border dict.
border_top (dict) – top border dict.
cell_style (dict) – cell style dict.
rowspan (int) – the row span.
colspan (int) – the column span.

Returns

tuple with position (x, y), size (width, height), and padding (left, top) for this cell.

Return type

tuple

is_span(col, border_left, border_top, is_delayed)

Method to check if cell at column col is part of a spanned cell (True) or not (False).

Parameters

col (int) – the column of the cell.
border_left (dict) – left border dict.
border_top (dict) – top border dict.
is_delayed (bool, optional) – whether this row is being added in delayed mode (True) or not (False).

Returns

whether col is part of a spanned cell (True) or not (False).

Return type

bool

get_cell_style(element)

Method to extract the cell style from a cell element.

Parameters: element (dict, str, list, tuple) – the cell element to extract the cell style from.
Returns: tuple with a copy of element, the element style, and the cell_style.
Return type: tuple

is_type(el, type_)

add_cell(col, element, is_delayed)

Method to add a cell to the current row.

Parameters

col (int) – the column index for the cell.
element (dict, str, list, tuple) – the cell element to be added.
is_delayed (bool, optional) – whether current row is being added in delayed mode (True) or not (False).

Returns

whether col is part of a spanned cell (True) or not (False).

Return type

bool

process_text(element, x, y, width, height, style, delayed)

Method to add a paragraph to a cell.

Parameters

col (int) – the column index of the cell.
element (dict) – the paragraph element
x (Number) – the x coordinate of the paragraph.
y (Number) – the y coordinate of the paragraph.
width (Number) – the width of the paragraph.
height (Number) – the height of the paragraph.
style (dict) – the paragraph style.
delayed (dict) – the delayed element to add the current paragraph if it can not be added completely to the current cell.

Returns

the height of the paragraph.

Return type

float

process_image(element, x, y, width, height, delayed)

Method to add an image to a cell.

Parameters

col (int) – the column index of the cell.
element (dict) – the image element
x (Number) – the x coordinate of the image.
y (Number) – the y coordinate of the image.
width (Number) – the width of the image.
height (Number) – the height of the image.
delayed (dict) – the delayed element to add the current image if it can not be added to the current cell.

Returns

the height of the image.

Return type

float

process_content(element, x, y, width, height, style, delayed)

Method to add a content box to a cell.

Parameters

col (int) – the column index of the cell.
element (dict) – the content box element
x (Number) – the x coordinate of the content box.
y (Number) – the y coordinate of the content box.
width (Number) – the width of the content box.
height (Number) – the height of the content box.
style (dict) – the content box style.
delayed (dict) – the delayed element to add the current content box if it can not be added completely to the current cell.

Returns

the height of the content box.

Return type

float

process_table(element, x, y, width, height, style, delayed)

Method to add a table to a cell.

Parameters

col (int) – the column index of the cell.
element (dict) – the table element
x (Number) – the x coordinate of the table.
y (Number) – the y coordinate of the table.
width (Number) – the width of the table.
height (Number) – the height of the table.
style (dict) – the table style.
delayed (dict) – the delayed element to add the current table if it can not be added completely to the current cell.

Returns

the height of the table.

Return type

float