[Numpy-discussion] array interface nitpicks

[David M. Cooke]

Just some small nitpicks in the array interface document
(http://numeric.scipy.org/array_interface.html):

As written:
"""
__array_shape__ (required)

Tuple showing size in each dimension. Each entry in the tuple must be
a Python (long) integer. Note that these integers could be larger
than the platform "int" or "long" could hold. Use Py_LONG_LONG if
accessing the entries of this tuple in C.
"""

Since this is supposed to be an interface, not an implementation
(duck-typing and all that), I think this is too strict:
__array_shape__ should just be a sequence of integers, not necessarily
a tuple. I'd suggest something like this:

'''
__array_shape__ (required)

Sequence whose elements are the size in each dimension. Each entry is
an integer (a Python int or long). Note that these integers could be
larger than the platform "int" or "long" could hold (a Python int is a
C long). It is up to the calling code to handle this appropiately;
either by raising an error when overflow is possible, or by using
Py_LONG_LONG as the C type for the shapes.
'''

This is clearer about the users responsibility -- note that Numeric
is taking the first approach (error), as the dimensions in
PyArrayObject are ints.

Similiar comments about __array_strides. I'd reword it along the lines
of

'''
__array_strides__ (optional)

Sequence of strides which provides the number of bytes needed to jump
to the next array element in the corresponding dimension. Each entry
must be integer (a Python int or long). As with __array_shape__, the
values may be larger than can be represented by a C "int" or "long";
the calling code should handle this appropiately, either by raising an
error, or by using Py_LONG_LONG in C.
Default is a strides tuple which implies a C-style contiguous memory
buffer. In this model, the last dimension of the array varies the
fastest. For example, the default __array_strides__ tuple for an
object whose array entries are 8 bytes long and whose __array_shape__
is (10,20,30) would be (4800, 240, 8)
Default: C-style contiguous
'''

I'm mostly worried about the use of Python longs; it shouldn't be
necessary in almost all cases, and adds extra complications (in normal
usage, you don't see Python longs all that much).

-- 
|>|\/|<
/--------------------------------------------------------------------------\
|David M. Cooke                      http://arbutus.physics.mcmaster.ca/dmc/
|cookedm at physics.mcmaster.ca