struct — empaqueter et désempaqueter des types de données primitifs

Ce module effectue des conversions entre des valeurs Python et des structures de style C représentées sous forme d’objets bytes Python, en utilisant des chaînes de format pour décrire la disposition des données.

Les ordres d’octets suivants sont pris en charge :

Caractère	Ordre des octets	Taille	Alignement
@	natif	natif	natif
<	petit-boutiste	standard	aucun
>	gros-boutiste	standard	aucun
!	réseau (= gros-boutiste)	standard	aucun

Les types de données suivants sont pris en charge :

Format	Type C	Type Python	Taille standard
b	signed char	entier	1
B	unsigned char	entier	1
h	short	entier	2
H	unsigned short	entier	2
i	int	entier (1)	4
I	unsigned int	entier (1)	4
l	long	entier (1)	4
L	unsigned long	entier (1)	4
q	long long	entier (1)	8
Q	unsigned long long	entier (1)	8
e	n/a (half-float)	float (2)	2
f	float	float (2)	4
d	double	float (2)	8
s	char[]	bytes
P	void *	entier

1. Nécessite la prise en charge des entiers longs lorsqu’il est utilisé avec des valeurs supérieures à 30 bits.

2. Nécessite la prise en charge des nombres à virgule flottante.

Différence avec CPython

Les espaces ne sont pas pris en charge dans les chaînes de format.

Exemples

Empaqueter et désempaqueter des valeurs petit-boutistes. Le préfixe < sélectionne l’ordre d’octets petit-boutiste avec des tailles standard et sans alignement

import struct

# Pack an unsigned short (H, 2 bytes) then an unsigned int (I, 4 bytes).
data = struct.pack("<HI", 7, 1000)
# data == b'\x07\x00\xe8\x03\x00\x00'

# Unpack returns a tuple of the values, in order.
struct.unpack("<HI", data)
# (7, 1000)

# calcsize() reports how many bytes the format needs.
struct.calcsize("<HI")
# 6

Empaqueter dans un tampon existant et désempaqueter depuis celui-ci à un décalage en octets

buf = bytearray(8)

# Write a little-endian signed int (i) at offset 2.
struct.pack_into("<i", buf, 2, -12345)
# buf == bytearray(b'\x00\x00\xc7\xcf\xff\xff\x00\x00')

# Read it back from the same offset.
struct.unpack_from("<i", buf, 2)
# (-12345,)

Fonctions

struct.calcsize(fmt: str) → int

Renvoie le nombre d’octets nécessaires pour stocker le fmt donné.

struct.pack(fmt: str, *values: Any) → bytes

Empaquette les values selon la chaîne de format fmt. La valeur de retour est un objet bytes encodant les valeurs.

struct.pack_into(fmt: str, buffer: Any, offset: int, *values: Any) → None

Empaquette les values selon la chaîne de format fmt dans un buffer en commençant à offset. offset peut être négatif pour compter à partir de la fin de buffer.

struct.unpack(fmt: str, data: bytes) → Tuple

Désempaquette depuis data selon la chaîne de format fmt. La valeur de retour est un tuple des valeurs désempaquetées.

struct.unpack_from(fmt: str, data: bytes, offset: int = 0, /) → Tuple

Désempaquette depuis data en commençant à offset selon la chaîne de format fmt. offset peut être négatif pour compter à partir de la fin de data. La valeur de retour est un tuple des valeurs désempaquetées.