Merge pull request #210 from nbruin/master

Explain difference between cdef and cpdef

docs/src/quickstart/cythonize.rst

@@ -94,13 +94,16 @@ object or if it is guaranteed that an exception will not be raised
 within the function call.
 
 A side-effect of cdef is that the function is no longer available from
-Python-space, as Python wouldn't know how to call it. Using the
-``cpdef`` keyword instead of cdef, a Python wrapper is also created,
-so that the function is available both from Cython (fast, passing
-typed values directly) and from Python (wrapping values in Python
-objects).
+Python-space, as Python wouldn't know how to call it. It is also no
+longer possible to change ``f` at runtime.
 
-Note also that it is no longer possible to change ``f`` at runtime.
+Using the ``cpdef`` keyword instead of ``cdef``, a Python wrapper is also
+created, so that the function is available both from Cython (fast, passing
+typed values directly) and from Python (wrapping values in Python
+objects). In fact, ``cpdef`` does not just provide a Python wrapper, it also
+installs logic to allow the method to be overridden by python methods, even
+when called from within cython. This does add a tiny overhead compared to ``cdef``
+methods.
 
 Speedup: 150 times over pure Python.
 

docs/src/tutorial/cdef_classes.rst

@@ -32,20 +32,25 @@ Cython code and pure Python code.
 
 So far our integration example has not been very useful as it only
 integrates a single hard-coded function. In order to remedy this,
-without sacrificing speed, we will use a cdef class to represent a
+with hardly sacrificing speed, we will use a cdef class to represent a
 function on floating point numbers::
 
   cdef class Function:
       cpdef double evaluate(self, double x) except *:
           return 0
 
-Like before, cpdef makes two versions of the method available; one
+The directive cpdef makes two versions of the method available; one
 fast for use from Cython and one slower for use from Python. Then::
 
   cdef class SinOfSquareFunction(Function):
       cpdef double evaluate(self, double x) except *:
           return sin(x**2)
 
+This does slightly more than providing a python wrapper for a cdef
+method: unlike a cdef method, a cpdef method is fully overrideable by
+subclasses and instance attributes. This adds a little calling overhead
+compared to a cdef method.
+
 Using this, we can now change our integration example::
 
   def integrate(Function f, double a, double b, int N):
@@ -62,8 +67,8 @@ Using this, we can now change our integration example::
   print(integrate(SinOfSquareFunction(), 0, 1, 10000))
 
 This is almost as fast as the previous code, however it is much more flexible
-as the function to integrate can be changed. It is even possible to pass
-in a new function defined in Python-space::
+as the function to integrate can be changed. We can even pass in a new
+function defined in Python-space::
 
   >>> import integrate
   >>> class MyPolynomial(integrate.Function):

docs/src/tutorial/clibraries.rst

@@ -426,7 +426,10 @@ methods from ``cdef`` to ``cpdef``.  This will let Cython generate two
 entry points, one that is callable from normal Python code using the
 Python call semantics and Python objects as arguments, and one that is
 callable from C code with fast C semantics and without requiring
-intermediate argument conversion from or to Python types.
+intermediate argument conversion from or to Python types. Note that ``cpdef``
+methods ensure that they can be appropriately overridden by Python
+methods even when they are called from Cython. This adds a tiny overhead
+compared to ``cdef`` methods.
 
 The following listing shows the complete implementation that uses
 ``cpdef`` methods where possible::

docs/src/userguide/extension_types.rst

@@ -343,7 +343,9 @@ C methods
 Extension types can have C methods as well as Python methods. Like C
 functions, C methods are declared using :keyword:`cdef` or :keyword:`cpdef` instead of
 :keyword:`def`. C methods are "virtual", and may be overridden in derived
-extension types.::
+extension types. In addition, :keyword:`cpdef` methods can even be overridden by python
+methods when called as C method. This adds a little to their calling overhead
+compared to a :keyword:`cdef` methd::
 
     # pets.pyx
     cdef class Parrot:

docs/src/userguide/language_basics.rst

@@ -100,7 +100,11 @@ interpreted Python code. So, any functions that you want to "export" from your
 Cython module must be declared as Python functions using def. 
 There is also a hybrid function, called :keyword:`cpdef`. A :keyword:`cpdef` 
 can be called from anywhere, but uses the faster C calling conventions 
-when being called from other Cython code. 
+when being called from other Cython code. A :keyword:`cpdef` can also be overridden
+by a Python method on a subclass or an instance attribute, even when called from Cython.
+If this happens, most performance gains are of course lost and even if it does not,
+there is a tiny overhead in calling a :keyword:`cpdef` method from Cython compared to
+calling a :keyword:`cdef` method.
 
 Parameters of either type of function can be declared to have C data types,
 using normal C declaration syntax. For example,::