Output

Output:

HistToCSV(**kwargs)	Deprecated.
PDFToPNG([format, timeoutsec])	Convert PDF to image format (by default PNG).
ToCSV([separator, header, duplicate_last_bin])	Convert data to CSV text.
Writer([output_directory, output_filename])	Write text data to filesystem.

LaTeX utilities:

LaTeXToPDF([verbose, create_command])	Run pdflatex binary for LaTeX files.
RenderLaTeX([select_template, …])	Create LaTeX from templates and data.

Make filename:

format_context(format_str, *args, **kwargs)	Create a function, which formats a given string using a context.
MakeFilename(*args, **kwargs)	Make file names for data from the flow.

Output

class PDFToPNG(format='png', timeoutsec=60)

Convert PDF to image format (by default PNG).

Initialize output format.

timeoutsec is time (in seconds) for subprocess timeout (used only in Python 3). If the timeout expires, the child process will be killed and waited for. The TimeoutExpired exception will be re-raised after the child process has terminated.

This class uses pdftoppm binary internally. Pdftoppm can be given other output formats as an option (see man pdftoppm), for example jpeg or tiff.

run(flow)

Convert PDF files to format.

PDF files are recognized via context.output.filetype. Their paths are assumed to be data part of the value (may contain trailing “.pdf”).

Data yielded is the resulting file name. Context is updated with filetype = format.

Other values are passed unchanged.

class Writer(output_directory='', output_filename='output')

Write text data to filesystem.

output_directory is the base output directory. It can be further appended by the incoming data. Non-existing directories are created.

output_filename is the name for unnamed data. Use it to write only one file.

If no arguments are given, the default is to write to “output.txt” in the current directory (rewritten for every new value) (unless different extensions are provided through the context). It is recommended to create filename explicitly using MakeFilename. The default writer’s output file can be useful in case of errors, when explicit file name didn’t work.

run(flow)

Write incoming data to file system.

Only strings (and unicode in Python 2) are written. To be written, data must have “output” dictionary in context and context[“output”][“writer”] not set to False. Other values pass unchanged.

Full name of the file to be written (filepath) has the form self.output_directory/dirname/filename.fileext, where dirname, filename and file extension are searched in context[“output”]. If filename is missing, Writer’s default filename is used. If fileext is missing, then filetype is used; if it is also absent, the default file extension is “txt”. It is recommended to provide only fileext in context, unless it differs with filetype.

File name with full path is yielded as data. Context.output is updated with fileext and filename (in case they were not present), and filepath, where filename is its base part (without output directory and extension) and filepath is the complete path.

If context.output.filename is present, but empty, LenaRuntimeError is raised.

class ToCSV(separator=', ', header=None, duplicate_last_bin=True)

Convert data to CSV text.

These objects are converted:

• Histogram (implemented only for 1- and 2-dimensional histograms).
• any object (including Graph) with to_csv method.

separator delimits values in the output text,

header is a string which becomes the first line of the output,

If duplicate_last_bin is True, contents of the last bin will be written in the end twice. This may be useful for graphical representation: if last bin is from 9 to 10, then the plot may end on 9, while this parameter allows to write bin content at 10, creating the last horizontal step.

run(flow)

Convert values from flow to CSV text.

Context.output is updated with {“filetype”: “csv”}. All not converted data is yielded unchanged.

If data has to_csv method, it must accept keyword arguments separator and header and return text.

If context.output.to_csv is False, the value is skipped.

Data is yielded as a whole CSV block. To generate CSV line by line, use hist1d_to_csv() and hist2d_to_csv().

hist1d_to_csv(hist, header=None, separator=', ', duplicate_last_bin=True)

Yield CSV-formatted strings for a one-dimensional histogram.

hist2d_to_csv(hist, header=None, separator=', ', duplicate_last_bin=True)

Yield CSV-formatted strings for a two-dimensional histogram.

class HistToCSV(**kwargs)

Deprecated. Use ToCSV instead.

LaTeX

class LaTeXToPDF(verbose=1, create_command=None)

Run pdflatex binary for LaTeX files.

It runs in parallel (separate process is spawned for each job) and non-interactively.

Initialize object.

verbose = 0 means no output messages. 1 prints pdflatex error messages. More than 1 prints pdflatex stdout.

If you need to run pdflatex (or other executable) with different parameters, provide its command.

create_command is a function which accepts texfile_name, outfilename, output_directory, context (in this order) and returns a list made of the command and its arguments.

Default command is:

[“pdflatex”, “-halt-on-error”, “-interaction”, “batchmode”,

“-output-directory”, output_directory, texfile_name]

run(flow)

Convert all incoming LaTeX files to pdf.

class RenderLaTeX(select_template='', template_path='.', select_data=None)

Create LaTeX from templates and data.

select_template is a string or a callable. If a string, it is the name of the template to be used (unless context.output.template overwrites that). If select_template is a callable, it must accept a value from the flow and return template name. If select_template is an empty string (default) and no template could be found in the context, LenaRuntimeError is raised.

template_path is the path for templates (used in jinja2.FileSystemLoader). By default, it is the current directory.

select_data is a callable to choose data to be rendered. It should accept a value from flow and return boolean. If it is not provided, by default CSV files are selected.

run(flow)

Render values from flow to LaTeX.

If no select_data was initialized, values with context.output.filetype equal to “csv” are selected by default.

Rendered LaTeX text is yielded in the data part of the tuple (no write to filesystem occurs). context.output.filetype updates to “tex”.

Not selected values pass unchanged.

Make filename

class MakeFilename(*args, **kwargs)

Make file names for data from the flow.

MakeFilename can be initialized using a single string, a Sequence or from keyword arguments.

A single string is a file name without extension (but it can contain a relative path).

Otherwise, all positional arguments will make a Sequence.

By default, values with context.output already containing filename are skipped. This can be changed using a keyword argument overwrite.

Other allowed keywords are make_filename, make_dirname, make_fileext. Their values must be a tuple, which will initialize a context formatter, or a callable (as returned by format_context). The first item of the tuple is format string, the rest are positional and keyword arguments taken from context during run (see format_context()).

run(flow)

Add output parameters to context from the flow.

If MakeFilename works as a Sequence, it transforms all flow. In general it should only add values for filename, fileext or dirname in context.output. It is recommended that if context already contains the field, that is not changed. Place more specific formatters first in the sequence.

If MakeFilename was initialized with keyword arguments, then only those values are transformed, which have no corresponding fields (filename, fileext and dirname) in context.output and for which the current context from flow could be formatted (contains all necessary keys for the format string).

Note that Sequence takes values with data, while keyword methods take and update only context.

format_context(format_str, *args, **kwargs)

Create a function, which formats a given string using a context.

format_str is an ordinary Python format string. args are positional and kwargs are keyword arguments.

When calling format_context, arguments are bound and a new function is returned. When called with a context, its keys are extracted and formatted in format_str.

Positional arguments in the format_str correspond to args, which must be keys in the context. Keys used as positional arguments may be nested (e.g. format_context(“{}”, “x.y”)).

Keyword arguments kwargs connect arguments between format_str and context. Example:

>>> f = format_context("{y}", y="x.y")
>>> f({"x": {"y": 10}})
'10'

All keywords in the format_str must have corresponding kwargs.

Keyword and positional arguments can be mixed. Example:

>>> f = format_context("{}_{x}_{y}", "x", x="x", y="y")
>>> f({"x": 1, "y": 2})
'1_1_2'
>>>

If no args or kwargs are given, kwargs are extracted from format_str. It must contain all non-empty replacement fields, and only simplest formatting without attribute lookup. Example:

>>> f = format_context("{x}")
>>> f({"x": 10})
'10'

If format_str is not a string, LenaTypeError is raised. All other errors are raised only during formatting. If context doesn’t contain the needed key, LenaKeyError is raised. Note that string formatting can also raise a KeyError or an IndexError, so it is recommended to test your formatters before using them.