reportcompiler.documentcompilers

documentcompilers.py

This module is responsible for the compilation of the document specifications (DocumentCompiler) and its fragments (FragmentCompiler).

Classes

  • DocumentCompiler: Class responsible for compiling a document specification into an
  • FragmentCompiler: Class responsible for compiling a fragment within a document
class reportcompiler.documentcompilers.DocumentCompiler(_doc_spec)

Class responsible for compiling a document specification into an actual document

Inheritance

Inheritance diagram of DocumentCompiler
static augment_doc_param(doc_param, metadata)

Stage to augment the document variable with necessary additional data for the document generation.

Parameters:
  • doc_param (OrderedDict) – Document variable
  • metadata (dict) – Metadata
Returns:

Document variable “augmented” with the specified additional data
Return type:

dict
static fetch_allowed_param_values(doc_param, metadata)

Fetches the information about the allowed document variables.

Parameters:
  • doc_param (OrderedDict) – Document variable
  • metadata (dict) – Document metadata
Returns:

Dictionary with the allowed values for mandatory variables.
Return type:

dict
static fetch_style_data(metadata)

Fetches the information about the aesthetic settings for the document.

Parameters:metadata (dict) – Document metadata
Returns:Dictionary with styling settings.
Return type:dict
generate(doc_params, doc_metadata, n_doc_workers=2, n_frag_workers=2, debug=False, random_seed=0, fragments=None, log_level=10)

Generates documents from a list of document variables.

Parameters:
  • doc_params (dict) – List of document variables, where each document variable is a dictionary with variables associated with a document.
  • doc_metadata (dict) – Document metadata
  • n_doc_workers (int) – Number of concurrent document-generating threads.
  • n_frag_workers (int) – Number of concurrent fragment-generating threads. The total thread count will be n_doc_workers * n_frag_workers.
  • debug (boolean) – If enabled, the document generation will be limited to one thread and several measures will be taken to facilitate debugging.
  • random_seed (int) – Seed to initialize any possible pseudorandom generators.
  • fragments (str) – Fragment(s) to be generated. Setting this value generates the document only considering the templates from the main template to the chosen value(s) and all its children. Setting it to None is equivalent to setting it to the main template and therefore the whole document will be generated.
  • log_level (int) – Log level
generate_fragments_mapping()

Generates (and validates) the mapping between each template and its corresponding source code file.

Returns:Template/source code file mapping
Return type:dict
generate_template_tree()

Scans the template directory and creates a template dependency tree (i.e. templates, subtemplates, …).

Returns:Template dependency tree
Return type:anytree.Tree
static get_doc_param_suffix(doc_param)

Generates a unique suffix given a particular document variable.

Parameters:doc_param (OrderedDict) – Document variable
Returns:String with a representation of the document variable, to be used as a filename suffix
Return type:str
included_templates(content)

Returns the number of child templates included in content, according to the document specification template renderer engine.

Parameters:content (str) – String content of the parent template
Returns:List of child templates included in content
Return type:list
static postprocess(doc, doc_param, context)

Performs the postprocessing stages for the document (see architecture). Multiple stages can be defined.

Parameters:
  • doc (object) – Document content, output from the template rendering stage
  • doc_param (OrderedDict) – Document variable
  • context (dict) – Full context with two keys: ‘data’ for context generation output and ‘meta’ for document metadata
static render_template(doc_param, template_tree, context)

Performs the template rendering stage for the document (see architecture).

Parameters:
  • doc_param (OrderedDict) – Document variable
  • template_tree (anytree) – Tree with the templates to be rendered.
  • context (dict) – Full context with two keys: ‘data’ for context generation output and ‘meta’ for document metadata
Returns:

Template rendering engine output, generally the rendered template
Return type:

object
static setup_environment(metadata, doc_param)

Prepares the environment to generate the necessary files (e.g. output, temp, logs, hashes, figures, …) and variables.

Parameters:
  • metadata (dict) – Document metadata
  • doc_param (OrderedDict) – Document variable
static setup_logger(doc_metadata, log_level)

Initializes and sets up the logger.

Parameters:
  • doc_metadata (dict) – Document metadata
  • log_level (int) – Log level
static shutdown_loggers()

Shutdowns the logger and its handlers.

static update_nested_dict(doc_context, fragment, frag_context)

Updates a dictionary recursively, forming a nested structure according to the template tree structure.

Parameters:
  • doc_context (dict) – Context/dictionary to be updated
  • fragment (str) – Path of the new fragment from the template root, used as the new key path
  • frag_context (dict) – Dictionary to be inserted in doc_context
Returns:

Updated document context
Return type:

dict
class reportcompiler.documentcompilers.FragmentCompiler

Class responsible for compiling a fragment within a document

Inheritance

Inheritance diagram of FragmentCompiler
static compile(fragment, doc_param, doc_metadata, multiprocessing=True, log_level=20)

Compiles a fragment within a document with the given document variables.

Parameters:
  • fragment (str) – Fragment path from template root
  • doc_param (OrderedDict) – Document variable
  • doc_metadata (dict) – Document metadata
  • multiprocessing (bool) – Boolean, set to True when using multiprocessing
  • log_level (int) – Log level
Returns:

Context of the specified fragment, to be used in the template rendering stage
Return type:

dict
static fetch_data(doc_param, metadata)

Stage to fetch the data to be used in the context generation stage (see architecture).

Parameters:
  • doc_param (OrderedDict) – Document variable
  • metadata (dict) – Metadata (document metadata, overriden by fragment)
Returns:

Pandas dataframe (or list of dataframes) with required data
Return type:

pandas.DataFrame
static fetch_info(doc_param, fetcher_key, metadata)

Fetches data according to fetcher_key.

Parameters:
  • doc_param (OrderedDict) – Document variable
  • fetcher_key (str) – Key identifying the fetcher within the metadata. A slash (‘/’) represents a nested dictionary path: e.g. ‘a/b’ means metadata[‘a’][‘b’].
  • metadata (dict) – Metadata (document metadata, overriden by fragment)
Returns:

Pandas dataframe (or list of dataframes) with required data
Return type:

pandas.DataFrame
static generate_context(fragment_data, doc_param, metadata)

Stage to generate dictionary to be used as context for template rendering stage.

Parameters:
  • fragment_data (pandas.DataFrame) – Pandas dataframe (or list of dataframes) with the current fragment’s data
  • doc_param (OrderedDict) – Document variable
  • metadata (dict) – Metadata (document metadata, overriden by fragment)
Returns:

Dictionary with the context of the current fragment, to be used in the template rendering stage
Return type:

dict
static retrieve_fragment_metadata(doc_param, metadata)

Stage to extract metadata from within the fragment’s source code (see architecture).

Parameters:
  • doc_param (OrderedDict) – Document variable
  • metadata (dict) – Document metadata
Returns:

Fragment metadata dictionary
Return type:

dict
static setup_logger(fragment_name, doc_metadata, log_level)

Initializes and sets up the logger.

Parameters:
  • fragment_name (str) – Name of the current fragment
  • doc_metadata (dict) – Document metadata
  • log_level (int) – Log level