[Cython] A few suggestions for the numpy tutorial documentation...

[Robert Kern]

On 2009-04-28 13:10, Dag Sverre Seljebotn wrote:
> Robert Bradshaw wrote:
>> On Apr 28, 2009, at 11:01 AM, Robert Kern wrote:
>>
>>> On 2009-04-28 01:05, Dag Sverre Seljebotn wrote:
>>> [Mike Fletcher wrote:]
>>>>>       * You have to call import_array() in your module or many of the
>>>>>         Numpy C API entry points will segfault
>>>> Are you sure about this? I never do it. I know you need to do it
>>>> from C
>>>> code, but is it not enough in Cython to do
>>>>
>>>> import numpy
>>>>
>>>> ?
>>> If you call any of the PyArray_* functions, you will need an
>>> import_array()
>>> call. That does not just import numpy; it sets up the function
>>> pointer table in
>>> your extension module such that the PyArray_* #defines reference
>>> the right
>>> functions.
>> So "import numpy" doesn't call import_array() then?

No, "import numpy" just imports numpy just as in Python. Each numpy-using 
extension module has a variable local to it that points to the global table of 
function pointers. import_array() must be called once per extension module in 
order to make that module-local variable point to the correct location.

> Apparently a plain import it does what is needed for normal/trivial
> usage of NumPy/Cython, but if you in addition need to call low-level
> PyArray_*-functions then you need the call.
>
> This is fairly well documented in the NumPy API, and my tutorial doesn't
> mention PyArray_*-functions, so I consider the issue OK. (Though we
> could certainly have additional documentation on the wiki for using the
> lower-level NumPy API from Cython).

It would be wise to include it in the tutorial with a comment about when it is 
necessary. People have a wide variety of entry points into the material. They 
may start with your tutorial and just need to use a few API functions. They may 
very well skip the parts in the numpy docs about setting up an extension module 
thinking that Cython took care of everything for them.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
  that is made terrible by our own mad attempt to interpret it as though it had
  an underlying truth."
   -- Umberto Eco