Cython special class methods

(Or some that are not in Pyrex anyway. This documentation should probably be moved somewhere appropriate.)

Buffer functions

   1 cdef class MyClass:
   2     def __getbuffer__(self, Py_buffer* info, int flags):
   3         info.obj = self # do this if you want __releasebuffer__ called on "self"
   4         ...
   5 
   6     def __releasebuffer__(self, Py_buffer* info):
   7         # never change info.obj here!
   8         ...

These let your class export a buffer as described in PEP-3118.

There is some special treatment of __getbuffer__ so that reference counting will work correctly:

The field info.obj (with info being the second argument) is initialized to None automatically at the beginning of the function.
info.obj is typed as a Python object
If the function exits with an exception, info.obj is decref-ed and set to NULL automatically.
If the function exits normally, a value of None in info.obj is converted to a value of NULL.

Note that within __releasebuffer__, you must not change info.obj (there's no reason you should either), as this will decref the object. When __releasebuffer__ is called Python is already on its way to decref info.obj and so if you reassign it there will be one decref too many (and a segfault may happen later).

All Cython-generated classes have Py_TPFLAGS_HAVE_NEWBUFFER set under Python 2.6+.