Editing Advanced Scripting (section)

=== Sending the Results back to Python/PyMOL ===
Once you're done with your calculations and want to send your data back to PyMOL, you need to package it up into a Python object, using the Python API, and then return it.  You should be aware of the expected return value and how you're packaging the results.  If you user calls,
<source lang="python">
(results1,results2) = someCFunction(parameters1,parameters2)
</source>
then you need to package a list with two values.  To build values for returning to PyMOL, use '''[http://www.python.org/doc/1.5.2p2/ext/buildValue.html Py_BuildValue]'''.  Py_BuildValue takes a string indicating the type, and then a list of values.  [http://docs.python.org/ext/buildValue.html Building values] for return has been documented very well.  Consider an example: if I want to package an array of integers, the type specifier for two ints for Py_BuildValue is, "[i,i]", so my call could be:
<source lang="c">
# Package the two ints into a Python pair of ints.
PyObject* thePair = Py_BuildValue( "[i,i]", int1, in2 );

# Don't forget to tell Python about the object.
Py_INCREF(thePair);
</source>

If you need to make a list of things to return, you iterate through a list and make a bunch of '''thePairs''' and add them to a Python list as follows:
<source lang="c">
# Make the python list
PyObject* theList = PyList_New(0);
# Tell Python about it
Py_INCREF(theList);

for ( int i = 0; i < someLim; i++ ) {
  PyObject* thePair = Py_BuildValue( "[i,i]", int1, in2 );
  Py_INCREF(thePair);
  PyList_Append(theList,thePair);
</source>
To add a list of lists, just make an outer list, <source lang="c">PyObject* outerList = PyList_New(0);</source> and iteratively add to it your inner lists:
<source lang="c">
PyObject* outerList = PyList_New(0);
Py_INCREF(outerList);

for ( int i = 0; i < someLim; i++ ) {
  // make the inner list, called curList;
  curList = PyObject* curList = PyList_New(0);
  Py_INCREF(curList);

  // fill the inner list, using PyList_Append with some data, shown above
  ...

  PyList_Append(outerList,curList);
</source>

Great, now we can extract data from Python, use it in C/C++, and package it back up for returning to Python.  Now, we need to learn about the minimal baggage needed for C to operate with Python.  Keep reading; almost done.