struct — pack and unpack primitive data types

This module performs conversions between Python values and C-style structs represented as Python bytes objects, using format strings to describe the layout of the data.

The following byte orders are supported:

Character	Byte order	Size	Alignment
@	native	native	native
<	little-endian	standard	none
>	big-endian	standard	none
!	network (= big-endian)	standard	none

The following data types are supported:

Format	C Type	Python type	Standard size
b	signed char	integer	1
B	unsigned char	integer	1
h	short	integer	2
H	unsigned short	integer	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 *	integer

1. Requires long support when used with values larger than 30 bits.

2. Requires floating point support.

Difference to CPython

Whitespace is not supported in format strings.

Examples

Pack and unpack little-endian values. The < prefix selects little-endian byte order with standard sizes and no alignment:

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

Pack into and unpack from an existing buffer at a byte offset:

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

Functions

struct.calcsize(fmt: str) → int

Return the number of bytes needed to store the given fmt.

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

Pack the values according to the format string fmt. The return value is a bytes object encoding the values.

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

Pack the values according to the format string fmt into a buffer starting at offset. offset may be negative to count from the end of buffer.

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

Unpack from the data according to the format string fmt. The return value is a tuple of the unpacked values.

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

Unpack from the data starting at offset according to the format string fmt. offset may be negative to count from the end of data. The return value is a tuple of the unpacked values.