pdfme.document
- class pdfme.document.PDFDocument(document, context=None)
Bases:
object
Class that helps to build a PDF document from a dict (
document
argument) describing the document contents.This class uses an instance of
pdfme.pdf.PDF
internally to build the PDF document, but adds some functionalities to allow the user to build a PDF document from a JSONish dict, add footnotes and other functions explained here.A document is made up of sections, that can have their own page layout, page numbering, running sections and style.
document
dict can have the following keys:style
: the default style of each section inside the document. A dict with all of the keys that a content box can have (seepdfme.content.PDFContent
for more information about content box, and for the default values of the attributes of this dict seepdfme.pdf.PDF
). Additional to the keys of content box style, you can add the following keys:outlines_level
,page_size
,rotate_page
,margin
,page_numbering_offset
andpage_numbering_style
. For more information about this page attributes and their default values seepdfme.pdf.PDF
definition.formats
: a dict with the global styles of the document that can be used anywhere in the document. For more information about this dict seepdfme.pdf.PDF
definition.running_sections
: a dict with the running sections that will be used by each section in the document. Each section can have, in turn, arunning_section
list, with the name of the running sections defined in this argument that should be included in the section. For information about running sections seepdfme.pdf.PDF
. Ifwidth
key is equal to'left'
, it takes the value of the left margin, if equal to'right'
it takes the value of the right margin, if equal to'full'
it takes the value of the whole page width, and if it is not defined or is None it will take the value of the content width of the page. Ifheight
key is equal to'top'
, it takes the value of the top margin, if equal to'bottom'
it takes the value of the bottom margin, if equal to'full'
it takes the value of the whole page height, and if it is not defined or is None it will take the value the content height of the page. Ifx
key is equal to'left'
, it takes the value of the left margin, if equal to'right'
it takes the value of the whole page width minus the right margin, and if it is not defined or is None it will be 0. Ify
key is equal to'top'
, it takes the value of the top margin, if equal to'bottom'
it takes the value of the whole page height minus the bottom margin, and if it is not defined or is None i will be 0.per_page
: a list of dicts, each with a mandatory keypages
, a comma separated string of indexes or ranges (python style), and any of the following optional keys:style
: a style dict with page related style properties (page_size, rotate_page, margin) that will be applied to every page in thepages
ranges.running_sections
: a dict with optionalexclude
andinclude
lists of running sections names to be included and excluded in every page in thepages
ranges.
sections
: an iterable with the sections of the document.
Each section in
sections
iterable is a dict like the one that can be passed topdfme.content.PDFContent
, so each section ends up being a content box. This class will add as many pages as it is needed to add all the contents of every section (content box) to the PDF document.Additional to the keys from a content box dict, you can include a
running_sections
list with the name of the running sections that you want to be included in all of the pages of the section. There is a special key that you can include in a section’sstyle
dict calledpage_numbering_reset
, that if True, resets the numbering of the pages.You can also include footnotes in any paragraph, by adding a dict with the key
footnote
with the description of the footnote as its value, to the list of elements of the dot key (seepdfme.text.PDFText
for more informarion about the structure of a paragraph and the dot key).Here is an example of a document dict, and how it can be used to build a PDF document using the helper function
pdfme.document.build_pdf()
.from pdfme import build_pdf document = { "style": { "page_size": "letter", "margin": [70, 60], "s": 10, "c": 0.3, "f": "Times", "text_align": "j", "margin_bottom": 10 }, "formats": { "link": {"c": "blue", "u": True}, "title": {"s": 12, "b": True} }, "running_sections": { "header": { "x": "left", "y": 40, "height": "top", "content": ["Document with header"] }, "footer": { "x": "left", "y": "bottom", "height": "bottom", "style": {"text_align": "c"}, "content": [{".": ["Page ", {"var": "$page"}]}] } }, "sections": [ { "running_sections": ["header", "footer"], "style": {"margin": 60}, "content": [ {".": "This is a title", "style": "title"}, {".": [ "Here we include a footnote", {"footnote": "Description of a footnote"}, ". And here we include a ", { ".": "link", "style": "link", "uri": "https://some.url.com" } ]} ] }, { "running_sections": ["footer"], "style": {"rotate_page": True}, "content": [ "This is a rotated page" ] } ] } with open('document.pdf', 'wb') as f: build_pdf(document, f)
- Parameters
document (dict) – a dict like the one just described.
context (dict, optional) – a dict containing the context of the inner
pdfme.pdf.PDF
instance.
- run()
Method to process this document sections.
- output(buffer)
Method to create the PDF file.
- Parameters
buffer (file_like) – a file-like object to write the PDF file into.
- pdfme.document.build_pdf(document, buffer, context=None)
Function to build a PDF document using a PDFDocument instance. This is the easiest way to build a PDF document file in this library. For more information about arguments
document
, andcontext
seepdfme.document.PDFDocument
.- Parameters
buffer (file_like) – a file-like object to write the PDF file into.