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