pdfme.text

class pdfme.text.PDFState(style, fonts)

Bases: object

Class that represents the state of a paragraph line part.

The state is a lower level version of the style, and is used by the other paragraph classes to make calculations and yield the paragraph PDF stream.

Parameters
  • style (dict) – the paragraph line part style.

  • fonts (PDFFonts) – the fonts instance with the information about the fonts already added to the PDF document.

compare(other)

Compares this state, with state other and returns a PDF stream with the differences between both states.

Parameters

other (PDFState) – the state to compare.

Returns

a PDF stream with the differences between both states.

Return type

str

class pdfme.text.PDFTextLinePart(style, fonts, ids=None)

Bases: object

This class represents a part of a paragraph line, with its own style.

Parameters
  • style (dict) – the style of this line part.

  • fonts (PDFFonts) – the fonts instance with the information about the fonts already added to the PDF document.

  • ids (list, optional) – the ids of this part.

pop_word(index=None)

Function to delete the last word of this part if index is None, and the word in the position index if it’s not None.

Parameters

index (int, optional) – word index.

Returns

if word in index could be deleted, the deleted word is

returned, if not None is returned.

Return type

str

add_word(word)

Function to add a word to this part.

Parameters

word (str) – the word.

current_width(factor=1)

Return the width of this part, according to the words added to this part, using factor to calculate this width of the spaces in this part.

Parameters

factor (int, float, optional) – to calculate this width of the spaces in this part.

Returns

width of this part.

Return type

float

tentative_width(word, factor=1)

The same as method current_width, but adding the width of word.

Parameters
  • word (str) – the word that could be added to this part.

  • factor (int, float, optional) – to calculate this width of the spaces in this part.

Returns

the width of this part + the width of the word passed.

Return type

float

get_char_width(char)

The width of the character passed.

Parameters

char (str) – the character string.

Returns

the width of the character passed.

Return type

float

get_word_width(word)

The width of the word passed.

Parameters

char (str) – the word string.

Returns

the width of the word passed.

Return type

float

class pdfme.text.PDFTextLine(fonts, max_width=0, text_align=None, top_margin=0)

Bases: object

Class that represents a line of a paragraph.

This class has the logic to add paragraph parts, and inside them add their words one by one, until all of the horizontal space of the paragraph has been used. For more information about this mechanism check the method pdfme.text.PDFTextLine.add_word().

Parameters
  • fonts (PDFFonts) – to extract information about the fonts being used in the paragraph.

  • max_width (int, float, optional) – the maximum horizontal space that this line can use.

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

  • top_margin (Number, optional) – if not None, this is the top margin of the line, added to the actual line height.

property height

Property that returns the line height, calculated from the vertical space of each part of the line.

Returns

the line height.

Return type

float

property min_width

Property that returns the width of the line, calculated using the minimum value for attribute factor. This attribute is used to increase or decrease the space character width inside a line to

Returns

the line width.

Return type

float

property bottom

Property that returns the line bottom, calculated from the vertical space of each part of the line.

Returns

the line bottom.

Return type

float

get_widths()

This function returns the widths of the line.

Returns

of 2 elements, the width on the words as the first, and the

width of the spaces as the second.

Return type

tuple

add_line_part(style=None, ids=None)

Add a new line part to this line.

Parameters
  • style (dict, optional) – the style of the new part.

  • ids (list, optional) – the ids of the new part.

Returns

The new line part that was added.

Return type

PDFTextLinePart

add_accumulated()

Function to add the parts accumulated in the auxiliar line ( next_line attribute) to this line.

add_word(word)

Function to add a word to this line.

Parameters

word (str) – The word to be added.

Returns

containing a status key, with one of the following values:

  • 'added': The word passed was added to the auxiliar line, or if the word is a space the accumulated words in the auxiliar line, to the current line.

  • 'ignored': The word passed (a space) was ignored.

  • 'preadded': The word passed was added to the auxiliar line.

  • 'finished': The word didn’t fit in the current line, and this means this line is full. Because of this, a new line is created to put this word, and this new line is returned in the key 'new_line'.

Return type

dict

class pdfme.text.PDFTextBase(content, width, height, x=0, y=0, fonts=None, text_align=None, line_height=None, indent=0, list_text=None, list_indent=None, list_style=None, pdf=None)

Bases: object

Class that represents a rich text paragraph to be added to a pdfme.pdf.PDF instance.

You should use pdfme.text.PDFText instead of this class, because it has more functionalities.

To create the data needed to add this paragraph to the PDF document, you have to call the method pdfme.text.PDFTextBase.run(), which will try to add all of the dict parts in content argument list (or tuple) to the rectangle defined by args x, y, width and height.

Each part represents a part of the paragraph with a different style or with a var or a specific id.

The parts 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 parts can not be added. In these two cases method run finishes, and the property finished will be True if all the parts 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 parts that couldn’t be added in the last rectangle. You can keep doing this until all of the parts are added and therefore property finished is True.

By using method run the paragraph is not really added to the PDF object. After calling run, the property result will be available with the information needed to be added to the PDF, at least the parts that fitted inside the rectangle. You have to use the property result to add the paragraph to the PDF object before using method run again (in case finished is False), because it will be redefined for the next rectangle after calling run again. You can check the text method in PDF module to see how this process is done.

The other args not defined here, are explained in pdfme.text.PDFText.

Parameters

content (str, list, tuple) –

If this is a string, it will become the following:

[{'style': <DEFAULT_STYLE>, 'text': <STRING>}]

If this is a list or a tuple, its elements should be dicts with the following keys:

Raises

TypeError – if content is not a str, list or tuple.

property stream

Property that returns the PDF stream generated by the method run, with all of the graphics and the text, ready to be added to a PDF page stream.

Returns

the stream.

Return type

str

property result

Property that returns a dict with the result of calling method run, and can be passed to method pdfme.pdf.PDF._add_text(), to add this paragraph to that PDF document’s page. Check method _add_parts from pdfme.pdf.PDF to see how a dict like the one returned by this method (a paragraph part) is added to a PDF instance.

The dict returned will have the following keys:

  • x the x coordinate.

  • y the y coordinate.

  • width of the paragraph.

  • height of the paragraph.

  • text_stream a string with the paragraphs PDF text stream.

  • graphics_stream a string with the paragraphs PDF graphics stream.

  • used_fonts a set with tuples of 2 elements, first element the font family, and second element the font mode.

  • ids a dict with every id extracted from the paragraph.

Returns

like the one described.

Return type

dict

get_state()

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

Returns

a dict with the state of this paragraph.

Return type

dict

set_state(last_part=None, last_word=None)

Function to update the state of the paragraph

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

Parameters
  • last_part (int) – this is the index of the part that was being processed the last time method run was called.

  • last_word (int) – this is the index of the word of the last part that was added the last time method run was called.

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.

  • last_part (int, optional) – If not None, this is the index of the part that was being processed the last time method run was called.

  • last_word (int, optional) – If not None, this is the index of the word of the last part that was added the last time method run was called.

init()

Function to reset all of the instance properties that have to be resetted before running the arranging process in a new rectangle.

This function is called by method run.

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

Function to create the data needed to add this paragraph to the PDF document.

This function will try to add all of the dict parts in content argument list (or tuple) to this paragraph rectangle. Check this class documentation for more information about this method.

This function args are the same as pdfme.text.PDFTextBase.setup().

Returns

The dict from the property result.

Return type

dict

add_part(part, part_index)

Function used by methodm run to add one paragraph part at a time.

Parameters
  • part (dict) – part to be added.

  • part_index (int) – index of the part to be added.

Returns

whether it was able to add all of the parts (True) or the

vertical space ran out.

Return type

bool

add_current_line(is_last=False)

Function to add the current line to the list of already added lines.

Parameters

is_last (bool, optional) – whether this is the last line of this paragraph (True) or not (False).

Returns

whether this line was successfully added (True) or not (False)

Return type

bool

setup_list()

This function is called when the first part of the paragraph is going to be added, and if this is a list paragraph, i.e. a paragraph with a something on its left (a bullet, a number, etc), this function will setup everything needed to display the text of the list paragraph, and will adjust its width to make space for the list text.

Raises

TypeError – if list_style or list_indent passed to this instance are not a dict and an number respectively.

add_line_to_stream(line, is_last=False)

Function to add a PDFTextLine representing a paragraph line to the already added lines stream.

Parameters
  • line (PDFTextLine) – The line to be added to the stream.

  • is_last (bool, optional) – whether this is the last line of this paragraph (True) or not (False).

clean_words(words)

This function joins a list of words (spaces included) and makes the resulting string compatible with a PDF string.

Parameters

words (list) – a list of strings, where each string is a word.

Returns

A string with all of the words passed.

Return type

str

output_text(part, text, factor=1)

Function that creates a piece of PDF stream (only the text), from the PDFTextLinePart and the text arguments.

Parameters
  • part (PDFTextLinePart) – the part to be transformed into a string representing a PDF stream piece.

  • text ([type]) – the text to be transformed into a string representing a PDF stream piece.

  • factor (Number, optional) – factor of the line needed to create center, right and justified aligned paragraphs.

Returns

representing the PDF stream

Return type

str

output_graphics(part, x, y, part_width)

Function that creates a piece of PDF stream (only the graphics), from the PDFTextLinePart argument.

Parameters
  • part (PDFTextLinePart) – the part to be transformed into a string representing a PDF stream piece.

  • x (int, float) – the x origin coordinate of the graphics being added.

  • y (int, float) – the y origin coordinate of the graphics being added.

  • width (int, float) – the width of the part being added

Returns

representing the PDF stream

Return type

str

class pdfme.text.PDFText(content, width, height, x=0, y=0, fonts=None, text_align=None, line_height=None, indent=0, list_text=None, list_indent=None, list_style=None, pdf=None)

Bases: pdfme.text.PDFTextBase

Class that represents a rich text paragraph to be added to a pdfme.pdf.PDF instance.

content argument should be a dict, with a key starting with a dot, like '.b;s:10;c:1;u' for example (keep reading to learn more about the format of this key), which we are going to refer to as the “the dot key” from here on. The value for the dot key is a list/tuple containing strings or more content dicts like the one we are describing here (you can have nested content dicts or what we call a paragraph part), but for simplicity, you can pass a string (for non-rich text) or a tuple/list with strings and more paragraph parts:

  • If content argument is a string, it will become the following:

    { '.': [ <STRING>, ] }
    
  • If content argument is a list/tuple, it will become the following:

    { '.': <LIST_OR_TUPLE> }
    

This is an example of a content argument:

{
    ".b;u;i;c:1;bg:0.5;f:Courier": [
        "First part of the paragraph ",
        {
            ".b:0;u:0;i:0;c:0;bg:": [
                "and here the second, nested inside the root paragraph,",
            ]
        },
        "and yet one more part before a ",
        {".c:blue;u:1": "url link", "uri": "https://some.url.com"}
    ]
}

This class is a subclass of pdfme.text.PDFTextBase and adds the logic to let the user of this class pass content in a nested cascading “jsonish” format (like HTML), i.e. if you pass a dict to content, and this dict has a style key, all of its children will inherit this style and will be able to overwrite some or all of the style parameters coming from it. The children will be able to pass their own style parameters to their children too, and so on.

Additional to the dot key, paragraph parts can have the following keys:

  • 'label': this is a string with a unique name (there should be only one label with this name in the whole document) representing a destination that can be referenced in other parts of the document. This is suited for titles, figures, tables, etc.

  • 'ref': this is a string with the name of a label, that will become a link to the position of the label referenced.

  • 'uri': this is a string with a reference to a web resource, that will turn this text part in a link to that web page.

  • 'outline': an outline is a label that is shown in the outlines panel of the PDF reader. This outlines show the structure of the document. This attribute is a dict with the following optional keys:

    • level: an optional int with the level of this outline in the outlines tree. The default value is 1.

    • text: an optional string to be shown in the outlines panel for this outline. The default value is the contents of this part.

  • 'ids': when method run is called, dict attr result is available with information to add the paragraph to the PDF, and within that information you’ll find a key ids, a dict with the position and size of the rectangle for each of the ids you include in this argument. This way you can “tag” a part of a paragraph, call run, and get the position of it afterwards.

  • 'var': this is a string with the name of a global variable, previously set in the containing pdfme.pdf.PDF instance, by adding a new key to its dict attribute context. This way you can reuse a repetitive string throughout the PDF document.

Style of the paragraph dicts can be defined in the dot key itself (a string with a semi-colon separeted list of the attributes, explained in pdfme.utils.parse_style_str()) or in a style dict too. The attributes for a paragraph style are the following:

  • 'b' (bool) to make text inside this part bold. Default is False.

  • 'i' (bool) to make text inside this part cursive (italics, oblique). Default is False.

  • 's' (int, float) to set the size of the text inside this part. Default is 11.

  • 'f' (str) to set the font family of the text inside this part. Default is 'Helvetica'.

  • 'u' (bool) to make the text inside this part underlined. Default is False.

  • 'c' (int, float, list, tuple, str) to set the color of the text inside this part. See pdfme.color.parse_color() for information about this attribute. Default is black.

  • 'bg' (int, float, list, tuple, str) to set the background color of the text inside this part. See pdfme.color.parse_color() for information about this attribute. Default is None.

  • 'r' (int, float) to set the baseline of the text, relative to the normal baseline. This is a fraction of the current size of the text, i.e. it will move the baseline the text size times this number in points, upwards if positive, and downwards if negative. Default is 0.

One more example of a content argument with a style dict, and additional keys:

{
    '.': ['text to be displayed'],
    'style': {
        'b': True,
        'i': True,
        'u': True,
        's': 10.2,
        'f': 'Courier',
        'c': 0.9,
        'bg': 'red',
        'r': 0.5
    },
    'label': 'a_important_paragraph',
    'uri': 'https://github.com/aFelipeSP/pdfme'
}

With arguments list_text, list_indent and list_style you can turn a paragraph into a list paragraph, one that has a bullet or a number at the left of the paragraph, with an additional indentation. With this you can build a bulleted or numbered list of paragraphs.

Parameters
  • content (str, list, tuple, dict) – the one just described.

  • width (int, float) – The width of the paragraph.

  • height (int, float) – The height of the paragraph.

  • x (int, float, optional) – The x coordinate of the paragraph.

  • y (int, float, optional) – The y coordinate of the paragraph

  • fonts (PDFFonts, optional) – To extract information about the fonts being used in the paragraph.

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

  • line_height (int, float, optional) – How much space between the lines of the paragraph. This is a fraction of each line’s height, so the real distance between lines can vary depending on the text size of each part of the paragraph.

  • indent (int, float, optional) – The indentation of the first line of the paragraph.

  • list_text (str, optional) – Needed if you want to turn this paragraph into a list paragraph. This text will be displayed before the paragraph and will be aligned with the first line.

  • list_indent (int, float, optional) – Needed if you want to turn this paragraph into a list paragraph. The space between the start of the left side of the rectangle and the left side of the paragraph itself. If omitted, this space will be the width of the list_text.

  • list_style (dict, optional) – Needed if you want to turn this paragraph into a list paragraph. The style of list_text. If omitted, the style of the first part of the first line will be used.

  • pdf (PDF, optional) – To grab global information of the PDF being used.