Source code documentation¶
Templating¶
-
class
py3o.template.main.
Template
(template, outfile, ignore_undefined_variables=False, escape_false=False)¶ The default template to be used to output ODF content.
-
apply_variable_type_in_cells
(content_trees, namespaces)¶ Replace default ‘string’ type by a function call.
-
static
convert_py3o_to_python_ast
(expressions)¶ Convert py3o expressions to parsable Python code.
The py3o expressions can be extracted from a Template object using the
get_all_user_python_expression()
method. The result can then be parsed byPy3oConvertor
in order to obtain the data structure expected by the template.Parameters: expressions (list) – A list of strings that represent expressions in the template. Returns: The expressions in the form of Python code that can be parsed by AST. Return type: str
-
static
find_image_frames
(content_trees, namespaces)¶ find all frames that must be converted to images
-
get_all_user_python_expression
()¶ Public method to get all python expression
-
get_user_instructions
()¶ Public method to help report engine to find all instructions This method will be removed in a future version. Please use
Py3oTemplate.get_all_user_python_expression()
.
-
get_user_variables
()¶ a public method to help report engines to introspect a template and find what data it needs and how it will be used returns a list of user variable names without the leading ‘py3o.’ This method will be removed in a future version. Please use
Py3oTemplate.get_all_user_python_expression()
.
-
handle_draw_frame
(frame, py3o_base)¶ remove a draw:frame content and inject a draw:image with py:attrs=”__py3o_image(image_name)” this __py3o_image method will be injected inside the template dictionary to be called back from inside the template
-
handle_link
(link, py3o_base, closing_link)¶ transform a py3o link into a proper Genshi statement rebase a py3o link at a proper place in the tree to be ready for Genshi replacement
-
render
(data)¶ render the OpenDocument with the user data
@param data: the input stream of userdata. This should be a dictionary mapping, keys being the values accessible to your report. @type data: dictionary
-
render_flow
(data)¶ render the OpenDocument with the user data
@param data: the input stream of user data. This should be a dictionary mapping, keys being the values accessible to your report. @type data: dictionary
-
render_tree
(data)¶ prepare the flows without saving to file this method has been decoupled from render_flow to allow better unit testing
-
set_image_data
(identifier, data, mime_type=None)¶ Set data for an image mentioned in the template.
@param identifier: Identifier of the image; refer to the image in the template by setting “py3o.staticimage.[identifier]” as the name of that image. @type identifier: string
@param data: Contents of the image. @type data: binary
-
set_image_path
(identifier, path)¶ Set data for an image mentioned in the template.
@param identifier: Identifier of the image; refer to the image in the template by setting “py3o.[identifier]” as the name of that image. @type identifier: string
@param path: Image path on the file system @type path: string
-
static
validate_link
(link, py3o_base)¶ this method will ensure a link is valid or raise a TemplateException
Parameters: link (lxml.Element) – a link node found in the tree Returns: nothing Raises: TemplateException
-
-
exception
py3o.template.main.
TemplateException
(message)¶ some client code is used to catching ValueErrors, let’s keep the old codebase happy
-
class
py3o.template.main.
TextTemplate
(template, outfile, encoding='utf-8', ignore_undefined_variables=False)¶ A specific template that can be used to output textual content.
It works as the ODT or ODS templates, minus the fact that is does not support images.
-
render
(data)¶ Render the template with the provided data.
Parameters: data – a dictionnary containing your data (preferably a iterators) :return: Nothing
-
-
py3o.template.main.
detect_keep_boundary
(start, end, namespaces)¶ a helper to inspect a link and see if we should keep the link boundary
-
py3o.template.main.
format_amount
(amount, format='%f')¶ Replace the thousands separator from ‘.’ to ‘,’
-
py3o.template.main.
format_currency
(*args, **kwargs)¶ Format the specified amount according to a format string & a currency.
Relies on babel.numbers.format_currency.
Online docs: * <http://babel.pocoo.org/en/latest/numbers.html#pattern-syntax> * <http://babel.pocoo.org/en/latest/api/numbers.html
#babel.numbers.format_currency>Changes we provide here: * Make the 2nd argument (currency) optional. When not displaying the
currency symbol, no need to provide a currency.Their parameter docstring has been copied below.
Parameters: - number – the number to format
- currency – the currency code, optional unless displaying the currency
- format – the format string to use
- locale – locale identifier
- currency_digits – use the currency’s natural number of decimal digits
- format_type – the currency format type to use
- decimal_quantization – Truncate and round high-precision numbers to
the format pattern. Defaults to
True
.
Return type: String.
-
py3o.template.main.
format_date
(date, format='%Y-%m-%d')¶ Format the date according to format string.
Parameters: date – One of: datetime.date object, datetime.datetime object, ISO formatted string (‘%Y-%m-%d’ or ‘%Y-%m-%d %H:%M:%S’).
-
py3o.template.main.
format_datetime
(date_obj, format=None, locale=None)¶ Format the specified date / date-time according to a format string.
Parameters: date – One of: datetime.date object, datetime.datetime object, ISO formatted string (‘%Y-%m-%d’ or ‘%Y-%m-%d %H:%M:%S’).
Parameters: format – How the date should be formatted. We use babel to format; see <http://babel.pocoo.org/en/latest/dates.html#pattern-syntax>. Optional; when left as is, the default format is: * ‘YYYY-MM-dd’ for datetime.date objects. * ‘YYYY-MM-dd HH:mm:ss’ for datetime.datetime objects. :type format: String.
Parameters: locale (String.) – Locale identifier used during babel formatting. Optional. Return type: String.
-
py3o.template.main.
format_locale
(amount, format_, locale_, grouping=True)¶ format the given amount using the format and a locale example: format_locale(10000.33, “%.02f”, “fr_FR.UTF-8”) will give you: “10 000,33”
-
py3o.template.main.
format_multiline
(value)¶ Allow line breaks in input data with a format function. Escape and replace code originally by tonthon tonthon.
-
py3o.template.main.
get_all_python_expression
(content_trees, namespaces)¶ Return all the python expressions found in the whole document
-
py3o.template.main.
get_image_frames
(content_tree, namespaces)¶ find all draw frames that must be converted to draw:image
-
py3o.template.main.
get_instructions
(content_tree, namespaces)¶ find all text links that have a py3o
-
py3o.template.main.
get_list_transformer
(namespaces)¶ - this function returns a transformer to
- find all list elements and recompute their xml:id.
Because if we duplicate lists we create invalid XML. Each list must have its own xml:id
- This is important if you want to be able to reopen the produced
- document wih an XML parser. LibreOffice will fix those ids itself silently, but lxml.etree.parse will bork on such duplicated lists
-
py3o.template.main.
get_var_corresponding_ods_type
(var)¶ Check variable type and return the corresponding ODS value.
-
py3o.template.main.
move_siblings
(start, end, new_, keep_start_boundary=False, keep_end_boundary=False)¶ a helper function that will replace a start/end node pair by a new containing element, effectively moving all in-between siblings This is particularly helpful to replace for /for loops in tables with the content resulting from the iteration
This function call returns None. The parent xml tree is modified in place
@param start: the starting xml node @type start: lxml.etree.Element
@param end: the ending xml node @type end: lxml.etree.Element
@param new_: the new xml element that will replace the start/end pair @type new_: lxlm.etree.Element
@param keep_start_boundary: Flag to let the function know if it copies your start tag to the new_ node or not, Default value is False @type keep_start_boundary: bool
@param keep_end_boundary: Flag to let the function know if it copies your end tag to the new_ node or not, Default value is False @type keep_end_boundary: bool
@returns: None @raises: ValueError
Data extraction¶
AST Conversion¶
-
class
py3o.template.helpers.
Py3oConvertor
¶ Provide the data extraction functionality.
-
bind_target
(iterable, target, context, iterated=True)¶ Helper function to the For node. This function fill the context according to the iterable and
target and return a new_context to pass through the for body- The new context should contain the for loop declared variable
- as main key so our children can update their content without knowing where they come from.
- Example:
python_code = ‘for i in list’ context = {
‘i’: Py3oArray({}), ‘__py3o_module__’: Py3oModule({‘list’: Py3oArray({})}),}
In the above example, the two Py3oArray are the same instance. So if we later modify the context[‘i’] Py3oArray,
we also modify the context[‘__py3o_module__][‘list’] one.
-
static
set_last_item
(py3o_obj, inst)¶ - Helper function that take a Py3oObject and set the first leaf found
- with inst.
This should not be called with a leaf directly.
-
visit
(node, local_context=None)¶ Call the node-class specific visit function, and propagate the context
-
visit_attribute
(node, local_context)¶ Visit our children and return a Py3oDummy equivalent Example:
- i.egg.foo -> Py3oDummy({
- ‘i’: Py3oName({
- ‘egg’: Py3oName({‘foo’: Py3oName()})
}
}
-
visit_call
(node, local_context)¶ Visit a function call.
-
visit_expr
(node, local_context)¶ - An Expr is the way to express the will of printing a variable
- in a Py3oTemplate. So here we must update the context to map all attribute access.
We only handle attribute access and simple name (i.foo or i)
-
visit_for
(node, local_context)¶ Update the context so our chidren have access to the newly declared variable.
-
visit_module
(node, local_context)¶ The main node, should be alone. Here we initialize the context and loop for all our children
-
visit_name
(node, local_context)¶ Simply return Py3oDummy equivalent
-
visit_str
(node, local_context)¶ Do nothing
-
Data structure¶
This file contains all the data structures used by Py3oConvertor See the docstring of Py3oConvertor.__call__() for further information
-
class
py3o.template.data_struct.
Py3oArray
¶ A class representing an iterable value in the data structure. The attribute direct_access will tell if this class should be considered
as a list of dict or a list of values.-
render
(data)¶ This function will render the datastruct according to the user’s data
-
-
class
py3o.template.data_struct.
Py3oBuiltin
¶ This class holds information about builtins
-
classmethod
from_name
(name=None)¶ Return the Py3oObject subclass for the given built-in name Return None if the name does not correspond to a builtin.
Parameters: name – A Py3oObject instance that represent a name/attribute path Returns: A Py3oObject subclass or None
-
classmethod
-
class
py3o.template.data_struct.
Py3oCall
(name, dict)¶ This class holds information of function call. ‘name’ holds the name of function as a Py3oName The keys are the arguments as:
- numeric keys are positional arguments ordered ascendently
- string keys are keywords arguments
-
class
py3o.template.data_struct.
Py3oContainer
(values)¶ Represent a container defined in the template. This container can be: _ A literal list, tuple, set or dict definition _ A tuple of variables that are the target of an unpack assignment
-
get_tuple
()¶ Return the container’s values in a tuple
-
-
class
py3o.template.data_struct.
Py3oDummy
¶ This class holds temporary dict, or unused attribute such as counters from enumerate()
-
class
py3o.template.data_struct.
Py3oEnumerate
(name, dict)¶ Represent an enumerate call
-
class
py3o.template.data_struct.
Py3oName
¶ This class holds information of variables. Keys are attributes and values the type of this attribute
(another Py3o class or a simple value)i.e.: i.egg -> Py3oName({‘i’: Py3oName({‘egg’: Py3oName({})})})
-
render
(data)¶ This function will render the datastruct according to the user’s data
-
-
class
py3o.template.data_struct.
Py3oObject
¶ Base class to be inherited.
-
get_key
()¶ Return the first key
-
get_size
()¶ Return the max depth of the object
-
get_tuple
()¶ Return the value of the Py3oObject as a tuple. As a default behavior, the object returns None.
-
rget
(other)¶ Get the value for the path described by the other Py3oObject.
Recursively checks that the values in other can be found in self.
The method returns the values of self and other at the point where the search stopped. If other is a leaf, the search stops sucessfully. The method returns True, the value that corresponds to the path described by other, and the leaf in question. If other cannot be found in self, the search stops unsuccessfully. The method returns False, the value that corresponds to the deepest point reached in self, and the rest of the path.
Example: self = Py3oObject({
‘a’: Py3oObject({}), ‘b’: Py3oObject({
‘c’: Py3oObject({}),}),
}) other = Py3oObject({
- ‘b’: Py3oObject({
- ‘d’: Py3oObject({}),
}),
}) res = (
False, Py3oObject({‘c’: Py3oObject({})}), # is self[‘b’] Py3oObject({‘d’: Py3oObject({})}), # is other[‘b’]) if other[‘b’] was a leaf, res[0] would be True and res[2] the leaf.
Returns: A triple: - True if the search was successful, False otherwise - The active sub-element of self when the search stopped - The active sub-element of other when the search stopped
-
rupdate
(other)¶ Update recursively the Py3oObject self with the Py3oObject other. Example: self = Py3oObject({
‘a’: Py3oObject({}), ‘b’: Py3oObject({
‘c’: Py3oObject({}),}),
}) other = Py3oObject({
- ‘b’: Py3oObject({
- ‘d’: Py3oObject({}),
}),
}) res = Py3oObject({
‘a’: Py3oObject({}), ‘b’: Py3oObject({
‘c’: Py3oObject({}), ‘d’: Py3oObject({}),}),
})
-