8.7. array — Tableaux efficaces de valeurs numériques

Ce module définit un type d’objet qui permet de représenter de façon compacte un tableau (array) de valeurs élémentaires : caractères, entiers, flottants. Les tableaux sont de type séquence et se comportent de manière très similaire aux listes, sauf que les types d’objets qui y sont stockés sont limités. Le type est spécifié au moment de la création de l’objet en utilisant type code, qui est un caractère unique. Voir ci-dessous pour la définition des types :

Code d’indication du type Type C Type Python Taille minimum en octets Notes
'b' signed char int 1  
'B' unsigned char int 1  
'u' Py_UNICODE Caractère Unicode 2 (1)
'h' signed short int 2  
'H' unsigned short int 2  
'i' signed int int 2  
'I' unsigned int int 2  
'l' signed long int 4  
'L' unsigned long int 4  
'q' signed long long int 8 (2)
'Q' unsigned long long int 8 (2)
'f' float float 4  
'd' double float 8  

Notes :

  1. Le code de type 'u' correspond au type obsolète de Python caractère Unicode (Py_UNICODE de type wchar_t). Selon la plateforme, il peut être 16 bits ou 32 bits.

    'u' sera supprimé avec le reste de l’API Py_UNICODE.

    Deprecated since version 3.3, will be removed in version 4.0.

  2. Les codes de type 'q' et 'Q' ne sont disponibles que si le compilateur C de la plateforme utilisé pour construire Python gère le type C long long, ou, sur Windows, __int64.

    Nouveau dans la version 3.3.

La représentation réelle des valeurs est déterminée par l’architecture de la machine (à proprement parler, par l’implémentation C). La taille réelle est accessible via l’attribut itemsize.

Le module définit le type suivant :

class array.array(typecode[, initializer])

Un nouveau tableau dont les éléments sont limités par typecode, et initialisés par la valeur optionnelle initializer, qui peut être une liste, un bytes-like object, ou un itérable sur des éléments du type approprié.

Si le paramètre initializer est une liste ou une chaîne de caractères, il est passé à la méthode fromlist(), frombytes() ou fromunicode() du tableau (voir ci-dessous) pour ajouter les éléments initiaux du tableau. Si c’est un itérable, il est passé à la méthode extend().

array.typecodes

Une chaîne avec tous les codes de types disponibles.

Les objets de tableau supportent les opérations classiques de séquence : indiçage, découpage, concaténation et multiplication. Lors de l’utilisation de tranche, la valeur assignée doit être un tableau du même type ; dans tous les autres cas, l’exception TypeError est levée. Les objets de tableau implémentent également l’interface tampon, et peuvent être utilisés partout où bytes-like objects sont supportés.

Les éléments de données et méthodes suivants sont également supportés :

array.typecode

Le code (de type Python caractère) utilisé pour spécifier le type des éléments du tableau.

array.itemsize

La longueur en octets d’un élément du tableau dans la représentation interne.

array.append(x)

Ajoute un nouvel élément avec la valeur x à la fin du tableau.

array.buffer_info()

Renvoie un tuple (address, length) indiquant l’adresse mémoire courante et la longueur en éléments du tampon utilisé pour contenir le contenu du tableau. La taille du tampon mémoire en octets peut être calculée par array.buffer_info()[1] * array.itemsize. Ceci est parfois utile lorsque vous travaillez sur des interfaces E/S de bas niveau (et intrinsèquement dangereuses) qui nécessitent des adresses mémoire, telles que certaines opérations ioctl(). Les nombres renvoyés sont valides tant que le tableau existe et qu’aucune opération qui modifie sa taille ne lui est appliquée.

Note

Lors de l’utilisation d’objets tableaux provenant de codes écrits en C ou C++ (le seul moyen d’utiliser efficacement ces informations), il est plus logique d’utiliser l’interface tampon supportée par les objets tableaux. Cette méthode est maintenue pour des raisons de rétrocompatibilité et devrait être évitée dans un nouveau code. L’interface tampon est documentée dans Protocole tampon.

array.byteswap()

Boutisme de tous les éléments du tableau. Ceci n’est pris en charge que pour les valeurs de 1, 2, 4 ou 8 octets ; pour les autres types de valeur, RuntimeError est levée. Il est utile lors de la lecture de données à partir d’un fichier écrit sur une machine avec un ordre d’octets différent.

array.count(x)

Renvoi le nombre d’occurrences de x dans le tableau.

array.extend(iterable)

Ajoute les éléments de iterable à la fin du tableau. Si iterable est un autre tableau, il doit le même code d’indication du type ; dans le cas contraire, TypeError sera levée. Si iterable n’est pas un tableau, il doit être itérable et ces éléments doivent être du bon type pour être ajoutés dans le tableau.

array.frombytes(s)

Ajoute des éléments de la chaîne, interprétant la chaîne comme un tableau de valeurs machine (comme si elle avait été lue depuis le fichier en utilisant la méthode from file()).

Nouveau dans la version 3.2: fromstring() est renommée en frombytes() pour plus de lisibilité.

array.fromfile(f, n)

Lit n éléments (en tant que valeurs machine) du file object f et les ajouter à la fin du tableau. Si moins de n éléments sont disponibles, EOFError est levée, mais les éléments qui étaient disponibles sont tout de même insérés dans le tableau. f doit être un objet fichier natif ; quelque chose d’autre avec une méthode read() ne suffit pas.

array.fromlist(list)

Ajoute les éléments de la liste. C’est l’équivalent de for x in list: a.append(x) sauf que s’il y a une erreur de type, le tableau est inchangé.

array.fromstring()

Alias obsolète de frombytes().

array.fromunicode(s)

Étend ce tableau avec les données de la chaîne Unicode donnée. Le tableau doit être de type 'u' ; sinon ValueError est levée. Utiliser array.frombytes(unicodestring.encode(enc)) pour ajouter des données Unicode à un tableau d’un autre type.

array.index(x)

Renvoie le plus petit i tel que i est l’index de la première occurrence de x dans le tableau.

array.insert(i, x)

Ajoute un nouvel élément avec la valeur x dans le tableau avant la position i. Les valeurs négatives sont traitées relativement à la fin du tableau.

array.pop([i])

Supprime l’élément du tableau avec l’index i et le renvoie. L’argument optionnel par défaut est à -1, de sorte que par défaut le dernier élément est supprimé et renvoyé.

array.remove(x)

Supprime la première occurrence de x du tableau.

array.reverse()

Inverse l’ordre des éléments du tableau.

array.tobytes()

Convertit le tableau en un tableau de valeurs machine et renvoie la représentation en octets (la même séquence d’octets qui serait écrite par la méthode tofile()).

Nouveau dans la version 3.2: tostring() est renommé en tobytes() pour plus de lisibilité.

array.tofile(f)

Écrit tous les éléments (en tant que valeurs machine) du file object f.

array.tolist()

Convertit le tableau en une liste ordinaire avec les mêmes éléments.

array.tostring()

Alias obsolète de tobytes().

array.tounicode()

Convertit le tableau en une chaîne Unicode. Le tableau doit être un tableau de type 'u' ; sinon ValueError est levée. Utilisez array.tobytes().decode(enc) pour obtenir une chaîne Unicode depuis un tableau de tout autre type.

When an array object is printed or converted to a string, it is represented as array(typecode, initializer). The initializer is omitted if the array is empty, otherwise it is a string if the typecode is 'u', otherwise it is a list of numbers. The string is guaranteed to be able to be converted back to an array with the same type and value using eval(), so long as the array class has been imported using from array import array. Examples:

array('l')
array('u', 'hello \u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])

Voir aussi

Module struct
Empaquetage et dépaquetage de données binaires hétérogènes.
Module xdrlib
Empaquetage et dépaquetage des données XDR (External Data Representation) telles qu’elles sont utilisées dans certains systèmes d’appels de procédures à distance (ou RPC pour remote procedure call en anglais).
The Numerical Python Documentation
L’extension Numeric Python (NumPy) définit un autre type de tableau ; voir http://www.numpy.org/ pour plus d’informations sur Numeric Python.