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 attributesfont_family
,font_size
,font_color
,text_align
andline_height
.Methods
pdfme.pdf.PDF.text()
,pdfme.pdf.PDF.image()
,pdfme.pdf.PDF.table()
andpdfme.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 methodspdfme.pdf.PDF._text()
,pdfme.pdf.PDF._table()
andpdfme.pdf.PDF._content()
instead, but these don’t handle the creation of new pages like the first ones.Each page has attributes
x
andy
that are used to place elements inside them, and for the methods that receivex
andy
arguments, if they are None, the page’sx
andy
attributes are used instead.For more information about paragraphs see
pdfme.text.PDFText
, and about tablespdfme.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,…) androman
(I, II, III, IV, …).font_family (str, optional) – The name of the font family. Options are
Helvetica
(default),Times
,Courier
,Symbol
andZapfDingbats
. 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_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 andi
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
- 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 andheight
is not, the width will be calculated fromheight
, 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 andheight
is not, the width will be calculated fromheight
, 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
andpage_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 methodrun
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 argumentcontent
and call methodrun
afterwards.For more information about the arguments see
pdfme.text.PDFText
.- Returns
object that represents the paragraph.
- Return type
- 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 methodrun
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 argumentcontent
and call methodrun
afterwards.For more information about this method arguments see
pdfme.table.PDFTable
.- Returns
object that represents a table.
- Return type
- 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 methodrun
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 argumentcontent
and call methodrun
afterwards.For more information about this method arguments see
pdfme.content.PDFContent
.- Returns
object that represents a content box.
- Return type
- 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.