array — efficient arrays of numeric values

array typecodes, overflow, tobytes, and concatenation, with no platform-dependent item sizes in the output, checked on Python 3.13.12.

The array module stores a compact, homogeneous sequence of basic numeric values. The type is chosen by a one-character typecode when the array is created. Examples were checked on Python 3.13.12.

This is not NumPy: there is no broadcasting or elementwise arithmetic. array + array concatenates, and array * n repeats the sequence. Official documentation lists minimum item sizes; the actual itemsize for some typecodes, especially 'i', 'I', 'l', and 'L', depends on the C ABI. The examples print itemsize only for 'B', which is 1 byte, and they use tobytes only with 'B', so the output does not depend on endianness or word size.

Examples were checked against Python 3.13. See the official documentation for the complete API.

Python reference overview →

Typecodes, itemsize, and overflow

class array.array(typecode[, initializer]) builds an array. typecode is the code character; itemsize is the size in bytes of one element on this build. Official minimum sizes include 'b'/'B' at 1, 'h'/'H' at 2, 'q'/'Q' at 8, 'f' at 4, and 'd' at 8. Codes 'i' and 'l' have official minimums of 2 and 4, but the actual width is platform-dependent and is not printed here. 'w' was added in Python 3.13; 'u' is deprecated and will be removed in 3.16.

Values that do not fit the type raise OverflowError. array('B', [256]) and array('b', [128]) both overflow, because unsigned 8-bit values end at 255 and signed 8-bit values end at 127. append, extend, and fromlist follow the same range check.

array.array, array.array.append, array.array.tolist

class array.array(typecode[, initializer])
array.array.typecode
array.array.itemsize
array.array.append(value, /)
array.array.tolist()

Create a typed array, append a value, and convert it to a list.

ParameterDescription
typecodeA single character such as 'B'. array.typecodes lists the codes available in this Python.
initializerOptional bytes, bytearray, Unicode string (for 'u' or 'w'), or iterable of values of the right type.
valueA number that must fit the typecode. Out-of-range values raise OverflowError.

Returns: The constructor returns an array. typecode is a str. itemsize is an int. tolist returns a list. append returns None.

Raises

  • OverflowError — Raised when a value does not fit the type, such as 256 for 'B' or 128 for 'b' on Python 3.13.12.
  • TypeError / ValueError — Raised for a bad typecode, a value of the wrong type, or an initializer the constructor does not accept.
  • Do not treat itemsize of 'i' or 'l' as a portable constant. This example only asserts itemsize for 'B'.
python
import array

b = array.array("B", [0, 255])
print(b.typecode, b.itemsize, b.tolist())
try:
    array.array("B", [256])
except OverflowError:
    print("OverflowError")
try:
    array.array("b", [128])
except OverflowError:
    print("OverflowError")
b.append(1)
print(b.tolist())

Expected output

B 1 [0, 255]
OverflowError
OverflowError
[0, 255, 1]

Official documentation →

Bytes conversion and concatenation

tobytes() returns the native machine representation. frombytes() appends items interpreted the same way. For multi-byte typecodes the byte order follows the platform, so the examples use only 'B', where each item is one byte and endianness does not matter.

Arrays support indexing, slicing, concatenation, and repetition, like lists, but they are not NumPy arrays. array('B', [1, 2]) + array('B', [3]) is array('B', [1, 2, 3]), not elementwise addition. Concatenating arrays with different typecodes raises TypeError. tofile and fromfile are omitted here because they need a file.

array.array.tobytes, array.array.frombytes

array.array.tobytes()
array.array.frombytes(buffer, /)

Convert an 8-bit array to bytes, rebuild one from bytes, and concatenate or repeat arrays.

ParameterDescription
bufferA bytes-like object whose length is a multiple of itemsize. The bytes are interpreted as native machine values.

Returns: tobytes returns bytes. frombytes mutates the array in place and returns None. + and * return a new array.

Raises

  • TypeError — Raised when concatenating arrays whose typecodes differ, such as 'B' and 'b'.
  • fromfile, tofile, and buffer_info are not demonstrated. The first can raise EOFError on a short read, and buffer_info exposes a raw memory address.
python
import array

b = array.array("B", [0, 255, 1])
print(b.tobytes())
c = array.array("B")
c.frombytes(b"\x01\x02")
print(c.tolist())
print(array.array("B", [1, 2]) + array.array("B", [3]))
print(array.array("B", [1, 2]) * 2)
try:
    array.array("B", [1]) + array.array("b", [1])
except TypeError as err:
    print(type(err).__name__)

Expected output

b'\x00\xff\x01'
[1, 2]
array('B', [1, 2, 3])
array('B', [1, 2, 1, 2])
TypeError

Official documentation →