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 (see pdfme.content.PDFContent for more information about content box, and for the default values of the attributes of this dict see pdfme.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 and page_numbering_style. For more information about this page attributes and their default values see pdfme.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 see pdfme.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, a running_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 see pdfme.pdf.PDF. If width 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. If height 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. If x 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. If y 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 key pages, 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 the pages ranges.

  • running_sections: a dict with optional exclude and include lists of running sections names to be included and excluded in every page in the pages 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 to pdfme.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’s style dict called page_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 (see pdfme.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, and context see pdfme.document.PDFDocument.

Parameters

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