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.
- 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 positionindex
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.
- if word in
- 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 ofword
.- 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
- 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 incontent
argument list (or tuple) to the rectangle defined by argsx
,y
,width
andheight
.Each part represents a part of the paragraph with a different style or with a
var
or a specificid
.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 propertyfinished
will be True if all the parts were added, and False if the vertical space ran out. Iffinished
is False, you can set a new rectangle (on a new page for example) and use methodrun
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 propertyfinished
is True.By using method
run
the paragraph is not really added to the PDF object. After callingrun
, the propertyresult
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 propertyresult
to add the paragraph to the PDF object before using methodrun
again (in casefinished
is False), because it will be redefined for the next rectangle after callingrun
again. You can check thetext
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:
'text'
: this is the text that will be displayed with the style defined instyle
key.'style'
: this is a style dict like the one described inpdfme.text.PDFText
.'ids'
: seepdfme.text.PDFText
definition.'var'
: seepdfme.text.PDFText
definition.
- 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 methodpdfme.pdf.PDF._add_text()
, to add this paragraph to that PDF document’s page. Check method_add_parts
frompdfme.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 morecontent
dicts like the one we are describing here (you can have nestedcontent
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 tocontent
, and this dict has astyle
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 methodrun
is called, dict attrresult
is available with information to add the paragraph to the PDF, and within that information you’ll find a keyids
, 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, callrun
, and get the position of it afterwards.'var'
: this is a string with the name of a global variable, previously set in the containingpdfme.pdf.PDF
instance, by adding a new key to its dict attributecontext
. 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 astyle
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. Seepdfme.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. Seepdfme.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 astyle
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
andlist_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.