aspecd.report module

General facilities for generating reports.

To do scientific research in terms of reproducibility and traceability it’s highly necessary to report all the steps done on a given dataset and never separate the dataset from its metadata. However, having a dataset containing all these metadata is only useful if there are easy ways to retrieve and present the information stored. This is the task of reports.

This module provides functionality to create reports based on templates provided either by the user or by the package as such.

The report functionality relies heavily on the Jinja2 template engine . Therefore, it is very useful to be generally familiar with the concepts of Jinja2. Basically, this template engine allows users to specify rather complicated replacements and logic within the template. However, logic within templates should be used sparingly, and the template should always be rendered correctly even without processing it by the template engine. Only then templates are easy to develop and adapt.

Two concepts used by Jinja2 the user of the report facilities of the ASpecD framework should be familiar with are “environment” and “context”. The former is a list of settings determining the type of delimiters used within a certein template for the control structures that are understood by Jinja2. As Jinja2 is developed with web applications (and hence HTML) in mind, those delimiters may not be feasible for other types of languages a template may be written in, such as LaTeX. Currently, the aspecd.report module of the ASpecD framework provides a generic environment as well as a dedicated LaTeX environment, implemented as respective classes:

These two environments get automatically loaded by the respective reporter classes:

The second important concept of Jinja2 is that of the “context”: Think of it as a dictionary containing all the key–value pairs you can use to replace placeholders within a template with their actual values. In the simplest of all cases within the context of the ASpecD framework, this could be the metadata of an aspecd.dataset.Dataset.

exception aspecd.report.Error

Bases: Exception

Base class for exceptions in this module.

exception aspecd.report.MissingFilenameError(message='')

Bases: aspecd.report.Error

Exception raised when no filename is provided

message

explanation of the error

Type

str

exception aspecd.report.LaTeXExecutableNotFoundError(message='')

Bases: aspecd.report.Error

Exception raised when the LaTeX executable could not be found

message

explanation of the error

Type

str

class aspecd.report.Reporter(template='', filename='')

Bases: object

Base class for reports.

To generate a report from a template, you will need a template in the first place. The path to the template (including its filename) is set in the template attribute that is either provided as parameter at initialisation or assigned later on. Similarly, you should specify an output filename, stored in the filename attribute. The variables known to the template that should be replaced by appropriate content, termed “context” in Jinja2 language, are stored in the context attribute. This is, by default, an ordered dict to preserve the order of the keys it contains. This is sometimes very useful.

Next, you want to render the template, and most often, save it to a file afterwards. If you would like to separate those steps, you can call the render() and save() methods separately. For convenience, simply call create() to render the report and save it to the file whose name you have provided.

The whole procedure may look as follows:

template = "/path/to/my/template.tex"
filename = "/path/to/my/final/report.tex"
report_ = aspecd.report.Reporter(template=template, filename=filename)
report_.create()
template

Template file used to generate report.

Type

str

filename

Name of the resulting template file.

Type

str

context

Variables of a template that are replaced with the given content.

context contains a key “sysinfo” containing system-related information, i.e. the information contained in the aspecd.system.SystemInfo class.

Type

collections.OrderedDict

environment

Jinja2 environment used for rendering the template.

Defaults to a aspecd.report.GenericEnvironment object with settings for rendering generic templates.

Type

aspecd.report.GenericEnvironment

report

Actual report, i.e. rendered template

Type

str

Parameters
  • template (str) – Path to template file used to generate report.

  • filename (str) – Path to the output file the report should be rendered to.

Raises
  • aspecd.report.FileNotFoundError – Raised if the template file provided does not exist.

  • aspecd.report.MissingFilenameError – Raised if no output file for the report is provided.

render()

Render the template.

The actual rendering of the template should be implemented within the non-public method _render().

Before calling the non-public method _render(), the renderer checks the existence of the file provided as attribute template as well as whether an output filename has been provided. If this is not the case, a corresponding exception will be raised.

Raises

FileNotFoundError – Raised if the template file provided does not exist.

save()

Save report to file.

Raises

aspecd.report.MissingFilenameError – Raised if no output file for the report is provided.

create()

Create report, thus rendering template and saving result to file.

Convenience method to render the template and save the generated report to a file, thus simply calling render() and save() subsequently.

class aspecd.report.LaTeXReporter(template='', filename='')

Bases: aspecd.report.Reporter

LaTeX Reporter.

Often, templates for reports are written in LaTeX, and the results typeset as PDF file upon a (pdf)LaTeX run. For convenience, this class offers the necessary facilities to compile the template once written.

The whole procedure may look as follows:

template = "template.tex"
filename = "report.tex"
report_ = aspecd.report.LaTeXReporter(template=template,
                                      filename=filename)
report_.create()
report_.compile()

This will result with a file “report.pdf” in the current directory. If you specify a relative or absolute path for the filename of the report, the resulting PDF file will be copied to that path accordingly.

Note that for compiling a temporary directory is used, such as not to clutter the current working directory with all the auxiliary files usually created during a (pdf)LaTeX run. Furthermore, currently, only a single (pdf)LaTeX run is performed with option “-interaction=nonstopmode” passed in order to not block further execution.

Note

Due to problems with LaTeX rendering text containing underscores, the keys in the context dict are recursively parsed and each key containing underscores converted to camel case (but preserving the case of the first character: “foo_bar” => “fooBar”). Thus, the template can be compiled using LaTeX without having to replace the placeholder variables beforehand.

environment

Jinja2 environment used for rendering the template.

Defaults to a aspecd.report.LaTeXEnvironment object with settings for rendering LaTeX templates.

Type

aspecd.report.LaTeXEnvironment

includes

List of files that need to be present for compiling the template.

These files will be copied into the temporary directory used for compiling the template.

Type

list

latex_executable

Name of/path to the LaTeX executable.

Defaults to “pdflatex”

Type

str

Parameters
  • template (str) – Path to template file used to generate report.

  • filename (str) – Path to the output file the report should be rendered to.

Raises

aspecd.report.LaTeXExecutableNotFoundError – Raised if the LaTeX executable could not be found

compile()

Compile LaTeX template.

The template is copied to a temporary directory and the LaTeX executable specified in latex_executable called on the report. Afterwards, the result is copied back to the original directory.

Additionally, all files necessary to compile the report are copied to the temporary directory as well.

Raises

aspecd.report.LaTeXExecutableNotFoundError – Raised if the LaTeX executable could not be found

class aspecd.report.GenericEnvironment

Bases: jinja2.environment.Environment

Jinja2 environment for rendering generic templates.

Todo

Describe the settings in more detail, thus providing users of this class and in turn the aspecd.report.Reporter class with ideas of how to create their templates.

class aspecd.report.LaTeXEnvironment

Bases: jinja2.environment.Environment

Jinja2 environment for rendering LaTeX-based templates.

This environment is designed for using templates written in LaTeX that can be rendered by LaTeX without having their control code replaced by Jinja2. While variables are usually output in LaTeX, control structures are prefixed by a LaTeX comment character (%). For convenience, the following table lists all the variables currently set within this environment.

Variable

Value

block_start_string

%{

block_end_string

}%

variable_start_string

{@

variable_end_string

}

comment_start_string

%#{

comment_end_string

}

line_statement_prefix

%%

line_comment_prefix

%#

trim_blocks

True

autoescape

False

While every measure is taken to keep the above information as accurate as possible, for authoritative information the reader is referred to the actual source code.