1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
.. index::
pair: array; interface
pair: array; protocol
.. _arrays.interface:
*******************
The Array Interface
*******************
:version: 3
The array interface (sometimes called array protocol) was created in
2005 as a means for array-like Python objects to re-use each other's
data buffers intelligently whenever possible. The homogeneous
N-dimensional array interface is a default mechanism for objects to
share N-dimensional array memory and information. The interface
consists of a Python-side and a C-side using two attributes. Objects
wishing to be considered an N-dimensional array in application code
should support at least one of these attributes. Objects wishing to
support an N-dimensional array in application code should look for at
least one of these attributes and use the information provided
appropriately.
This interface describes homogeneous arrays in the sense that each
item of the array has the same "type". This type can be very simple
or it can be a quite arbitrary and complicated C-like structure.
There are two ways to use the interface: A Python side and a C-side.
Both are separate attributes.
.. note::
An alternative to the array interface;
:cfunc:`The Revised Buffer Protocol <PyObject_GetBuffer>`, :pep:`3118`
is introduced in Python 2.6.
Python side
===========
This approach to the interface consists of the object having an
:data:`__array_interface__` attribute.
.. data:: __array_interface__
A dictionary of items (3 required and 5 optional). The optional
keys in the dictionary have implied defaults if they are not
provided.
The keys are:
**shape** (required)
Tuple whose elements are the array 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 code
using this attribute to handle this appropriately; either by
raising an error when overflow is possible, or by using
:cdata:`Py_LONG_LONG` as the C type for the shapes.
**typestr** (required)
A string providing the basic type of the homogenous array The
basic string format consists of 3 parts: a character describing
the byteorder of the data (``<``: little-endian, ``>``:
big-endian, ``|``: not-relevant), a character code giving the
basic type of the array, and an integer providing the number of
bytes the type uses.
The basic type character codes are:
===== ================================================================
``t`` Bit field (following integer gives the number of
bits in the bit field).
``b`` Boolean (integer type where all values are only True or False)
``i`` Integer
``u`` Unsigned integer
``f`` Floating point
``c`` Complex floating point
``O`` Object (i.e. the memory contains a pointer to :ctype:`PyObject`)
``S`` String (fixed-length sequence of char)
``U`` Unicode (fixed-length sequence of :ctype:`Py_UNICODE`)
``V`` Other (void \* -- each item is a fixed-size chunk of memory)
===== ================================================================
**descr** (optional)
A list of tuples providing a more detailed description of the
memory layout for each item in the homogeneous array. Each
tuple in the list has two or three elements. Normally, this
attribute would be used when *typestr* is ``V[0-9]+``, but this is
not a requirement. The only requirement is that the number of
bytes represented in the *typestr* key is the same as the total
number of bytes represented here. The idea is to support
descriptions of C-like structs (records) that make up array
elements. The elements of each tuple in the list are
1. A string providing a name associated with this portion of
the record. This could also be a tuple of ``('full name',
'basic_name')`` where basic name would be a valid Python
variable name representing the full name of the field.
2. Either a basic-type description string as in *typestr* or
another list (for nested records)
3. An optional shape tuple providing how many times this part
of the record should be repeated. No repeats are assumed
if this is not given. Very complicated structures can be
described using this generic interface. Notice, however,
that each element of the array is still of the same
data-type. Some examples of using this interface are given
below.
**Default**: ``[('', typestr)]``
**data** (optional)
A 2-tuple whose first argument is an integer (a long integer
if necessary) that points to the data-area storing the array
contents. This pointer must point to the first element of
data (in other words any offset is always ignored in this
case). The second entry in the tuple is a read-only flag (true
means the data area is read-only).
This attribute can also be an object exposing the
:cfunc:`buffer interface <PyObject_AsCharBuffer>` which
will be used to share the data. If this key is not present (or
returns :class:`None`), then memory sharing will be done
through the buffer interface of the object itself. In this
case, the offset key can be used to indicate the start of the
buffer. A reference to the object exposing the array interface
must be stored by the new object if the memory area is to be
secured.
**Default**: :const:`None`
**strides** (optional)
Either :const:`None` to indicate a C-style contiguous array or
a Tuple of strides which provides the number of bytes needed
to jump to the next array element in the corresponding
dimension. Each entry must be an integer (a Python
:const:`int` or :const:`long`). As with 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 :ctype:`Py_LONG_LONG` in C. The
default is :const:`None` which implies a C-style contiguous
memory buffer. In this model, the last dimension of the array
varies the fastest. For example, the default strides tuple
for an object whose array entries are 8 bytes long and whose
shape is (10,20,30) would be (4800, 240, 8)
**Default**: :const:`None` (C-style contiguous)
**mask** (optional)
:const:`None` or an object exposing the array interface. All
elements of the mask array should be interpreted only as true
or not true indicating which elements of this array are valid.
The shape of this object should be `"broadcastable"
<arrays.broadcasting.broadcastable>` to the shape of the
original array.
**Default**: :const:`None` (All array values are valid)
**offset** (optional)
An integer offset into the array data region. This can only be
used when data is :const:`None` or returns a :class:`buffer`
object.
**Default**: 0.
**version** (required)
An integer showing the version of the interface (i.e. 3 for
this version). Be careful not to use this to invalidate
objects exposing future versions of the interface.
C-struct access
===============
This approach to the array interface allows for faster access to an
array using only one attribute lookup and a well-defined C-structure.
.. cvar:: __array_struct__
A :ctype:`PyCObject` whose :cdata:`voidptr` member contains a
pointer to a filled :ctype:`PyArrayInterface` structure. Memory
for the structure is dynamically created and the :ctype:`PyCObject`
is also created with an appropriate destructor so the retriever of
this attribute simply has to apply :cfunc:`Py_DECREF()` to the
object returned by this attribute when it is finished. Also,
either the data needs to be copied out, or a reference to the
object exposing this attribute must be held to ensure the data is
not freed. Objects exposing the :obj:`__array_struct__` interface
must also not reallocate their memory if other objects are
referencing them.
.. admonition:: New since June 16, 2006:
In the past most implementations used the "desc" member of the
:ctype:`PyCObject` itself (do not confuse this with the "descr" member of
the :ctype:`PyArrayInterface` structure above --- they are two separate
things) to hold the pointer to the object exposing the interface.
This is now an explicit part of the interface. Be sure to own a
reference to the object when the :ctype:`PyCObject` is created using
:ctype:`PyCObject_FromVoidPtrAndDesc`.
|
