Editing Advanced Scripting (section)

==== Calling the External Function ====
So, to start, let's look at the Python code that will call the C-function:
<source lang="python">
#
# -- in someCode.py
#
# Call funName.  Pass it a list () of lists.  (sel1 and sel2 are lists.)
# Get the return value into rValFromC.
#
rValFromC = funName( (sel1, sel2) );
</source>
where '''sel1''' and '''sel2''' could be any list of atom coordinates, say, from PyMOL.  (See above.)

Ok, this isn't hard.  Now, we need to see what the code that receives this function call in C, looks like.  Well, first we need to let C know we're integrating with Python.  So, in your [http://docs.python.org/api/includes.html header file] of '''funName.h''' we put:
<source lang="c">
// in funName.h
#include <Python.h>
</source>

Next, by default your C-function's name is '''funName_funName''' (and that needs to be setup, I'll show how, later).  So, let's define funName:
<source lang="c">
static PyObject*
funName_funName(PyObject* self, PyObject* args)
{
...more code...
</source>
This is the generic call.  '''funName''' is taking two pointers to [http://docs.python.org/api/common-structs.html PyObjects].  It also returns a PyObject.  This is how you get the Python data into and out of C.  It shows up in "[http://docs.python.org/api/arg-parsing.html args]" array of packaged Python objects and we then unpack it into C, using some [http://docs.python.org/api/arg-parsing.html helper methods].  Upon completion of unpacking,  we perform our C/C++ procedure with the data, package up the results using the [http://docs.python.org/api/api.html Python API], and send the results back to Python/PyMOL.