array – Sequence of fixed-type data¶

Purpose:	Manage sequences of fixed-type numerical data efficiently.
Available In:	1.4 and later

The array module defines a sequence data structure that looks very much like a list except that all of the members have to be of the same type. The types supported are all numeric or other fixed-size primitive types such as bytes.

Code	Type	Minimum size (bytes)
`c`	character	1
`b`	int	1
`B`	int	1
`u`	Unicode character	2 or 4 (build-dependent)
`h`	int	2
`H`	int	2
`i`	int	2
`I`	long	2
`l`	int	4
`L`	long	4
`f`	float	4
`d`	float	8

array Initialization¶

An array is instantiated with an argument describing the type of data to be allowed, and possibly an initial sequence of data to store in the array.

import array
import binascii

s = 'This is the array.'
a = array.array('c', s)

print 'As string:', s
print 'As array :', a
print 'As hex   :', binascii.hexlify(a)

In this example, the array is configured to hold a sequence of bytes and is initialized with a simple string.

$ python array_string.py

As string: This is the array.
As array : array('c', 'This is the array.')
As hex   : 54686973206973207468652061727261792e

Manipulating Arrays¶

An array can be extended and otherwise manipulated in the same ways as other Python sequences.

import array

a = array.array('i', xrange(5))
print 'Initial :', a

a.extend(xrange(5))
print 'Extended:', a

print 'Slice   :', a[3:6]

print 'Iterator:', list(enumerate(a))

$ python array_sequence.py

Initial : array('i', [0, 1, 2, 3, 4])
Extended: array('i', [0, 1, 2, 3, 4, 0, 1, 2, 3, 4])
Slice   : array('i', [3, 4, 0])
Iterator: [(0, 0), (1, 1), (2, 2), (3, 3), (4, 4), (5, 0), (6, 1), (7, 2), (8, 3), (9, 4)]

Arrays and Files¶

The contents of an array can be written to and read from files using built-in methods coded efficiently for that purpose.

import array
import binascii
import tempfile

a = array.array('i', xrange(5))
print 'A1:', a

# Write the array of numbers to the file
output = tempfile.NamedTemporaryFile()
a.tofile(output.file) # must pass an *actual* file
output.flush()

# Read the raw data
input = open(output.name, 'rb')
raw_data = input.read()
print 'Raw Contents:', binascii.hexlify(raw_data)

# Read the data into an array
input.seek(0)
a2 = array.array('i')
a2.fromfile(input, len(a))
print 'A2:', a2

This example illustrates reading the data “raw”, directly from the binary file, versus reading it into a new array and converting the bytes to the appropriate types.

$ python array_file.py

A1: array('i', [0, 1, 2, 3, 4])
Raw Contents: 0000000001000000020000000300000004000000
A2: array('i', [0, 1, 2, 3, 4])

Alternate Byte Ordering¶

If the data in the array is not in the native byte order, or needs to be swapped before being written to a file intended for a system with a different byte order, it is easy to convert the entire array without iterating over the elements from Python.

import array
import binascii

def to_hex(a):
    chars_per_item = a.itemsize * 2 # 2 hex digits
    hex_version = binascii.hexlify(a)
    num_chunks = len(hex_version) / chars_per_item
    for i in xrange(num_chunks):
        start = i*chars_per_item
        end = start + chars_per_item
        yield hex_version[start:end]

a1 = array.array('i', xrange(5))
a2 = array.array('i', xrange(5))
a2.byteswap()

fmt = '%10s %10s %10s %10s'
print fmt % ('A1 hex', 'A1', 'A2 hex', 'A2')
print fmt % (('-' * 10,) * 4)
for values in zip(to_hex(a1), a1, to_hex(a2), a2):
    print fmt % values

$ python array_byteswap.py

    A1 hex         A1     A2 hex         A2
---------- ---------- ---------- ----------
  00000000          0   00000000          0
  01000000          1   00000001   16777216
  02000000          2   00000002   33554432
  03000000          3   00000003   50331648
  04000000          4   00000004   67108864

PyMOTW

Page Contents

Navigation

This Page

Examples