docs specialmethods

DagSverreSeljebotn edited this page Sep 4, 2008 · 4 revisions
Clone this wiki locally

Cython special class methods

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

Buffer functions

cdef class MyClass:
    def __getbuffer__(self, Py_buffer* info, int flags):
        info.obj = self # do this if you want __releasebuffer__ called on "self"

    def __releasebuffer__(self, Py_buffer* info):
        # never change info.obj here!

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+.