Editing Advanced Scripting (section)

==== Reference Counting ====
Next, we check for success.  Unpacking could fail.  If it does, complain and quit.  Else, '''listA''' and '''listB''' now have data in them.  To avoid memory leaks we need to [http://docs.python.org/api/countingRefs.html manually keep track of PyObjects] we're tooling around with.  That is, I can create PyObjects in C (being sneaky and not telling Python) and then when Python quits later on, it'll not know it was supposed to clean up after those objects (making a leak).  To, we let Python know about each list with '''Py_INCREF(listA)''' and '''Py_INCREF(listB)'''.  This is [http://docs.python.org/api/countingRefs.html reference counting].

Now, just for safety, let's check the lists to make sure they actually were passed something.  A tricky user could have given us empty lists, looking to hose the program.  So, we do:
<source lang="c">
     // handle empty selections (should probably do this in Python, it's easier)
     const int lenA = PyList_Size(listA);
     if ( lenA < 1 ) {
             printf("ERROR: First selection didn't have any atoms.  Please check your selection.\n");
             // let Python remove the lists
             Py_DECREF(listA);
             Py_DECREF(listB);
             return NULL;
      }
</source>
We check the list size with, '''[http://docs.python.org/api/listObjects.html PyList_Size]''' and if it's 0 -- we quit.  But, before quitting we give control of the lists back to Python so it can clean up after itself.  We do that with '''Py_DECREF'''.