Andrew Straw wrote:
> Pauli Virtanen wrote:
>> Hi,
>>
>> Fri, 06 Mar 2009 09:16:33 -0800, Andrew Straw wrote:
>>> I have updated http://numpy.scipy.org/array_interface.shtml to have a
>>> giant warning first paragraph describing how that information is
>>> outdated. Additionally, I have updated http://numpy.scipy.org/ to point
>>> people to the buffer interface described in PEP 3118 and implemented in
>>> Python 2.6/3.0. Furthermore, I have suggested Cython has a way to write
>>> code for older Pythons that will automatically support the buffer
>>> interface in newer Pythons.
>>>
>>> If you have knowledge about these matters (Travis O. and Dag,
>>> especially), I'd appreciate it if you could read over the pages to
>>> ensure everything is actually correct.
>> I wonder if it would make sense to redirect the page here:
>>
>> http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
>>
>> so that it would be easier to edit etc. in the future?
>>
>
>
> Yes, great idea. I just updated the page to point to the page you linked
> (which I didn't know existed -- thanks for pointing it out).
>
> Also, I have made several changes to arrays.interface.rst which I will
> upload once my password situation gets resolved.
OK, I now have a password (thanks Gaël), but I don't have edit
permissions on that page. So I'm attaching a patch against that page
source that incorporates the stuff that was on the old page that's not
in the new page.
I'm happy to apply this myself if someone gives me edit permissions. I
wasn't able to check out all the ReST formatting with the online editor
because I don't have edit permissions.
-Andrew
diff --git a/scipy-website/numpy-doc/arrays.interface.rst b/scipy-website/numpy-doc/arrays.interface.rst
index e3b12ce..4894dd6 100644
--- a/scipy-website/numpy-doc/arrays.interface.rst
+++ b/scipy-website/numpy-doc/arrays.interface.rst
@@ -206,6 +206,33 @@ array using only one attribute lookup and a well-defined C-structure.
must also not reallocate their memory if other objects are
referencing them.
+The PyArrayInterface structure is defined in ``numpy/ndarrayobject.h``
+as::
+
+ typedef struct {
+ int two; /* contains the integer 2 -- simple sanity check */
+ int nd; /* number of dimensions */
+ char typekind; /* kind in array --- character code of typestr */
+ int itemsize; /* size of each element */
+ int flags; /* flags indicating how the data should be interpreted */
+ /* must set ARR_HAS_DESCR bit to validate descr */
+ Py_intptr_t *shape; /* A length-nd array of shape information */
+ Py_intptr_t *strides; /* A length-nd array of stride information */
+ void *data; /* A pointer to the first element of the array */
+ PyObject *descr; /* NULL or data-description (same as descr key
+ of __array_interface__) -- must set ARR_HAS_DESCR
+ flag or this will be ignored. */
+ } PyArrayInterface;
+
+The flags member may consist of 5 bits showing how the data should be
+interpreted and one bit showing how the Interface should be
+interpreted. The data-bits are :const:`CONTIGUOUS` (0x1),
+:const:`FORTRAN` (0x2), :const:`ALIGNED` (0x100), :const:`NOTSWAPPED`
+(0x200), and :const:`WRITEABLE` (0x400). A final flag
+:const:`ARR_HAS_DESCR` (0x800) indicates whether or not this structure
+has the arrdescr field. The field should not be accessed unless this
+flag is present.
+
.. admonition:: New since June 16, 2006:
In the past most implementations used the "desc" member of the
@@ -216,3 +243,92 @@ array using only one attribute lookup and a well-defined C-structure.
reference to the object when the :ctype:`PyCObject` is created using
:ctype:`PyCObject_FromVoidPtrAndDesc`.
+
+Type description examples
+=========================
+
+For clarity it is useful to provide some examples of the type
+description and corresponding :data:`__array_interface__` 'descr'
+entries. Thanks to Scott Gilbert for these examples:
+
+In every case, the 'descr' key is optional, but of course provides
+more information which may be important for various applications::
+
+ * Float data
+ typestr == '>f4'
+ descr == [('','>f4')]
+
+ * Complex double
+ typestr == '>c8'
+ descr == [('real','>f4'), ('imag','>f4')]
+
+ * RGB Pixel data
+ typestr == '|V3'
+ descr == [('r','|u1'), ('g','|u1'), ('b','|u1')]
+
+ * Mixed endian (weird but could happen).
+ typestr == '|V8' (or '>u8')
+ descr == [('big','>i4'), ('little','<i4')]
+
+ * Nested structure
+ struct {
+ int ival;
+ struct {
+ unsigned short sval;
+ unsigned char bval;
+ unsigned char cval;
+ } sub;
+ }
+ typestr == '|V8' (or '<u8' if you want)
+ descr == [('ival','<i4'), ('sub', [('sval','<u2'), ('bval','|u1'), ('cval','|u1') ]) ]
+
+ * Nested array
+ struct {
+ int ival;
+ double data[16*4];
+ }
+ typestr == '|V516'
+ descr == [('ival','>i4'), ('data','>f8',(16,4))]
+
+ * Padded structure
+ struct {
+ int ival;
+ double dval;
+ }
+ typestr == '|V16'
+ descr == [('ival','>i4'),('','|V4'),('dval','>f8')]
+
+It should be clear that any record type could be described using this interface.
+
+Differences with Array interface (Version 2)
+============================================
+
+The version 2 interface was very similar. The differences were
+largely asthetic. In particular:
+
+1. The PyArrayInterface structure had no descr member at the end
+ (and therefore no flag ARR_HAS_DESCR)
+
+2. The desc member of the PyCObject returned from __array_struct__ was
+ not specified. Usually, it was the object exposing the array (so
+ that a reference to it could be kept and destroyed when the
+ C-object was destroyed). Now it must be a tuple whose first
+ element is a string with "PyArrayInterface Version #" and whose
+ second element is the object exposing the array.
+
+3. The tuple returned from __array_interface__['data'] used to be a
+ hex-string (now it is an integer or a long integer).
+
+4. There was no __array_interface__ attribute instead all of the keys
+ (except for version) in the __array_interface__ dictionary were
+ their own attribute: Thus to obtain the Python-side information you
+ had to access separately the attributes:
+
+ * __array_data__
+ * __array_shape__
+ * __array_strides__
+ * __array_typestr__
+ * __array_descr__
+ * __array_offset__
+ * __array_mask__
+
_______________________________________________
Numpy-discussion mailing list
Numpy-discussion@scipy.org
http://mail.scipy.org/mailman/listinfo/numpy-discussion
