[Numpy-discussion] C API freeze and review

[Ralf Gommers]

On Thu, Mar 10, 2011 at 10:10 PM, Charles R Harris
<charlesr.harris at gmail.com> wrote:
>
>
> On Thu, Mar 10, 2011 at 12:25 AM, Charles R Harris
> <charlesr.harris at gmail.com> wrote:
>>
>>
>> On Thu, Mar 10, 2011 at 12:15 AM, Ralf Gommers
>> <ralf.gommers at googlemail.com> wrote:
>>>
>>> Hi all,
>>>
>>> In preparation for making a 1.6.x branch, I just updated the C API
>>> version. Please do not add any more functions before the branch is
>>> created.
>>>
>>> Over 70 new functions and types were added, we should also review if
>>> all those are necessary and if they are documented. Below is a list of
>>> all new objects (generated with attached script), and an indication of
>>> those items being documented.
>>>
>>> Most function are from the new iterator, are they all necessary?
>>>
>>> And can the authors of the items with missing docs please write some?
>>>
>>> Cheers,
>>> Ralf
>>>
>>>
>>> NpyIter_Type
>>> PyDatetimeArrType_Type
>>> PyHalfArrType_Type
>>> PyTimeIntegerArrType_Type
>>> PyTimedeltaArrType_Type
>>>
>>> NpyIter_Copy                            YES
>>> NpyIter_CreateCompatibleStrides
>>> NpyIter_Deallocate                      YES
>>> NpyIter_DebugPrint
>>> NpyIter_GetAxisStrideArray              YES
>>> NpyIter_GetBufferSize                   YES
>>> NpyIter_GetDataPtrArray                 YES
>>> NpyIter_GetDescrArray                   YES
>>> NpyIter_GetGetCoords                    YES
>>> NpyIter_GetIndexPtr                     YES
>>> NpyIter_GetInitialDataPtrArray
>>> NpyIter_GetInnerFixedStrideArray        YES
>>> NpyIter_GetInnerLoopSizePtr             YES
>>> NpyIter_GetInnerStrideArray             YES
>>> NpyIter_GetIterIndex                    YES
>>> NpyIter_GetIterIndexRange               YES
>>> NpyIter_GetIterNext                     YES
>>> NpyIter_GetIterSize                     YES
>>> NpyIter_GetIterView                     YES
>>> NpyIter_GetNDim                         YES
>>> NpyIter_GetNIter                        YES
>>> NpyIter_GetOperandArray                 YES
>>> NpyIter_GetReadFlags                    YES
>>> NpyIter_GetShape                        YES
>>> NpyIter_GetWriteFlags                   YES
>>> NpyIter_GotoCoords                      YES
>>
>> I'd like to rename this something like  NpyIter_GotoMultiIndex,
>> NpyIter_GotoPolyIndex, or some such. We need a name for extended indices.
>> Suggestions?
>>
>
> Maybe the following terms?
>
> Index -- single index
> FlatIndex -- single index into raveled array
> FullIndex -- [1,2,3]
> FancyIndex -- fancy index

Thanks to Mark for quickly adding docs and renaming some of the above
items. The undocumented items left are:

NpyIter_Type
NpyIter_CreateCompatibleStrides
NpyIter_DebugPrint            # does this need to be exposed?

PyDatetimeArrType_Type
PyTimeIntegerArrType_Type
PyTimedeltaArrType_Type
PyArray_DatetimeStructToDatetime
PyArray_DatetimeToDatetimeStruct
PyArray_SetDatetimeParseFunction
PyArray_TimedeltaStructToTimedelta
PyArray_TimedeltaToTimedeltaStruct

PyHalfArrType_Type
PyArray_ConvertClipmodeSequence


I know the datetime authors are quite busy, but it would really be
helpful if they would make a small update to the NEPs to indicate what
is implemented, still to come, or will not be done, and copy some of
the applicable documentation from the NEP to the C API docs and
relevant docstrings.

Thanks,
Ralf