1:mod:`array` --- Efficient arrays of numeric values
2===================================================
3
4.. module:: array
5   :synopsis: Space efficient arrays of uniformly typed numeric values.
6
7.. index:: single: arrays
8
9--------------
10
11This module defines an object type which can compactly represent an array of
12basic values: characters, integers, floating point numbers.  Arrays are sequence
13types and behave very much like lists, except that the type of objects stored in
14them is constrained.  The type is specified at object creation time by using a
15:dfn:`type code`, which is a single character.  The following type codes are
16defined:
17
18+-----------+--------------------+-------------------+-----------------------+-------+
19| Type code | C Type             | Python Type       | Minimum size in bytes | Notes |
20+===========+====================+===================+=======================+=======+
21| ``'b'``   | signed char        | int               | 1                     |       |
22+-----------+--------------------+-------------------+-----------------------+-------+
23| ``'B'``   | unsigned char      | int               | 1                     |       |
24+-----------+--------------------+-------------------+-----------------------+-------+
25| ``'u'``   | wchar_t            | Unicode character | 2                     | \(1)  |
26+-----------+--------------------+-------------------+-----------------------+-------+
27| ``'h'``   | signed short       | int               | 2                     |       |
28+-----------+--------------------+-------------------+-----------------------+-------+
29| ``'H'``   | unsigned short     | int               | 2                     |       |
30+-----------+--------------------+-------------------+-----------------------+-------+
31| ``'i'``   | signed int         | int               | 2                     |       |
32+-----------+--------------------+-------------------+-----------------------+-------+
33| ``'I'``   | unsigned int       | int               | 2                     |       |
34+-----------+--------------------+-------------------+-----------------------+-------+
35| ``'l'``   | signed long        | int               | 4                     |       |
36+-----------+--------------------+-------------------+-----------------------+-------+
37| ``'L'``   | unsigned long      | int               | 4                     |       |
38+-----------+--------------------+-------------------+-----------------------+-------+
39| ``'q'``   | signed long long   | int               | 8                     |       |
40+-----------+--------------------+-------------------+-----------------------+-------+
41| ``'Q'``   | unsigned long long | int               | 8                     |       |
42+-----------+--------------------+-------------------+-----------------------+-------+
43| ``'f'``   | float              | float             | 4                     |       |
44+-----------+--------------------+-------------------+-----------------------+-------+
45| ``'d'``   | double             | float             | 8                     |       |
46+-----------+--------------------+-------------------+-----------------------+-------+
47
48Notes:
49
50(1)
51   It can be 16 bits or 32 bits depending on the platform.
52
53   .. versionchanged:: 3.9
54      ``array('u')`` now uses ``wchar_t`` as C type instead of deprecated
55      ``Py_UNICODE``. This change doesn't affect its behavior because
56      ``Py_UNICODE`` is alias of ``wchar_t`` since Python 3.3.
57
58   .. deprecated-removed:: 3.3 4.0
59
60
61The actual representation of values is determined by the machine architecture
62(strictly speaking, by the C implementation).  The actual size can be accessed
63through the :attr:`array.itemsize` attribute.
64
65The module defines the following item:
66
67
68.. data:: typecodes
69
70   A string with all available type codes.
71
72
73The module defines the following type:
74
75
76.. class:: array(typecode[, initializer])
77
78   A new array whose items are restricted by *typecode*, and initialized
79   from the optional *initializer* value, which must be a list, a
80   :term:`bytes-like object`, or iterable over elements of the
81   appropriate type.
82
83   If given a list or string, the initializer is passed to the new array's
84   :meth:`fromlist`, :meth:`frombytes`, or :meth:`fromunicode` method (see below)
85   to add initial items to the array.  Otherwise, the iterable initializer is
86   passed to the :meth:`extend` method.
87
88   Array objects support the ordinary sequence operations of indexing, slicing,
89   concatenation, and multiplication.  When using slice assignment, the assigned
90   value must be an array object with the same type code; in all other cases,
91   :exc:`TypeError` is raised. Array objects also implement the buffer interface,
92   and may be used wherever :term:`bytes-like objects <bytes-like object>` are supported.
93
94   .. audit-event:: array.__new__ typecode,initializer array.array
95
96
97   .. attribute:: typecode
98
99      The typecode character used to create the array.
100
101
102   .. attribute:: itemsize
103
104      The length in bytes of one array item in the internal representation.
105
106
107   .. method:: append(x)
108
109      Append a new item with value *x* to the end of the array.
110
111
112   .. method:: buffer_info()
113
114      Return a tuple ``(address, length)`` giving the current memory address and the
115      length in elements of the buffer used to hold array's contents.  The size of the
116      memory buffer in bytes can be computed as ``array.buffer_info()[1] *
117      array.itemsize``.  This is occasionally useful when working with low-level (and
118      inherently unsafe) I/O interfaces that require memory addresses, such as certain
119      :c:func:`!ioctl` operations.  The returned numbers are valid as long as the array
120      exists and no length-changing operations are applied to it.
121
122      .. note::
123
124         When using array objects from code written in C or C++ (the only way to
125         effectively make use of this information), it makes more sense to use the buffer
126         interface supported by array objects.  This method is maintained for backward
127         compatibility and should be avoided in new code.  The buffer interface is
128         documented in :ref:`bufferobjects`.
129
130
131   .. method:: byteswap()
132
133      "Byteswap" all items of the array.  This is only supported for values which are
134      1, 2, 4, or 8 bytes in size; for other types of values, :exc:`RuntimeError` is
135      raised.  It is useful when reading data from a file written on a machine with a
136      different byte order.
137
138
139   .. method:: count(x)
140
141      Return the number of occurrences of *x* in the array.
142
143
144   .. method:: extend(iterable)
145
146      Append items from *iterable* to the end of the array.  If *iterable* is another
147      array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
148      be raised.  If *iterable* is not an array, it must be iterable and its elements
149      must be the right type to be appended to the array.
150
151
152   .. method:: frombytes(s)
153
154      Appends items from the string, interpreting the string as an array of machine
155      values (as if it had been read from a file using the :meth:`fromfile` method).
156
157      .. versionadded:: 3.2
158         :meth:`!fromstring` is renamed to :meth:`frombytes` for clarity.
159
160
161   .. method:: fromfile(f, n)
162
163      Read *n* items (as machine values) from the :term:`file object` *f* and append
164      them to the end of the array.  If less than *n* items are available,
165      :exc:`EOFError` is raised, but the items that were available are still
166      inserted into the array.
167
168
169   .. method:: fromlist(list)
170
171      Append items from the list.  This is equivalent to ``for x in list:
172      a.append(x)`` except that if there is a type error, the array is unchanged.
173
174
175   .. method:: fromunicode(s)
176
177      Extends this array with data from the given unicode string.  The array must
178      be a type ``'u'`` array; otherwise a :exc:`ValueError` is raised.  Use
179      ``array.frombytes(unicodestring.encode(enc))`` to append Unicode data to an
180      array of some other type.
181
182
183   .. method:: index(x[, start[, stop]])
184
185      Return the smallest *i* such that *i* is the index of the first occurrence of
186      *x* in the array.  The optional arguments *start* and *stop* can be
187      specified to search for *x* within a subsection of the array.  Raise
188      :exc:`ValueError` if *x* is not found.
189
190      .. versionchanged:: 3.10
191         Added optional *start* and *stop* parameters.
192
193
194   .. method:: insert(i, x)
195
196      Insert a new item with value *x* in the array before position *i*. Negative
197      values are treated as being relative to the end of the array.
198
199
200   .. method:: pop([i])
201
202      Removes the item with the index *i* from the array and returns it. The optional
203      argument defaults to ``-1``, so that by default the last item is removed and
204      returned.
205
206
207   .. method:: remove(x)
208
209      Remove the first occurrence of *x* from the array.
210
211
212   .. method:: reverse()
213
214      Reverse the order of the items in the array.
215
216
217   .. method:: tobytes()
218
219      Convert the array to an array of machine values and return the bytes
220      representation (the same sequence of bytes that would be written to a file by
221      the :meth:`tofile` method.)
222
223      .. versionadded:: 3.2
224         :meth:`!tostring` is renamed to :meth:`tobytes` for clarity.
225
226
227   .. method:: tofile(f)
228
229      Write all items (as machine values) to the :term:`file object` *f*.
230
231
232   .. method:: tolist()
233
234      Convert the array to an ordinary list with the same items.
235
236
237   .. method:: tounicode()
238
239      Convert the array to a unicode string.  The array must be a type ``'u'`` array;
240      otherwise a :exc:`ValueError` is raised. Use ``array.tobytes().decode(enc)`` to
241      obtain a unicode string from an array of some other type.
242
243
244When an array object is printed or converted to a string, it is represented as
245``array(typecode, initializer)``.  The *initializer* is omitted if the array is
246empty, otherwise it is a string if the *typecode* is ``'u'``, otherwise it is a
247list of numbers.  The string is guaranteed to be able to be converted back to an
248array with the same type and value using :func:`eval`, so long as the
249:class:`~array.array` class has been imported using ``from array import array``.
250Examples::
251
252   array('l')
253   array('u', 'hello \u2641')
254   array('l', [1, 2, 3, 4, 5])
255   array('d', [1.0, 2.0, 3.14])
256
257
258.. seealso::
259
260   Module :mod:`struct`
261      Packing and unpacking of heterogeneous binary data.
262
263   Module :mod:`xdrlib`
264      Packing and unpacking of External Data Representation (XDR) data as used in some
265      remote procedure call systems.
266
267   `NumPy <https://numpy.org/>`_
268      The NumPy package defines another array type.
269
270