fire::config Namespace Reference

python execution and parameter extraction More...

Classes
class	Parameters
	Class encapsulating parameters for configuring a processor. More...

Functions
Parameters	run (const std::string &root_object, const std::string &pythonScript, char *args[], int nargs)
	run the python script and extract the parameters More...
static std::string	getPyString (PyObject *pyObj)
	Turn the input python string object into a std::string. More...
static Parameters	getMembers (PyObject *object)
	Extract members from a python object. More...

Detailed Description

python execution and parameter extraction

this namespace is focused on holding the necessary functions to run and extract the configuration parameters from a python script. The documentation here is focused on the C++-side of the configuration - i.e. the translation of Python objects into their C++ counterparts. For documentation on the Python package used to configure fire, refer to fire's python package.

Function Documentation

getMembers()

static Parameters fire::config::getMembers ( PyObject *  object )

static

Extract members from a python object.

Iterates through the object's dictionary and translates the objects inside of it into the type-specified C++ equivalents, then puts these objects into an instance of the Parameters class.

This function is recursive. If a non-base type is encountered, we pass it back along to this function to translate it's own dictionary.

We rely completely on python being awesome. For all higher level class objects, python keeps track of all of its member variables in the member dictionary __dict__.

No Py_DECREF calls are made because all of the members of an object are borrowed references, meaning that when we destory that object, it handles the other members. We destroy the one Python object owning all of these references at the end of this function.

Note

Not sure if this is not leaking memory, kinda just trusting the Python / C API docs on this one.

Empty lists are NOT read in because there is no way for us to know what type should be inside the list. This means list parameters that can be empty need to put in a default empty list value: {}.

This recursive extraction method is able to handle the following cases.

• User-defined classes (via the __dict__ member) are extracted to Parameters
• one-dimensional lists whose entries all have the same type are extracted to std::vector of the type of the first entry in the list
• dict objects are extracted to Parameters
• Python str are extracted to std::string
• Python int are extracted to C++ int
• Python bool are extracted to C++ bool
• Python float are extracted to C++ double

Known design flaws include

• No support for nested Python lists
• Annoying band-aid solution for empty Python lists

Parameters

[in]

object

Python object to get members from

Returns

Mapping between member name and value.

getPyString()

static std::string fire::config::getPyString ( PyObject *  pyObj )

static

Turn the input python string object into a std::string.

Helpful to condense down the multi-line nature of the python3 code.

Parameters

[in]

pyObj

python object assumed to be a string python object

Returns

the value stored in it

run()

Parameters fire::config::run	(	const std::string &	root_object,
		const std::string &	pythonScript,
		char *	args[],
		int	nargs
	)

run the python script and extract the parameters

This method contains all the parsing and execution of the python script.

Exceptions

Exception	if the python script does not exit properly
Exception	if any necessary components of the python configuration are missing. e.g. The Process class or the different members of the lastProcess object.

The basic premise of this function is to execute the python configuration script. Then, after the script has been executed, all of the parameters for the Process are gathered from python. The fact that the script has been executed means that the user can get up to a whole lot of shenanigans that can help them make their work more efficient.

Parameters

[in]	full	pythonic path to the object to kickoff extraction
[in]	pythonScript	Filename location of the python script.
[in]	args	Commandline arguments to be passed to the python script.
[in]	nargs	Number of commandline arguments, assumed to be >= 0