struct — empacotar e desempacotar tipos de dados primitivos

Este módulo realiza conversões entre valores Python e structs no estilo C representados como objetos bytes do Python, usando strings de formato para descrever o layout dos dados.

São suportadas as seguintes ordens de bytes:

Caráter	Ordem de bytes	Tamanho	Alinhamento
@	nativo	nativo	nativo
<	little-endian	padrão	nenhum
>	big-endian	padrão	nenhum
!	rede (= big-endian)	padrão	nenhum

São suportados os seguintes tipos de dados:

Formato	Tipo C	Tipo Python	Tamanho padrão
b	signed char	inteiro	1
B	unsigned char	inteiro	1
h	short	inteiro	2
H	unsigned short	inteiro	2
i	int	integer (1)	4
I	unsigned int	integer (1)	4
l	long	integer (1)	4
L	unsigned long	integer (1)	4
q	long long	integer (1)	8
Q	unsigned long long	integer (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 *	inteiro

1. Requer suporte a long quando utilizado com valores maiores que 30 bits.

2. Requer suporte a vírgula flutuante.

Diferença em relação ao CPython

Espaços em branco não são suportados em strings de formato.

Exemplos

Empacotar e desempacotar valores little-endian. O prefixo < seleciona a ordem de bytes little-endian com tamanhos padrão e sem alinhamento:

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

Empacotar num buffer existente e desempacotar a partir dele com um deslocamento de byte:

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,)

Funções

struct.calcsize(fmt: str) → int

Devolve o número de bytes necessários para armazenar o dado fmt.

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

Empacota os values de acordo com a string de formato fmt. O valor de retorno é um objeto bytes que codifica os valores.

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

Empacota os values de acordo com a string de formato fmt num buffer a partir de offset. offset pode ser negativo para contar a partir do fim do buffer.

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

Desempacota a partir de data de acordo com a string de formato fmt. O valor de retorno é um tuplo dos valores desempacotados.

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

Desempacota a partir de data começando em offset de acordo com a string de formato fmt. offset pode ser negativo para contar a partir do fim de data. O valor de retorno é um tuplo dos valores desempacotados.