1##################################################################### 2# 3# These are the Cython pxd files for (most of) the Python/C API. 4# 5# REFERENCE COUNTING: 6# 7# JUST TO SCARE YOU: 8# If you are going to use any of the Python/C API in your Cython 9# program, you might be responsible for doing reference counting. 10# Read http://docs.python.org/api/refcounts.html which is so 11# important I've copied it below. 12# 13# For all the declaration below, whenver the Py_ function returns 14# a *new reference* to a PyObject*, the return type is "object". 15# When the function returns a borrowed reference, the return 16# type is PyObject*. When Cython sees "object" as a return type 17# it doesn't increment the reference count. When it sees PyObject* 18# in order to use the result you must explicitly cast to <object>, 19# and when you do that Cython increments the reference count wether 20# you want it to or not, forcing you to an explicit DECREF (or leak memory). 21# To avoid this we make the above convention. Note, you can 22# always locally override this convention by putting something like 23# 24# cdef extern from "Python.h": 25# PyObject* PyNumber_Add(PyObject *o1, PyObject *o2) 26# 27# in your .pyx file or into a cimported .pxd file. You just have to 28# use the one from the right (pxd-)namespace then. 29# 30# Cython automatically takes care of reference counting for anything 31# of type object. 32# 33## More precisely, I think the correct convention for 34## using the Python/C API from Cython is as follows. 35## 36## (1) Declare all input arguments as type "object". This way no explicit 37## <PyObject*> casting is needed, and moreover Cython doesn't generate 38## any funny reference counting. 39## (2) Declare output as object if a new reference is returned. 40## (3) Declare output as PyObject* if a borrowed reference is returned. 41## 42## This way when you call objects, no cast is needed, and if the api 43## calls returns a new reference (which is about 95% of them), then 44## you can just assign to a variable of type object. With borrowed 45## references if you do an explicit typecast to <object>, Cython generates an 46## INCREF and DECREF so you have to be careful. However, you got a 47## borrowed reference in this case, so there's got to be another reference 48## to your object, so you're OK, as long as you relealize this 49## and use the result of an explicit cast to <object> as a borrowed 50## reference (and you can call Py_INCREF if you want to turn it 51## into another reference for some reason). 52# 53# "The reference count is important because today's computers have 54# a finite (and often severely limited) memory size; it counts how 55# many different places there are that have a reference to an 56# object. Such a place could be another object, or a global (or 57# static) C variable, or a local variable in some C function. When 58# an object's reference count becomes zero, the object is 59# deallocated. If it contains references to other objects, their 60# reference count is decremented. Those other objects may be 61# deallocated in turn, if this decrement makes their reference 62# count become zero, and so on. (There's an obvious problem with 63# objects that reference each other here; for now, the solution is 64# ``don't do that.'') 65# 66# Reference counts are always manipulated explicitly. The normal 67# way is to use the macro Py_INCREF() to increment an object's 68# reference count by one, and Py_DECREF() to decrement it by 69# one. The Py_DECREF() macro is considerably more complex than the 70# incref one, since it must check whether the reference count 71# becomes zero and then cause the object's deallocator to be 72# called. The deallocator is a function pointer contained in the 73# object's type structure. The type-specific deallocator takes 74# care of decrementing the reference counts for other objects 75# contained in the object if this is a compound object type, such 76# as a list, as well as performing any additional finalization 77# that's needed. There's no chance that the reference count can 78# overflow; at least as many bits are used to hold the reference 79# count as there are distinct memory locations in virtual memory 80# (assuming sizeof(long) >= sizeof(char*)). Thus, the reference 81# count increment is a simple operation. 82# 83# It is not necessary to increment an object's reference count for 84# every local variable that contains a pointer to an object. In 85# theory, the object's reference count goes up by one when the 86# variable is made to point to it and it goes down by one when the 87# variable goes out of scope. However, these two cancel each other 88# out, so at the end the reference count hasn't changed. The only 89# real reason to use the reference count is to prevent the object 90# from being deallocated as long as our variable is pointing to 91# it. If we know that there is at least one other reference to the 92# object that lives at least as long as our variable, there is no 93# need to increment the reference count temporarily. An important 94# situation where this arises is in objects that are passed as 95# arguments to C functions in an extension module that are called 96# from Python; the call mechanism guarantees to hold a reference 97# to every argument for the duration of the call. 98# 99# However, a common pitfall is to extract an object from a list 100# and hold on to it for a while without incrementing its reference 101# count. Some other operation might conceivably remove the object 102# from the list, decrementing its reference count and possible 103# deallocating it. The real danger is that innocent-looking 104# operations may invoke arbitrary Python code which could do this; 105# there is a code path which allows control to flow back to the 106# user from a Py_DECREF(), so almost any operation is potentially 107# dangerous. 108# 109# A safe approach is to always use the generic operations 110# (functions whose name begins with "PyObject_", "PyNumber_", 111# "PySequence_" or "PyMapping_"). These operations always 112# increment the reference count of the object they return. This 113# leaves the caller with the responsibility to call Py_DECREF() 114# when they are done with the result; this soon becomes second 115# nature. 116# 117# Now you should read http://docs.python.org/api/refcountDetails.html 118# just to be sure you understand what is going on. 119# 120################################################################# 121 122 123 124################################################################# 125# BIG FAT DEPRECATION WARNING 126################################################################# 127# Do NOT cimport any names directly from the cpython package, 128# despite of the star-imports below. They will be removed at 129# some point. 130# Instead, use the correct sub-module to draw your cimports from. 131# 132# A direct cimport from the package will make your code depend on 133# all of the existing declarations. This may have side-effects 134# and reduces the portability of your code. 135################################################################# 136# START OF DEPRECATED SECTION 137################################################################# 138 139from cpython.version cimport * 140from cpython.ref cimport * 141from cpython.exc cimport * 142from cpython.module cimport * 143from cpython.mem cimport * 144from cpython.tuple cimport * 145from cpython.list cimport * 146from cpython.object cimport * 147from cpython.sequence cimport * 148from cpython.mapping cimport * 149from cpython.iterator cimport * 150from cpython.type cimport * 151from cpython.number cimport * 152from cpython.int cimport * 153from cpython.bool cimport * 154from cpython.long cimport * 155from cpython.float cimport * 156from cpython.complex cimport * 157from cpython.string cimport * 158from cpython.unicode cimport * 159from cpython.dict cimport * 160from cpython.instance cimport * 161from cpython.function cimport * 162from cpython.method cimport * 163from cpython.weakref cimport * 164from cpython.getargs cimport * 165from cpython.pythread cimport * 166from cpython.pystate cimport * 167 168# Python <= 2.x 169from cpython.cobject cimport * 170from cpython.oldbuffer cimport * 171 172# Python >= 2.4 173from cpython.set cimport * 174 175# Python >= 2.6 176from cpython.buffer cimport * 177from cpython.bytes cimport * 178 179# Python >= 3.0 180from cpython.pycapsule cimport * 181 182################################################################# 183# END OF DEPRECATED SECTION 184################################################################# 185