struct --- プリミティブデータ型のパックとアンパック

このモジュールは、データのレイアウトを記述する書式文字列を使用して、Python の値と、Python の bytes オブジェクトとして表される C 形式の構造体との間の変換を行います。

以下のバイトオーダーがサポートされています:

文字	バイトオーダー	サイズ	アライメント
@	ネイティブ	ネイティブ	ネイティブ
<	リトルエンディアン	標準	なし
>	ビッグエンディアン	標準	なし
!	ネットワーク（= ビッグエンディアン）	標準	なし

以下のデータ型がサポートされています:

書式	C 型	Python 型	標準サイズ
b	signed char	整数	1
B	unsigned char	整数	1
h	short	整数	2
H	unsigned short	整数	2
i	int	整数 (1)	4
I	unsigned int	整数 (1)	4
l	long	整数 (1)	4
L	unsigned long	整数 (1)	4
q	long long	整数 (1)	8
Q	unsigned long long	整数 (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 *	整数

1. 30 ビットより大きい値とともに使用する場合は long のサポートが必要です。

2. 浮動小数点のサポートが必要です。

CPython との相違点

書式文字列では空白はサポートされていません。

例

リトルエンディアンの値のパックとアンパック。< 接頭辞は、標準サイズかつアライメントなしのリトルエンディアンバイトオーダーを選択します:

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

既存のバッファのバイトオフセット位置へのパックおよびそこからのアンパック:

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

関数

struct.calcsize(fmt: str) → int

指定された fmt を格納するのに必要なバイト数を返します。

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

書式文字列 fmt に従って values をパックします。戻り値は、値をエンコードした bytes オブジェクトです。

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

書式文字列 fmt に従って、values を buffer の offset から始まる位置にパックします。offset は負の値にすることができ、その場合は buffer の末尾からの位置を表します。

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

書式文字列 fmt に従って data からアンパックします。戻り値は、アンパックされた値のタプルです。

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

書式文字列 fmt に従って、data の offset から始まる位置からアンパックします。offset は負の値にすることができ、その場合は data の末尾からの位置を表します。戻り値は、アンパックされた値のタプルです。