8. C-API

A C/C++ api has been provided for developers who are embedding Python into their program and wish to use the input_reader module to parse an input file. The API provides functions that make it easy to set up the Python environment within your C program, and to extract information from the Namespace object returned from InputReader.read_input() without having to worry about reference counting (when possible).

8.1. InputReader.include_path

This is a “header-only” library, meaning that you only need to include the header file supplied with this package to use it. You can determine the path to this header programatically using InputReader.include_path. In bash this might look like

$ cc -I$(python -c "import input_reader; print input_reader.include_path") -c a.c -o a.o

Or, to reduce the number of calls to the Python interpreter for large projects,

$ INPUT_READER=$(python -c "import input_reader; print input_reader.include_path")
$ cc -I$INPUT_READER -c a.c -o a.o
$ cc -I$INPUT_READER -c b.c -o b.o

8.2. The C Functions

Typedefs

typedef int bool

Functions

int AddCustomPythonSearchPath(const char * path, bool prepend)

Add a custom search path to sys.path.

Return

1 if unsuccessful, 0 otherwise.

Parameters

• path -

  The path to add to sys.path.

• prepend -

  Indicates you want to put the path at the front of sys.path instead of the end of sys.path.

const char * GetLastErrorMessage()

Returns the python traceback from an error.

The function checks if there is an error on the stack, and if so returns a minimal traceback message.

Return

The error message, or NULL if there was no error.

PyObject * CallInputReaderWrapperFunction(const char * module, const char * function, const char * input)

Calls a function that reads the input and returns the Namespace object.

It is assumed that the given function is a wrapper around the input reader definition then returns the output of the read_input method.

Check PyErr_Occured() or GetLastErrorMessage() after calling for errors.

Return

The Namespace object, or NULL if an error occurred.

Parameters

• module -

  The name of the python module containing the function to call.

• function -

  The name of the function to call.

• input -

  The name of the file to read.

PyObject * CallInputReaderReadInput(const char * module, const char * instance, const char * input)

Calls the InputReader object’s read_input to return the Namespace.

Extracts appropriate InputReader instance from the given module, and then calls its read_input method.

Check PyErr_Occured() or GetLastErrorMessage() after calling for errors.

Return

The Namespace object, or NULL if an error occurred.

Parameters

• module -

  The name of the python module containing the function to call.

• instance -

  The name of the InputReader instance object we will use to read the input file.

• input -

  The name of the file to read.

bool ExistsInNamespace(PyObject * name_space, const char * attr)

Determine if the given attribute is in the Namespace.

Return

True if it exists, false, if not.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to check.

bool ExistsInNamespace_IsNone(PyObject * name_space, const char * attr)

Determine if the given attribute is in the Namespace and is None.

Return

True if the attribute is None, false, if not.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to check.

bool ExistsInNamespace_IsInt(PyObject * name_space, const char * attr)

Determine if the given attribute is in the Namespace and is an int.

Return

True if the attribute is an int, false, if not.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to check.

bool ExistsInNamespace_IsFloat(PyObject * name_space, const char * attr)

Determine if the given attribute is in the Namespace and is a float.

Return

True if the attribute is a float, false, if not.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to check.

bool ExistsInNamespace_IsBool(PyObject * name_space, const char * attr)

Determine if the given attribute is in the Namespace and is a bool.

Return

True if the attribute is a bool, false, if not.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to check.

bool ExistsInNamespace_IsString(PyObject * name_space, const char * attr)

Determine if the given attribute is in the Namespace and is a str.

Return

True if the attribute is a str, false, if not.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to check.

bool ExistsInNamespace_IsSequence(PyObject * name_space, const char * attr)

Determine if the given attribute is in the Namespace and is a sequence.

Return

True if the attribute is a sequence, false, if not.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to check.

bool ExistsInNamespace_IsDict(PyObject * name_space, const char * attr)

Determine if the given attribute is in the Namespace and is a dict.

Return

True if the attribute is a dict, false, if not.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to check.

bool ExistsInNamespace_IsSubNamespace(PyObject * name_space, const char * attr)

Determine if the given attribute is in the Namespace and is a Namespace.

Return

True if the attribute is a Namespace, false, if not.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to check.

int FromNamespace_AsInt(PyObject * name_space, const char * attr)

Extract the given attribute from the Namespace as an int. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value in the attribute as an int.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

double FromNamespace_AsDouble(PyObject * name_space, const char * attr)

Extract the given attribute from the Namespace as a double. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value in the attribute as a double.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

bool FromNamespace_AsBool(PyObject * name_space, const char * attr)

Extract the given attribute from the Namespace as a bool. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value in the attribute as a bool.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

Py_complex FromNamespace_AsPyComplex(PyObject * name_space, const char * attr)

Extract the given attribute from the Namespace as a Py_complex. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value in the attribute as a Py_complex.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

const char * FromNamespace_AsString(PyObject * name_space, const char * attr)

Extract the given attribute from the Namespace as a const char*. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value in the attribute as a const char*.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

PyObject * FromNamespace_AsPyObject(PyObject * name_space, const char * attr)

Extract the given attribute from the Namespace as a PyObject. Check PyErr_Occured() or GetLastErrorMessage() for errors. The user will be responsible for decreasing the reference count of the returned object when they are done with it.

Return

The value in the attribute as a PyObject.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

PyObject * FromNamespace_SubNamespace(PyObject * name_space, const char * attr)

Extract a sub-Namespace from the Namespace (i.e. from a block). Check PyErr_Occured() or GetLastErrorMessage() for errors. The user will be responsible for decreasing the reference count of the returned object when they are done with it.

Return

The value in the attribute as a PyObject.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

int FromNamespace_AsInt_AtIndex(PyObject * name_space, const char * attr, int index)

Extract the given attribute from the Namespace as an int at some index in a sequence. It is assumed that the object in the given attribute is some sequence that can be indexed. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value at the index in the attribute as an int.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

• index -

  The index in the sequence.

double FromNamespace_AsDouble_AtIndex(PyObject * name_space, const char * attr, int index)

Extract the given attribute from the Namespace as a double at some index in a sequence. It is assumed that the object in the given attribute is some sequence that can be indexed. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value at the index in the attribute as a double.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

• index -

  The index in the sequence.

bool FromNamespace_AsBool_AtIndex(PyObject * name_space, const char * attr, int index)

Extract the given attribute from the Namespace as a bool at some index in a sequence. It is assumed that the object in the given attribute is some sequence that can be indexed. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value at the index in the attribute as a bool.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

• index -

  The index in the sequence.

Py_complex FromNamespace_AsPyComplex_AtIndex(PyObject * name_space, const char * attr, int index)

Extract the given attribute from the Namespace as a Py_complex at some index in a sequence. It is assumed that the object in the given attribute is some sequence that can be indexed. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value at the index in the attribute as a Py_complex.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

• index -

  The index in the sequence.

const char * FromNamespace_AsString_AtIndex(PyObject * name_space, const char * attr, int index)

Extract the given attribute from the Namespace as a const char* at some index in a sequence. It is assumed that the object in the given attribute is some sequence that can be indexed. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value at the index in the attribute as a const char*.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

• index -

  The index in the sequence.

PyObject * FromNamespace_AsPyObject_AtIndex(PyObject * name_space, const char * attr, int index)

Extract the given attribute from the Namespace as a PyObject at some index in a sequence. It is assumed that the object in the given attribute is some sequence that can be indexed. Check PyErr_Occured() or GetLastErrorMessage() for errors. The user will be responsible for decreasing the reference count of the returned object when they are done with it.

Return

The value at the index in the attribute as a PyObject.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

• index -

  The index in the sequence.

int FromNamespace_AsInt_AtKey(PyObject * name_space, const char * attr, const char * key)

Extract the given attribute from the Namespace as an int at some key in a dict. It is assumed that the object in the given attribute is some dict. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value at the index in the attribute as an int.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

• key -

  The key in the dict.

double FromNamespace_AsDouble_AtKey(PyObject * name_space, const char * attr, const char * key)

Extract the given attribute from the Namespace as a double at some key in a dict. It is assumed that the object in the given attribute is some dict. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value at the index in the attribute as a double.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

• key -

  The key in the dict.

bool FromNamespace_AsBool_AtKey(PyObject * name_space, const char * attr, const char * key)

Extract the given attribute from the Namespace as a bool at some key in a dict. It is assumed that the object in the given attribute is some dict. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value at the index in the attribute as a bool.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

• key -

  The key in the dict.

Py_complex FromNamespace_AsPyComplex_AtKey(PyObject * name_space, const char * attr, const char * key)

Extract the given attribute from the Namespace as a Py_complex at some key in a dict. It is assumed that the object in the given attribute is some dict. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value at the index in the attribute as a Py_complex.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

• key -

  The key in the dict.

const char * FromNamespace_AsString_AtKey(PyObject * name_space, const char * attr, const char * key)

Extract the given attribute from the Namespace as a const char* at some key in a dict. It is assumed that the object in the given attribute is some dict. Check PyErr_Occured() or GetLastErrorMessage() for errors.

Return

The value at the index in the attribute as a const char*.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

• key -

  The key in the dict.

PyObject * FromNamespace_AsPyObject_AtKey(PyObject * name_space, const char * attr, const char * key)

Extract the given attribute from the Namespace as a PyObject at some key in a dict. It is assumed that the object in the given attribute is some dict. Check PyErr_Occured() or GetLastErrorMessage() for errors. The user will be responsible for decreasing the reference count of the returned object when they are done with it.

Return

The value at the index in the attribute as a PyObject.

Parameters

• name_space -

  The Namespace object.

• attr -

  The attribute to get from the Namespace.

• key -

  The key in the dict.

Variables

const bool false

const bool true