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 argumentcontent
list in classpdfme.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 is5
.cell_margin_left
: left margin of the cells in the table. Default value iscell_margin
.cell_margin_top
: top margin of the cells in the table. Default value iscell_margin
.cell_margin_right
: right margin of the cells in the table. Default value iscell_margin
.cell_margin_bottom
: bottom margin of the cells in the table. Default value iscell_margin
.cell_fill
: the color of all the cells in the table. Default value isNone
(transparent). Seepdfme.color.parse_color()
for information about this attribute.border_width
: the width of all the borders in the table. Default value is0.5
.border_color
: the color of all the borders in the table .Default value is'black'
. Seepdfme.color.parse_color()
for information about this attribute.border_style
: the style of all the borders in the table. It can besolid
,dotted
orsolid
. Default value issolid
.
You can overwrite the default values for the cell fills and the borders with
fills
andborders
arguments. These arguments, if passed, should be iterables of dicts. Each dict should have apos
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 ah
or av
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 insidefills
iterable, you have to include acolor
key, with a valid color value. Seepdfme.color.parse_color()
for information about this attribute.Additional to the
pos
key for dicts insideborders
iterable, you can includewidth
(border width),color
(border color) andstyle
(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
andcell_fill
, to overwrite the default value of any of these parameters on its cell. In a cell dict, you can also includecolspan
androwspan
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 byx
,y`
,width
andheight
. 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 methodrun
finishes, and the propertyfinished
will be True if all the elements were added, and False if the vertical space ran out. Iffinished
is False, you can set a new rectangle (on a new page for example) and use methodrun
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 propertyfinished
is True.By using this method the rows are not really added to the PDF object. After calling
run
, the propertiesfills
andlines
will be populated with the fills and lines of the tables that fitted inside the rectangle, andparts
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 methodrun
again (in casefinished
is False), because they will be redefined for the next rectangle after calling it again. You can check thetable
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
andfills
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
andfills
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 attributesborders_h
andborders_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 positionj
. It takes a vertical border ifis_vert
istrue
, and a horizontal border ifis_vert
isfalse
: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 attributefills_defs
.- Parameters
fills (iterable) – the
fills
argument passed to this class.
- compare_borders(a, b)
Method that compares border dicts
a
andb
and returns if they are equal (True
) or not (False
)- Parameters
a (dict) – first border.
b (dict) – second border.
- Returns
if
a
andb
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
andheight
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 elementstyle
, and thecell_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