pdfme.pdf

class pdfme.pdf.PDF(page_size='a4', rotate_page=False, margin=56.693, page_numbering_offset=0, page_numbering_style='arabic', font_family='Helvetica', font_size=11, font_color=0.1, text_align='l', line_height=1.1, indent=0, outlines_level=1)

Bases: object

Class that represents a PDF document, and has methods to add pages, and to add paragraphs, images, tables and a mix of this, a content box, to them.

You can use this class to create a PDF file, by adding one page at a time, and adding stuff to each page you add, like this:

from pdfme import PDF

pdf = PDF()
pdf.add_page()
pdf.text('This is a paragraph')

with open('document.pdf', 'wb') as f:
    pdf.output(f)

Through the constructor arguments you can modify the default features of the PDF document, like the size of the pages, their orientation, the page numbering options, and the appearance of the text. These are used everytime you create a new page, or a new paragraph, but you can overwrite these for each case.

You can change the default values for the pages by calling pdfme.pdf.PDF.setup_page(), and change the default values for text by changing attributes font_family, font_size, font_color, text_align and line_height.

Methods pdfme.pdf.PDF.text(), pdfme.pdf.PDF.image(), pdfme.pdf.PDF.table() and pdfme.pdf.PDF.content() are the main functions to add paragraphs, images, tables and content boxes respectively, and all of them, except the image method, take into account the margins of the current page you are working on, and create new pages automatically if the stuff you are adding needs more than one page. If you want to be specific about the position and the size of the paragraphs, tables and content boxes you are inserting, you can use methods pdfme.pdf.PDF._text(), pdfme.pdf.PDF._table() and pdfme.pdf.PDF._content() instead, but these don’t handle the creation of new pages like the first ones.

Each page has attributes x and y that are used to place elements inside them, and for the methods that receive x and y arguments, if they are None, the page’s x and y attributes are used instead.

For more information about paragraphs see pdfme.text.PDFText, and about tables pdfme.table.PDFTable.

Although you can add all of the elements explained so far, we recommend using content boxes only, because all of the additional funcionalities they have, including its ability to embed other elements. For more information about content boxes see pdfme.content.PDFContent.

Paragraphs, tables and content boxes use styles to give format to the content inside of them, and sometimes styling can get repetitive. This is why there’s a dict attribute called formats where you can add named style dicts and used them everywhere inside this document, like this:

from pdfme import PDF

pdf = PDF()
pdf.formats['link'] = {
    'c': 'blue',
    'u': True
}
pdf.add_page()
pdf.text({
    '.': 'this is a link',
    'style': 'link',
    'uri': 'https://some.domain.com'
})

If you find yourself using a piece of text often in the document, you can add it to the dict attribute context and include it in any paragraph in the document by using its key in the dict, like this:

from pdfme import PDF

pdf = PDF()
pdf.context['arln'] = 'A Really Long Name'
pdf.add_page()
pdf.text({
    '.': ['The following name is ', {'var': 'arln'}, '.']
})

There are some special context variables that are used by us that start with symbol $, so it’s adviced to name your own variables without this symbol in the beginning. The only of these variables you should care about is $page that contains the number of the current page.

You can add as much running sections as you want by using pdfme.pdf.PDF.add_running_section(). Running sections are content boxes that are included on every page you create after adding them. Through these you can add a header and a footer to the PDF.

If you want a simpler and more powerful interface, you should use pdfme.document.PDFDocument.

Parameters

  • page_size (str, int, float, tuple, list, optional) – this argument sets the dimensions of the page. See pdfme.utils.get_page_size().

  • rotate_page (bool, optional) – whether the page dimensions should be inverted (True), or not (False).

  • margin (str, int, float, tuple, list, dict, optional) – the margins of the pages. See pdfme.utils.parse_margin().

  • page_numbering_offset (int, float, optional) – if the number of the page is included, this argument will set the offset of the page. For example if the current page is the 4th one, and the offset is 3, the page number displayed in the current page will be 1.

  • page_numbering_style (str, optional) – the style of the page number. Options are arabic (1,2,3,…) and roman (I, II, III, IV, …).

  • font_family (str, optional) – The name of the font family. Options are Helvetica (default), Times, Courier, Symbol and ZapfDingbats. You will also be able to add new fonts in a future release.

  • font_size (in, optional) – The size of the font.

  • font_color (int, float, str, list, tuple, optional) – The color of the font. See pdfme.color.parse_color().

  • text_align (str, optional) – 'l' for left (default), 'c' for center, 'r' for right and 'j' for justified text.

  • line_height (int, float, optional) – space between the lines of the paragraph. See pdfme.text.PDFText.

  • indent (int, float, optional) – space between left of the paragraph, and the beggining of the first line. See pdfme.text.PDFText.

  • outlines_level (int, optional) – the level of the outlines to be displayed on the outlines panel when the PDF document is opened.

property page
Returns

current page

Return type

PDFPage

property page_index
Returns

current page index.

Return type

int

property width
Returns

current page width

Return type

float

property height
Returns

current page height

Return type

float

setup_page(page_size=None, rotate_page=None, margin=None)

Method to set the page features defaults. These values will be used from now on when adding new pages.

Parameters

  • page_size (str, int, float, tuple, list, optional) – this argument sets the dimensions of the page. See pdfme.utils.get_page_size().

  • rotate_page (bool, optional) – whether the page dimensions should be inverted (True), or not (False).

  • margin (str, int, float, tuple, list, dict, optional) – the margins of the pages. See pdfme.utils.parse_margin().

add_page(page_size=None, rotate_page=None, margin=None)

Method to add a new page. If provided, arguments will only apply for the page being added.

Parameters

  • page_size (str, int, float, tuple, list, optional) – this argument sets the dimensions of the page. See pdfme.utils.get_page_size().

  • rotate_page (bool, optional) – whether the page dimensions should be inverted (True), or not (False).

  • margin (str, int, float, tuple, list, dict, optional) – the margins of the page. See pdfme.utils.parse_margin().

add_running_section(content, width, height, x, y)

Method to add running sections, like a header and a footer, to this document.

Running sections are content boxes that are included on every page you create after adding them.

Parameters

  • content (dict) – a content dict like the one you pass to create a instance of pdfme.content.PDFContent.

  • 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.

  • 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.

add_font(fontfile, font_family, mode='n')

Method to add a new font to this document. This functionality is not ready yet.

Parameters

  • fontfile (str) – the path of the fontfile.

  • font_family (str) – the name of the font family being added.

  • mode (str, optional) – the mode of the font being added. It can be n for normal, b for bold and i for italics (oblique).

create_image(image, extension=None, image_name=None)

Method to create a PDF image.

Arguments for this method are the same as pdfme.image.PDFImage.

Returns

object representing the PDF image.

Return type

PDFImage

add_image(pdf_image, x=None, y=None, width=None, height=None, move='bottom')

Method to add a PDF image to the current page.

Parameters

  • pdf_image (PDFImage) – the PDF image.

  • x (int, float, optional) – The x position of the left of the image.

  • y (int, float, optional) – The y position of the top of the image.

  • width (int, float, optional) – The width of the image. If this and height are None, the width will be the same as the page content width, but if this is None and height is not, the width will be calculated from height, keeping the proportion of the image.

  • height (int, float, optional) – The height of the image. If this is None, the height will be calculated from the image width, keeping the proportion.

  • move (str, optional) – wheter it should move page x coordinate to the right side of the image (next) or if it should move page y coordinate to the bottom of the image (bottom) (default).

image(image, extension=None, image_name=None, x=None, y=None, width=None, height=None, move='bottom')

Method to create and add a PDF image to the current page.

Parameters

  • image (str, Path, BytesIO) – see pdfme.image.PDFImage.

  • extension (str, optional) – see pdfme.image.PDFImage.

  • image_name (str, optional) – see pdfme.image.PDFImage.

  • x (int, float, optional) – the x position of the left of the image.

  • y (int, float, optional) – the y position of the top of the image.

  • width (int, float, optional) – the width of the image. If this and height are None, the width will be the same as the page content width, but if this is None and height is not, the width will be calculated from height, keeping the proportion of the image.

  • height (int, float, optional) – the height of the image. If this is None, the height will be calculated from the image width, keeping the proportion.

  • move (str, optional) – wheter it should move page x coordinate to the right side of the image (next) or if it should move page y coordinate to the bottom of the image (bottom) (default).

get_page_number()

Method that returns the string reprensentation of the number of the current page.

Returns

string with the page number that depends on attributes page_numbering_offset and page_numbering_style.

Return type

str

_text(content, width=None, height=None, x=None, y=None, text_align=None, line_height=1.1, indent=0, list_text=None, list_indent=None, list_style=None, move='bottom')

Method to create and add a paragraph to the current page.

If content is a PDFText, the method run for this instance will be called with the new rectangle passed to this function. Else, this method will try to build a new PDFText instance with argument content and call method run afterwards.

For more information about the arguments see pdfme.text.PDFText.

Returns

object that represents the paragraph.

Return type

PDFText

text(content, text_align=None, line_height=1.1, indent=0, list_text=None, list_indent=None, list_style=None)

Method to create and add a paragraph to this document. This method will keep adding pages to the PDF until all the contents of the paragraph are added to the document.

For more information about the arguments see pdfme.text.PDFText.

_table(content, width=None, height=None, x=None, y=None, widths=None, style=None, borders=None, fills=None, move='bottom')

Method to create and add a table to the current page.

If content is a PDFTable, the method run for this instance will be called with the new rectangle passed to this function. Else, this method will try to build a new PDFTable instance with argument content and call method run afterwards.

For more information about this method arguments see pdfme.table.PDFTable.

Returns

object that represents a table.

Return type

PDFTable

table(content, widths=None, style=None, borders=None, fills=None)

Method to create and add a table to this document. This method will keep adding pages to the PDF until all the contents of the table are added to the document.

For more information about this method arguments see pdfme.table.PDFTable.

_content(content, width=None, height=None, x=None, y=None, move='bottom')

Method to create and add a content box to teh current page.

If content is a PDFContent, the method run for this instance will be called with the new rectangle passed to this function. Else, this method will try to build a new PDFContent instance with argument content and call method run afterwards.

For more information about this method arguments see pdfme.content.PDFContent.

Returns

object that represents a content box.

Return type

PDFContent

content(content)

Method to create and add a content box to this document. This method will keep adding pages to the PDF until all the contents are added to the document.

Parameters

content (dict) – see pdfme.content.PDFContent.

output(buffer)

Method to create the PDF file.

Parameters

buffer (file_like) – a file-like object to write the PDF file into.

Raises

Exception – if this document doesn’t have any pages.