+Python Binding
+Text borrowed from here
+Any code that you write using any compiled language like C, C++ or Java
+can be integrated or imported into a Python script. This code is
+considered as an “extension”. A Python extension module is nothing more
+than a normal C library. On Unix machines, writting extensions, usually
+requires installing a developer-specific package such as python2.5-dev.
+For your first look at a Python extension module, you’ll be grouping
+your code into three parts:
+
+The C functions you want to expose as the interface from your module.
A table mapping the names of your functions as Python developers will
+see them to C functions inside the extension module.
An initialization function.
+
+The C functions:
+The signatures of the C implementations of your functions will always
+take one of the following three forms:
+static [[PyObject]] MyFunction( PyObjectself, PyObject *args );
+static [[PyObject]] MyFunctionWithKeywords(PyObjectself, PyObject
+args, PyObjectkw);
+static [[PyObject]] MyFunctionWithNoArgs( PyObjectself );
+Each one of the preceding declarations returns a Python object. There’s
+no such thing as a void function in Python as there is in C. If you
+don’t want your functions to return a value, return the C equivalent of
+Python’s None value. The Python headers define a macro, Py_RETURN_NONE,
+that does this for us.
+The names of your C functions can be whatever you like as they will
+never be seen outside of the extension module. So they would be defined
+as static function.
+Your C functions usually are named by combining the Python module and
+function names together, as shown here: static [[PyObject]] *
+[[FileName]] _isImage(PyObject obj, PyObjectargs, PyObject
+*kwargs) { if (isImage(FileName _Value(obj))) Py_RETURN_TRUE; else
+Py_RETURN_FALSE; }
+This would be a Python function called isImage inside of the module
+[[FileName]]. You’ll be putting pointers to your C functions into the
+method table for the module that usually comes next in your source code.
+
+
+The method mapping table
+This method table is a simple array of [[PyMethodDef]] structures. That
+structure looks something like this: struct [[PyMethodDef]] { char
+ml_name; [[PyCFunction]] ml_meth; int ml_flags; charml_doc; };
+Here is the description of the members of this structure:
+ml_name: This is the name of the function as the Python interpreter
+will present it when it is used in Python programs.
+ml_meth: This must be the address to a function that has any one of
+the signatures described in previous seection.
+ml_flags: This tells the interpreter which of the three signatures
+ml_meth is using.
+This flag will usually have a value of METH_VARARGS.
+This flag can be bitwise or’ed with METH_KEYWORDS if you want to allow
+keyword arguments into your function.
+This can also have a value of METH_NOARGS that indicates you don’t want
+to accept any arguments.
+ml_doc: This is the docstring for the function, which could be NULL
+if you don’t feel like writing one
+This table needs to be terminated with a sentinel that consists of NULL
+and 0 values for the appropriate members.
+Example:
+static[[PyMethodDef]][[FileName]]_methods[] = { { “compose”,
+(PyCFunction) FileName_compose, METH_VARARGS, “Compose from root, number
+and extension OR prefix with number @” }, { “composeBlock”,
+(PyCFunction) FileName_composeBlock, METH_VARARGS, “Compose from
+blockname, number, root and extension” }, { NULL } /* Sentinel */ };
+
+
+The initialization function
+The last part of your extension module is the initialization function.
+This function is called by the Python interpreter when the module is
+loaded. It’s required that the function be namedinitModule, where
+Module is the name of the module (the name isinitxmipp in our
+case).
+Your C initialization function generally has the following overall
+structure:
+[[PyMODINIT]]FUNC initModule() {
+Py[InitModule3]; }
+Here is the description of Py_InitModule3 function:
+func: This is the function to be exported.
+module_methods: This is the mapping table name defined above.
+docstring: This is the comment you want to give in your extension.
+Example:
+[[PyMODINIT]]_FUNC initxmipp(void) { //Initialize module
+variable[[PyObject]]* module; module = Py_InitModule3(“xmipp”,
+xmipp_methods, “Xmipp module as a Python extension.”);
+… }
+
+
+All together
+A simple example that makes use of all the above concepts:
+#include <Python.h>
+static[[PyObject]]* helloworld(PyObject* self) { return
+Py_BuildValue(“s”, “Hello, Python extensions!!”); }
+static char helloworld_docs[] = “helloworld( ): Any message you want to
+put here!!:raw-latex:n”;
+static[[PyMethodDef]] helloworld_funcs[] = { {“helloworld”,
+(PyCFunction)helloworld, METH_NOARGS, helloworld_docs}, {NULL} };
+void inithelloworld(void) { Py_InitModule3(“helloworld”,
+helloworld_funcs, “Extension module example!”); }
+
+
+Passing Function parameters
+Most of the time you will add functions to an existing module. For
+example, the following function, that accepts some number of parameters,
+would be defined like this:
+static[[PyObject]]module_func(PyObject self, PyObjectargs) { /
+Parse args and do something interesting here. */ Py_RETURN_NONE; }
+The method table containing an entry for the new function would look
+like this:
+static[[PyMethodDef]] module_methods[] = {
+{ “func”, module_func, METH_VARARGS, “help message” }, { NULL, NULL, 0,
+NULL } };
+You can use API[[PyArg]]_ParseTuple function to extract the
+arguments from the one[[PyObject]] pointer passed into your C function.
+The first argument to[[PyArg]]_ParseTuple is the args argument.
+This is the object you’ll be parsing. The second argument is a format
+string describing the arguments as you expect them to appear. Each
+argument is represented by one or more characters in the format string
+as follows.
+static[[PyObject]] module_func(PyObjectself, PyObject args) { int
+i; double d; chars;
+if (!PyArg_ParseTuple(args, “ids”, &i, &d, &s)) { return NULL; }
+/* Do something interesting here. */ Py_RETURN_NONE; }
+Compiling the new version of your module and importing it will enable
+you to invoke the new function with any number of arguments of any type:
+
+
+The PyArg _ParseTuple Function
+Here is a list of format codes for[[PyArg]] _ParseTuple function:
+Code
+ | C type
+ | Meaning
+ |
c
+ | char
+ | A Python string of length 1 becomes a C char.
+ |
d
+ | double
+ | A Python float becomes a C double.
+ |
f
+ | float
+ | A Python float becomes a C float.
+ |
i
+ | int
+ | A Python int becomes a C int.
+ |
l
+ | long
+ | A Python int becomes a C long.
+ |
L
+ | long long
+ | A Python int becomes a C long long
+ |
O
+ | [[PyObject]]*
+ | Gets non-NULL borrowed reference to Python argument.
+ |
s
+ | char*
+ | Python string without embedded nulls to C char*.
+ |
s#
+ | char*+int
+ | Any Python string to C address and length.
+ |
t#
+ | char*+int
+ | Read-only single-segment buffer to C address and length.
+ |
u
+ | Py_UNICODE*
+ | Python Unicode without embedded nulls to C.
+ |
u#
+ | Py_UNICODE*+int
+ | Any Python Unicode C address and length.
+ |
w#
+ | char*+int
+ | Read/write single-segment buffer to C address and length.
+ |
z
+ | char*
+ | Like s, also accepts None (sets C char* to NULL).
+ |
z#
+ | char*+int
+ | Like s#, also accepts None (sets C char* to NULL).
+ |
(…)
+ | as per …
+ | A Python sequence is treated as one argument per item.
+ |
| | The following arguments are optional.
+ |
:
+ | | Format end, followed by function name for error messages.
+ |
;
+ | | Format end, followed by entire error message text.
+ |
+
+Returning Values:
+Py_BuildValue takes in a format string much like PyArg _ParseTuple
+does. Instead of passing in the addresses of the values you’re building,
+you pass in the actual values. Here’s an example showing how to
+implement an add function:
+static[[PyObject]] foo_add(PyObjectself, PyObject *args) { int a;
+int b;
+if (!PyArg_ParseTuple(args, “ii”, &a, &b)) { return NULL; } return
+Py_BuildValue(“i”, a + b); }
+This is what it would look like if implemented in Python:
+You can return two values from your function as follows, this would be
+cauptured using a list in Python.
+static[[PyObject]] foo_add_subtract(PyObjectself, PyObject *args) {
+int a; int b;
+if (!PyArg_ParseTuple(args, “ii”, &a, &b)) { return NULL; } return
+Py_BuildValue(“ii”, a + b, a - b); }
+This is what it would look like if implemented in Python:
+
+
+Calling Python (+numpy) from C
+Here is an example code to perform the sum of two volumes in Python:
+#include <data/xmipp_image.h>
+#include <Python.h> #include <numpy/ndarrayobject.h>
+void myImport_array() { import_array(); }
+int main() { try { time_config();
+Image I;
+I.read(“/home/coss/temp/BPV_Project/BPV_scale_filtered_windowed.vol”);[[ProcessorTimeStamp]]
+t0; const[[MultidimArray]] &mI=I(); annotate_processor_time(&t0); double
+retval=0.0; FOR_ALL_DIRECT_ELEMENTS_IN_MULTIDIMARRAY(mI)
+retval+=DIRECT_MULTIDIM_ELEM(mI,n)+DIRECT_MULTIDIM_ELEM(mI,n); std::cout
+<< elapsed_time(t0,false) << std::endl; std::cout << “In C++:” << retval
+<< std::endl;
+std::cout << “Initializing Python:raw-latex:n”;
+annotate_processor_time(&t0); Py_Initialize(); myImport_array();
+std::cout << elapsed_time(t0,false) << std::endl;
+// Create numpy array in Python with I() std::cout << “Creating numpy
+array:raw-latex:n”; annotate_processor_time(&t0); npy_intp dim[3];
+dim[0]=ZSIZE(I()); dim[1]=YSIZE(I()); dim[2]=XSIZE(I());[[PyObject]]
+pyI=PyArray_SimpleNewFromData(3, dim, NPY_DOUBLE,
+(void)MULTIDIM_ARRAY(I())); std::cout << elapsed_time(t0,false) <<
+std::endl;
+// Import testPython std::cout << “Importing module:raw-latex:n”;
+annotate_processor_time(&t0);[[PyObject]]* pName
+=[[PyString]]_FromString(“testPython”); // Import testPython PyObject*
+pModule = PyImport_Import(pName); Py_DECREF(pName); std::cout <<
+elapsed_time(t0,false) << std::endl;
+// Call sum std::cout << “Calling sum:raw-latex:n”;
+annotate_processor_time(&t0); [[PyObject]] arglist =
+Py_BuildValue(“OO”, pyI, pyI); PyObjectpFunc =
+PyObject_GetAttrString(pModule, “sum”); PyObject *result =
+PyObject_CallObject(pFunc, arglist); std::cout << elapsed_time(t0,false)
+<< std::endl; std::cout << “In Python:” << PyFloat_AsDouble(result) <<
+std::endl; } catch (XmippError e) { std::cout << e << std::endl; }
+return 0; }
+You have to compile with
+xmipp_compile -i myCode.cpp –python
+And the Python code is
+
+
