API documentation

API documentation#

Additional to its usage as a command line tool, Fypp can also be operated directly from Python. This can be especially practical, when Fypp is used in a Python driven build environment (e.g. waf, Scons). Below you find the detailed documentation of the API Fypp offers.

fypp module#

For using the functionality of the Fypp preprocessor from within Python, one usually interacts with the following two classes:

  • Fypp: The actual Fypp preprocessor. It returns for a given input the preprocessed output.

  • FyppOptions: Contains customizable settings controlling the behaviour of Fypp. Alternatively, the function get_option_parser() can be used to obtain an option parser, which can create settings based on command line arguments.

If processing stops prematurely, an instance of one of the following subclasses of FyppError is raised:

  • FyppFatalError: Unexpected error (e.g. bad input, missing files, etc.)

  • FyppStopRequest: Stop was triggered by an explicit request in the input (by a stop- or an assert-directive).

Fypp#

class fypp.Fypp(options=None, evaluator_factory=<class 'fypp.Evaluator'>, parser_factory=<class 'fypp.Parser'>, builder_factory=<class 'fypp.Builder'>, renderer_factory=<class 'fypp.Renderer'>)#

Fypp preprocessor.

You can invoke it like

tool = fypp.Fypp()
tool.process_file('file.in', 'file.out')

to initialize Fypp with default options, process file.in and write the result to file.out. If the input should be read from a string, the process_text() method can be used:

tool = fypp.Fypp()
output = tool.process_text('#:if DEBUG > 0\nprint *, "DEBUG"\n#:endif\n')

If you want to fine tune Fypps behaviour, pass a customized FyppOptions instance at initialization:

options = fypp.FyppOptions()
options.fixed_format = True
tool = fypp.Fypp(options)

Alternatively, you can use the command line parser optparse.OptionParser to set options for Fypp. The function get_option_parser() returns you a default option parser. You can then use its parse_args() method to obtain settings by reading the command line arguments:

optparser = fypp.get_option_parser()
options, leftover = optparser.parse_args()
tool = fypp.Fypp(options)

The command line options can also be passed directly as a list when calling parse_args():

args = ['-DDEBUG=0', 'input.fpp', 'output.f90']
optparser = fypp.get_option_parser()
options, leftover = optparser.parse_args(args=args)
tool = fypp.Fypp(options)

For even more fine-grained control over how Fypp works, you can pass in custom factory methods that handle construction of the evaluator, parser, builder and renderer components. These factory methods must have the same signature as the corresponding component’s constructor. As an example of using a builder that’s customized by subclassing:

class MyBuilder(fypp.Builder):

    def __init__(self):
       super().__init__()
       ...additional initialization...

tool = fypp.Fypp(options, builder_factory=MyBuilder)
Parameters:

  • options (object) – Object containing the settings for Fypp. You typically would pass a customized FyppOptions instance or an optparse.Values object as returned by the option parser. If not present, the default settings in FyppOptions are used.

  • evaluator_factory (function) – Factory function that returns an Evaluator object. Its call signature must match that of the Evaluator constructor. If not present, Evaluator is used.

  • parser_factory (function) – Factory function that returns a Parser object. Its call signature must match that of the Parser constructor. If not present, Parser is used.

  • builder_factory (function) – Factory function that returns a Builder object. Its call signature must match that of the Builder constructor. If not present, Builder is used.

  • renderer_factory (function) – Factory function that returns a Renderer object. Its call signature must match that of the Renderer constructor. If not present, Renderer is used.

process_file(infile, outfile=None)#

Processes input file and writes result to output file.

Parameters:

  • infile (str) – Name of the file to read and process. If its value is ‘-’, input is read from stdin.

  • outfile (str, optional) – Name of the file to write the result to. If its value is ‘-’, result is written to stdout. If not present, result will be returned as string.

  • env (dict, optional) – Additional definitions for the evaluator.

Returns:

Result of processed input, if no outfile was specified.

Return type:

str

process_text(txt)#

Processes a string.

Parameters:

  • txt (str) – String to process.

  • env (dict, optional) – Additional definitions for the evaluator.

Returns:

Processed content.

Return type:

str

FyppOptions#

class fypp.FyppOptions#

Container for Fypp options with default values.

defines#

List of variable definitions in the form of ‘VARNAME=VALUE’. Default: []

Type:

list of str

includes#

List of paths to search when looking for include files. Default: []

Type:

list of str

line_numbering#

Whether line numbering directives should appear in the output. Default: False

Type:

bool

line_numbering_mode#

Line numbering mode ‘full’ or ‘nocontlines’. Default: ‘full’.

Type:

str

line_marker_format#

Line marker format. Currently ‘std’, ‘cpp’ and ‘gfortran5’ are supported, where ‘std’ emits #line pragmas similar to standard tools, ‘cpp’ produces line directives as emitted by GNU cpp, and ‘gfortran5’ cpp line directives with a workaround for a bug introduced in GFortran 5. Default: ‘cpp’.

Type:

str

line_length#

Length of output lines. Default: 132.

Type:

int

folding_mode#

Folding mode ‘smart’, ‘simple’ or ‘brute’. Default: ‘smart’.

Type:

str

no_folding#

Whether folding should be suppressed. Default: False.

Type:

bool

indentation#

Indentation in continuation lines. Default: 4.

Type:

int

modules#

Modules to import at initialization. Default: [].

Type:

list of str

moduledirs#

Module lookup directories for importing user specified modules. The specified paths are looked up before the standard module locations in sys.path.

Type:

list of str

fixed_format#

Whether input file is in fixed format. Default: False.

Type:

bool

encoding#

Character encoding for reading/writing files. Allowed values are Pythons codec identifiers, e.g. ‘ascii’, ‘utf-8’, etc. Default: ‘utf-8’. Reading from stdin and writing to stdout is always encoded according to the current locale and is not affected by this setting.

Type:

str

create_parent_folder#

Whether the parent folder for the output file should be created if it does not exist. Default: False.

Type:

bool

get_option_parser()#

fypp.get_option_parser()#

Returns an option parser for the Fypp command line tool.

Returns:

Parser which can create an optparse.Values object with

Fypp settings based on command line arguments.

Return type:

OptionParser

FyppError#

class fypp.FyppError(msg, fname=None, span=None)#

Signalizes error occurring during preprocessing.

Parameters:

  • msg (str) – Error message.

  • fname (str) – File name. None (default) if file name is not available.

  • span (tuple of int) – Beginning and end line of the region where error occurred or None if not available. If fname was not None, span must not be None.

msg#

Error message.

Type:

str

fname#

File name or None if not available.

Type:

str or None

span#

Beginning and end line of the region where error occurred or None if not available. Line numbers start from zero. For directives, which do not consume end of the line, start and end lines are identical.

Type:

tuple of int or None

Contents