6060
6161The actual representation of values is determined by the machine architecture
6262(strictly speaking, by the C implementation). The actual size can be accessed
63- through the :attr: `itemsize ` attribute.
63+ through the :attr: `array. itemsize
6464
6565The module defines the following item:
6666
@@ -85,161 +85,160 @@ The module defines the following type:
8585 to add initial items to the array. Otherwise, the iterable initializer is
8686 passed to the :meth: `extend ` method.
8787
88- .. audit-event :: array.__new__ typecode,initializer array.array
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.
8993
94+ .. audit-event :: array.__new__ typecode,initializer array.array
9095
91- Array objects support the ordinary sequence operations of indexing, slicing,
92- concatenation, and multiplication. When using slice assignment, the assigned
93- value must be an array object with the same type code; in all other cases,
94- :exc: `TypeError ` is raised. Array objects also implement the buffer interface,
95- and may be used wherever :term: `bytes-like objects <bytes-like object> ` are supported.
9696
97- The following data items and methods are also supported:
97+ .. attribute :: typecode
9898
99- .. attribute :: array.typecode
99+ The typecode character used to create the array.
100100
101- The typecode character used to create the array.
102101
102+ .. attribute :: itemsize
103103
104- .. attribute :: array.itemsize
104+ The length in bytes of one array item in the internal representation.
105105
106- The length in bytes of one array item in the internal representation.
107106
107+ .. method :: append(x)
108108
109- .. method :: array.append(x)
109+ Append a new item with value * x * to the end of the array.
110110
111- Append a new item with value *x * to the end of the array.
112111
112+ .. method :: buffer_info()
113113
114- .. method :: array.buffer_info()
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.
115121
116- Return a tuple ``(address, length) `` giving the current memory address and the
117- length in elements of the buffer used to hold array's contents. The size of the
118- memory buffer in bytes can be computed as ``array.buffer_info()[1] *
119- array.itemsize ``. This is occasionally useful when working with low-level (and
120- inherently unsafe) I/O interfaces that require memory addresses, such as certain
121- :c:func: `ioctl ` operations. The returned numbers are valid as long as the array
122- exists and no length-changing operations are applied to it.
122+ .. note ::
123123
124- .. note ::
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 `.
125129
126- When using array objects from code written in C or C++ (the only way to
127- effectively make use of this information), it makes more sense to use the buffer
128- interface supported by array objects. This method is maintained for backward
129- compatibility and should be avoided in new code. The buffer interface is
130- documented in :ref: `bufferobjects `.
131130
131+ .. method :: byteswap()
132132
133- .. method :: array.byteswap()
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.
134137
135- "Byteswap" all items of the array. This is only supported for values which are
136- 1, 2, 4, or 8 bytes in size; for other types of values, :exc: `RuntimeError ` is
137- raised. It is useful when reading data from a file written on a machine with a
138- different byte order.
139138
139+ .. method :: count(x)
140140
141- .. method :: array.count(x)
141+ Return the number of occurrences of * x * in the array.
142142
143- Return the number of occurrences of *x * in the array.
144143
144+ .. method :: extend(iterable)
145145
146- .. method :: array.extend(iterable)
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.
147150
148- Append items from *iterable * to the end of the array. If *iterable * is another
149- array, it must have *exactly * the same type code; if not, :exc: `TypeError ` will
150- be raised. If *iterable * is not an array, it must be iterable and its elements
151- must be the right type to be appended to the array.
152151
152+ .. method :: frombytes(s)
153153
154- .. method :: array.frombytes(s)
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).
155156
156- Appends items from the string, interpreting the string as an array of machine
157- values (as if it had been read from a file using the :meth: `fromfile ` method) .
157+ .. versionadded :: 3.2
158+ :meth: ` !fromstring ` is renamed to :meth: `frombytes ` for clarity .
158159
159- .. versionadded :: 3.2
160- :meth: `fromstring ` is renamed to :meth: `frombytes ` for clarity.
161160
161+ .. method :: fromfile(f, n)
162162
163- .. method :: array.fromfile(f, n)
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.
164167
165- Read *n * items (as machine values) from the :term: `file object ` *f * and append
166- them to the end of the array. If less than *n * items are available,
167- :exc: `EOFError ` is raised, but the items that were available are still
168- inserted into the array.
169168
169+ .. method :: fromlist(list)
170170
171- .. method :: array.fromlist(list)
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.
172173
173- Append items from the list. This is equivalent to ``for x in list:
174- a.append(x) `` except that if there is a type error, the array is unchanged.
175174
175+ .. method :: fromunicode(s)
176176
177- .. method :: array.fromunicode(s)
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.
178181
179- Extends this array with data from the given unicode string. The array must
180- be a type ``'u' `` array; otherwise a :exc: `ValueError ` is raised. Use
181- ``array.frombytes(unicodestring.encode(enc)) `` to append Unicode data to an
182- array of some other type.
183182
183+ .. method :: index(x[, start[, stop]])
184184
185- .. method :: array.index(x[, start[, stop]])
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.
186189
187- Return the smallest *i * such that *i * is the index of the first occurrence of
188- *x * in the array. The optional arguments *start * and *stop * can be
189- specified to search for *x * within a subsection of the array. Raise
190- :exc: `ValueError ` if *x * is not found.
190+ .. versionchanged :: 3.10
191+ Added optional *start * and *stop * parameters.
191192
192- .. versionchanged :: 3.10
193- Added optional *start * and *stop * parameters.
194193
195- .. method :: array. insert(i, x)
194+ .. method :: insert(i, x)
196195
197- Insert a new item with value *x * in the array before position *i *. Negative
198- values are treated as being relative to the end of the array.
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.
199198
200199
201- .. method :: array. pop([i])
200+ .. method :: pop([i])
202201
203- Removes the item with the index *i * from the array and returns it. The optional
204- argument defaults to ``-1 ``, so that by default the last item is removed and
205- returned.
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.
206205
207206
208- .. method :: array. remove(x)
207+ .. method :: remove(x)
209208
210- Remove the first occurrence of *x * from the array.
209+ Remove the first occurrence of *x * from the array.
211210
212211
213- .. method :: array. reverse()
212+ .. method :: reverse()
214213
215- Reverse the order of the items in the array.
214+ Reverse the order of the items in the array.
216215
217216
218- .. method :: array. tobytes()
217+ .. method :: tobytes()
219218
220- Convert the array to an array of machine values and return the bytes
221- representation (the same sequence of bytes that would be written to a file by
222- the :meth: `tofile ` method.)
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.)
223222
224- .. versionadded ::
E48E
3.2
225- :meth: `tostring ` is renamed to :meth: `tobytes ` for clarity.
223+ .. versionadded :: 3.2
224+ :meth: `! tostring:meth: `tobytes ` for clarity.
226225
227226
228- .. method :: array. tofile(f)
227+ .. method :: tofile(f)
229228
230- Write all items (as machine values) to the :term: `file object ` *f *.
229+ Write all items (as machine values) to the :term: `file object ` *f *.
231230
232231
233- .. method :: array. tolist()
232+ .. method :: tolist()
234233
235- Convert the array to an ordinary list with the same items.
234+ Convert the array to an ordinary list with the same items.
236235
237236
238- .. method :: array. tounicode()
237+ .. method :: tounicode()
239238
240- Convert the array to a unicode string. The array must be a type ``'u' `` array;
241- otherwise a :exc: `ValueError ` is raised. Use ``array.tobytes().decode(enc) `` to
242- obtain a unicode string from an array of some other type.
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.
243242
244243
245244When an array object is printed or converted to a string, it is represented as
0 commit comments