pdfme.content

class pdfme.content.PDFContent(content, fonts, x, y, width, height, pdf=None)

Bases: object

This class represents a group of elements (paragraphs, images, tables) to be added to a pdfme.pdf.PDF instance; what is called a “content box” in this library.

This class receives as the first argument a dict representing the layout of the elements that are going to be added to the PDF. This dict must have a content key with a tuple or a list as its value, containing the elements to be added.

The elements are arranged by using method run from top to bottom, and from left to right in order, in the rectangle defined by args x, y, width and height. The elements 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 elements 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 method run the elements 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 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 content method in PDF module to see how this process is done.

This process of creating new pages to fit all of the elements of a content box is done automatically when you use pdfme.document.PDFDocument or :pdfme.document.build_pdf()

A cols key with a dict as a value can be included to arrange the elements in more than one column. For example, to use 2 columns, and to set a gap space between the 2 columns of 20 points, a dict like this one can be used:

{
    'cols': {'count': 2, 'gap': 20},
    'content': ['This is a lot of text ...'],
}

The elements in the content list can be one of the following:

A paragraph that can be a string, a list, a tuple or a dictionary with a key starting with a .. To know more about paragraphs check pdfme.text.PDFText. Additional to the keys that can be included inside style key of a paragraph dict like the one you pass to pdfme.text.PDFText, you can include the following too: text_align, line_height, indent, list_text, list_style and list_indent. For information about these attributes check pdfme.text.PDFText. Here is an example of a paragraph dict:
```
{
    'style': {
        'text_align': 'j',
        'line_height': 1.5,
        'list_text': '1. ',
    },
    '.b': 'This is a bold text.'
}
```
This paragraph dict yields a justified paragraph with a line height of 1.5 times the original line height and with a 1 on the left of the paragraph.
An image that should be a dict with a image key, holding the path of the image, or the bytes of the image. In case image is of type bytes two more keys should be added to this dict: image_name and extension, being the first a unique name for the image and the second the extension or format of the image (ex. “jpg”). This dict can have a style dict, to tell this class what should it do when an image don’t fit a column through the key image_place. This attribute can be “normal” or “flow”(default) and both of them will take the image to the next column or rectangle, but the second one will try to accommodate the elements coming after the image to fill the space left by it. Here is an example of an image dict:
```
{
    'style': { 'image_place': 'flow' },
    'image': '/path/to/an/image.jpg'
}
```
A table that should be a dict with a table key with the table data, and optionally any or all of the following keys: widths, borders and fills. To know more about these keys check their meaning in pdfme.table.PDFTable. Here is an example of a table dict:
```
{
    'table': [['col1', 'col2', 'col3'], ['value1', 'value2', 'value3']],
    'widths': [1,2,3],
    'borders': [{'pos': 'h0,1,3;:', 'width': 2, 'color': 0}]
}
```
A content box that can be a dict like the one being explained here, and can contain other elements inside it recursively. This can be used to insert a new section with more columns (for example a 2 columns content box, inside another 2 columns content box).
A group element that is a list of paragraphs, images or tables that should be placed all in the same page. This can be used for example to place an image with a description, with the guarantee that both will be in the same page. Be careful though, because the group element should fit the width and max height of the containing box, or else an error will be raised. This can be “relaxed” by setting min_height property style in the images inside the group. If an image does not have this property it will take as much space as possible, and if it does it will be shrinked as much as possible (without shrinking it beyond min_height) to make the other elements in the group fit in the available height. If there are more than one images in the group with min_height style property they will be shrinked together proportionally. If you want to ensure that some image will be shrinked until its min_height, use the shrink style property. Here is an example of a group element:
```
{
    "style": {"margin_left": 80, "margin_right": 80},
    "group": [
        {"image": "tests/image_test.jpg", "min_height": 200},
        {".": "Figure 1: Description of figure 1"}
    ]
}
```

Each element in the content box can have margins to keep it separated from the other elements, and these margins can be set inside the style dict of the content box dict with the following keys: margin_top, margin_left, margin_bottom and margin_right. Default value for all of them is 0, except for margin_bottom that have a default value of 5.

All of the children elements in the content box will inherit the the content box style.

Parameters

content (dict) – A content dict.
fonts (PDFFonts) – A PDFFonts object used to build paragraphs.
x (int, float) – The x position of the left of the rectangle.
y (int, float) – The y position of the top of the rectangle.
width (int, float) – The width of the rectangle where the contents will be arranged.
height (int, float) – The height of the rectangle where the contents will be arranged.
pdf (PDF, optional) – A PDF object used to get string styles inside the elements.

Raises

TypeError – if content is not a dict

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

Function to change any or all of the parameters of the rectangle of the content.

Parameters

x (int, float, optional) – The x coordinate of the left of the rectangle.
y (int, float, optional) – The y coordinate of the top of the rectangle.
width (int, float, optional) – The width of the rectangle where the contents will be arranged.
height (int, float, optional) – The height of the rectangle where the contents will be arranged.

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

Function to arrange this object elements in the rectangle defined by x, y, width and height.

More information about this method in this class definition.

Parameters

x (int, float, optional) – The x position of the left of the rectangle.
y (int, float, optional) – The y position of the top of the rectangle.
width (int, float, optional) – The width of the rectangle where the contents will be arranged.
height (int, float, optional) – The height of the rectangle where the contents will be arranged.

get_state()

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

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

set_state(section_element_index=None, section_delayed=None, children_memory=None)

Method to set the state of this content box.

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

Parameters

section_element_index (int, optional) – the index of the current element being added.
section_delayed (list, optional) – a list of delayed elements, that should be added before continuing with the rest of elements.
children_memory (list, optional) – if the current element is in turn a content box, this list says what the indexes of the nested content boxes inside this content box are.

class pdfme.content.PDFContentPart(content, pdf_content, min_x, width, min_y, max_y, parent=None, last=False, inherited_style=None)

Bases: object

Class that represent a content element.

This class has all the logic to arrange the content elements in the rectangle defined by min_x (left), min_y (top), width and max_y (bottom). This class needs a reference to a pdfme.content.PDFContent that will store the information of the lines, fills and parts of the elements arranged by this class, and all of the children PDFContentPart ‘s of this object. The description of the content argument is the same that the one from pdfme.content.PDFContent.

Parameters

content (dict) – A content dict.
pdf_content (PDFContent) – To store the fills, lines and parts of the elements of the content.
min_x (int, float) – The x position of the left of the rectangle.
width (int, float) – The width of the rectangle where the contents will be arranged.
min_y (int, float) – The y position of the top of the rectangle.
max_y (int, float) – The y position of the bottom of the rectangle.
parent (PDFContentPart, optional) – If not None, this is the parent of the current object, and it’s needed because the arranging process made by this object affects the parent arranging process and viceversa.
last (bool, optional) – This tells whether this is the last element of the list of elements of the parent. Defaults to False.
inherited_style (dict, optional) – The accumulated styles of all of the ancestors of the current object.

Raises

TypeError – If content is not a dict

setup(min_x, width, min_y, max_y)

Function to update the rectangle of this element.

Parameters

min_x (int, float) – The x position of the left of the rectangle.
width (int, float) – The width of the rectangle where the contents will be arranged.
min_y (int, float) – The y position of the top of the rectangle.
max_y (int, float) – The y position of the bottom of the rectangle.

get_state()

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

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

set_state(section_element_index=None, section_delayed=None, children_memory=None)

Method to set the state of this content box part.

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

Parameters

section_element_index (int, optional) – the index of the current element being added.
section_delayed (list, optional) – a list of delayed elements, that should be added before continuing with the rest of elements.
children_memory (list, optional) – if the current element is in turn a content box, this list says what the indexes of the nested content boxes inside this content box are.

add_delayed()

Function to add the delayed elements to the rectangle.

This function will try to add the delayed elements to the rectangle and it will return a string telling what the main loop should do, depending on what happened with the elements when they were being added to the rectangle.

Returns: any of the strings mentioned in pdfme.content.PDFContentPart.add_elements().

add_elements()

Function to add the elements in content to the rectangle.

This function will try to add the elements to the rectangle and it will return a string telling what the main loop should do, depending on what happened with the elements when they were being added to the rectangle.

Returns

'interrupt' means this element or one of its children reached the end of the rectangle of this element’s root ancestor, or what is the same, this element’s pdfme.content.PDFContent instance (the one saved in pdf_content attribute). This message will propagate to the ancestors until it reach the root ancestor and make the pdf_content to end running. After that the user should set a new rectangle, maybe in a new page, and call the pdfme.content.PDFContent.run() function again to keep adding the remaining elements that couldn’t be added before.
'break' means an ancestor is resetting and this element should stop adding elements.
'partial_next' means an ancestor has some remaining elements that need to be added and this element should stop.
'next' means that this element needs to move to the next section, to continue adding elements to the rectangle. The next section could be the next column of this element, or the next section of the parent.
'continue' means this element is done adding all of the elements (there could be delayed elements still).

is_element_resetting()

Function that returns a string depending on whether this element is resetting or not.

Returns: A string telling the main loop what should do next.

process_add_ans(ans)

Function that process the answers from methods pdfme.content.PDFContentPart.add_delayed() and pdfme.content.PDFContentPart.add_elements().

Parameters: ans (str) – Any of the strings described in pdfme.content.PDFContentPart.add_elements().
Returns: A string telling the main loop what should do next.

run()

Function to run the main loop that will add the content elements to the rectangle.

Returns: A string telling the parent what should it do afterwards.

last_child_of_resetting()

Function that recursively, towards the ancestors, checks if this element is the last element of the last element of one ancestor that is resetting.

Returns: True if this element is the last element of an ancestor that is resetting.

start_resetting(): Function that sets the attribute will_reset of this element or one of its ancestors to True.

reset()

Function that first checks if resetting process is over, and if not calculates a new value for attribute max_y and resets all of the elements added to the rectangle so far to repeat the arranging process.

Returns: True if resetting process should continue or False if this process is done.

go_to_beginning(): Function that takes the x and y coordinates of this element to the min_x and min_y coordinates.

next_section(children_memory=None)

Function that sets the x and y position of this element in the next section.

The next section could be the next column of this element or the next section of one of the ancestors. If some ancestor is resetting, or the end of the rectangle of the root element is reached, a string with a instruction for the caller will propagate this message towards the ancestors to act according to it.

Parameters: children_memory (list, optional) – This is a list containing the children’s indexes and delayed elements, that is accumulated towards the ancestors.
Returns: A string containing a message to the main loop, or a dict containing the new x and y coordinates that the children are going to have from now on.
Return type: str, dict

get_min_x()

Function to get the x coordinate of the rectangle depending on the current column.

Returns: The x coordinate.
Return type: int, float

update_dimensions(style)

Function that updates the rectangle dimensions of the child element that is going to be added to the rectangle of this element.

Parameters: style (dict) – The style dict that contains the margin information needed to calculate the child element rectangle dimensions.

add_top_margin(style)

Function that adds the top margin of the current child element.

Parameters: style (dict) – The style dict that contains the margin information needed to calculate the child element top margin.

parse_element(element)

process(element, last=False)

Function to add a single child element to the rectangle.

This function will add an element to the rectangle, using the method corresponding to the type of the object (text, image, table or another content). Depending on what happens with the element (if it was added or delayed) this return a string with a message for the main loop, or a dict with information to tell the caller function what should be done afterwards.

Parameters

element (dict, str, list, tuple) – The object representing the element to be added.
last (bool) – Wheter or not this is the last child element of the list of child elements of this element.

process_text(element, style, element_style, add_parts=True, add_top_margin=True)

Function that tries to add a paragraph to the current column rectangle, and add the remainder to the delayed list

Parameters

element (dict) – The paragraph to be added
style (dict) – The style of the paragraph, combined with the style of this element.
element_style (dict) – The style of the paragraph.

Returns

Containing instructions to the caller.

Return type

dict

process_image(element, style, add_parts=True, add_top_margin=True)

Function that tries to add an image to the current column rectangle, and add it to the delayed list if it can’t add it.

Parameters

element (dict) – The image to be added
style (dict) – The style of the image.

Returns

Containing instructions to the caller.

Return type

dict

process_table(element, style, element_style, add_parts=True, add_top_margin=True)

Function that tries to add a table to the current column rectangle, and add the remainder to the delayed list.

Parameters

element (dict) – The table to be added.
style (dict) – The style of the table, combined with the style of this element.
element_style (dict) – The style of the table.

Returns

Containing instructions to the caller.

Return type

dict

process_child(element, style, last, add_top_margin=True)

Function that tries to add a child content to the current column rectangle.

Parameters

element (dict) – The child to be added
style (dict) – The style of the child, combined with the style of this element.
last (bool) – whether or not this is the last child of this element.

Returns

Containing instructions to the caller.

Return type

str, dict

get_element_styles(element, inherited_style)

process_group_element(element, inherited_style, add_element=False, add_top_margin=True, min_height=None)

process_group(group_element, style)

Function that tries to add a group element to the current column rectangle, and add it to the delayed list if it can’t add it. If after 50 tries it can not add the group element, it will throw an exception.

Parameters

group_element (dict) – The group element to be added
style (dict) – The style of the group element, combined with the style of this content element.

Returns

Containing instructions to the caller.

Return type

dict