7.1. struct — 字节码与二进制数据之间的转换

源代码： Lib/struct.py

该模块执行Python值和以Python bytes表示的C结构体之间的转换。这可以用于处理存储在文件中或来自网络连接以及其他源的二进制数据。它使用一定格式的字符串作为C语言结构布局的简洁描述以及到或从Python值的预期转换。

注意

默认情况下，封装给定C结构的结果包括填充字节，以便为所涉及的C类型保持适当的对齐；类似地，当分离时考虑对准。选择此行为以使打包结构的字节完全对应于C结构在存储器中的布局。要处理平台无关的数据格式或省略隐式填充字节，请使用标准大小和对齐而不是原生大小和对齐方式：请参阅字节顺序，大小和对齐了解详情。

几个struct函数（和Struct的方法）接受一个缓冲参数。这是指实现Buffer Protocol并提供可读或可读写缓冲区的对象。用于该目的的最常见类型是bytes和bytearray，但是可以看作是字节数组的许多其他类型实现缓冲区协议，因此它们可以读/填充，而不需要从bytes对象进行附加复制。

7.1.1.函数和异常

该模块定义了以下异常和函数：

exception struct.error

在各种场合提出异议；参数是描述错误的字符串。

struct.pack(fmt, v1, v2, ...)

返回一个字节对象包含值v1, v2， ... ，根据格式字符串 fmt 进行pack。参数必须与格式所需的值完全匹配。

struct.pack_into(fmt, buffer, offset, v1, v2, ...)

根据格式字符串fmt封装值v1，v2，并将压缩字节写入可写缓冲区缓冲区从位置偏移开始。请注意，offset是必需的参数。

struct.unpack(fmt, buffer)

根据格式字符串 fmt 从缓冲区 buffer unpack（假设缓冲区由 pack(fmt, ...) 进行pack）。结果是一个元组，即使它只包含一个元素。缓冲区的大小（以字节为单位）必须与格式所需的大小匹配，如calcsize()所反映。

struct.unpack_from(fmt, buffer, offset=0)

根据格式字符串fmt从缓冲区开始分离偏移。结果是一个元组，即使它只包含一个项目。缓冲区的大小（以字节为单位，减去offset）必须至少为格式所需的大小，如calcsize()所示。

struct.iter_unpack(fmt, buffer)

根据格式字符串fmt从缓冲区缓冲区中迭代分离。此函数返回一个迭代器，它将从缓冲区读取大小相等的块，直到其所有内容都已用完。缓冲区的大小（以字节为单位）必须是格式所需大小的倍数，如calcsize()所反映。

每次迭代产生由格式字符串指定的元组。

版本3.4中的新功能。

struct.calcsize(fmt)

返回对应于格式字符串的结构（以及由此产生的pack（fmt， ...））的字节对象的大小fmt。

7.1.2.格式字符串

格式字符串是用于在封装和分拆数据时指定预期布局的机制。它们由Format Characters构成，它指定正在打包/解包的数据类型。此外，还有一些特殊字符用于控制Byte Order, Size, and Alignment。

7.1.2.1.字节顺序，大小和对齐

默认情况下，C类型以机器的本机格式和字节顺序表示，并且如果必要，通过跳过填充字节（根据C编译器使用的规则）正确对齐。

或者，根据下表，格式字符串的第一个字符可用于指示打包数据的字节顺序，大小和对齐：

字符	字节顺序	大小	对齐
@	本机	本机	本机
=	本机	标准	没有
<	小端	标准	没有
>	大端	标准	没有
!	network（= big-endian）	标准	没有

如果第一个字符不是其中之一，则假定为'@'。

本地字节顺序是大端还是小端，取决于主机系统。例如，Intel x86和AMD64（x86-64）是小端字节序；摩托罗拉68000和PowerPC G5是大端； ARM和Intel Itanium特性可切换字节顺序（双字节顺序）。使用sys.byteorder来检查系统的字节序。

本机大小和对齐使用C编译器的sizeof表达式确定。这总是与本地字节顺序组合。

标准大小仅取决于格式字符；请参阅Format Characters部分中的表格。

注意'@'和'='之间的区别：两者都使用本地字节顺序，但是后者的大小和对齐是标准化的。

格式'!'是给那些声称自己记不住网络字节顺序是大端还是小端的可怜虫准备的。

There is no way to indicate non-native byte order (force byte-swapping); use the appropriate choice of '<' or '>'.

笔记：

1. 填充仅在连续的结构成员之间自动添加。在编码结构的开始或结尾处不添加填充。
2. 当使用非本地大小和对齐时，不添加填充。用''，'='和'！'。
3. 要将结构的末端与特定类型的对齐要求对齐，请使用重复计数为零的该类型的代码结束格式。请参见Examples。

7.1.2.2.格式字符

格式字符具有以下含义； C和Python值之间的转换应该是显而易见的，因为它们的类型。The ‘Standard size’ column refers to the size of the packed value in bytes when using standard size; that is, when the format string starts with one of '<', '>', '!'或'='。当使用原生大小时，打包值的大小取决于平台。

格式	C类型	Python类型	标准尺寸	笔记
x	填充字节	没有值
c	char	字节长度为1	1
b	signed char	整数	1	（1），（3）
B	unsigned char	整数	1	（3）
?	_Bool	bool	1	（1）
h	short	整数	2	（3）
H	unsigned short	整数	2	（3）
i	int	整数	4	（3）
I	unsigned int	整数	4	（3）
l	long	整数	4	（3）
L	unsigned long	整数	4	（3）
q	long long	整数	8	（2），（3）
Q	unsigned long long	整数	8	（2），（3）
n	ssize_t	整数		（4）
N	size_t	整数		（4）
f	float	浮动	4	（5）
d	double	浮动	8	（5）
s	char[]	字节
p	char[]	字节
P	void *	整数		（6）

在版本3.3中已更改：添加了对'n'和'N'格式的支持。

笔记：

1. '?'转换代码对应于由C99定义的_Bool类型。如果此类型不可用，则使用char来模拟。在标准模式下，它总是由一个字节表示。

2. The 'q' and 'Q' conversion codes are available in native mode only if the platform C compiler supports C long long, or, on Windows, __int64. 它们总是在标准模式下可用。

3. 当尝试使用任何整数转换代码封装非整数时，如果非整数具有__index__()方法，则在封装之前调用该方法将参数转换为整数。

   在版本3.2中更改：对于非整数的__index__()方法的使用在3.2中是新的。

4. 'n'和'N'转换代码仅适用于原始大小（选择为默认值或使用'@'字节顺序字符）。对于标准大小，您可以使用适合您的应用程序的其他整数格式。

5. 对于'f'和'd'转换代码，打包表示使用IEEE 754 binary32（'f'）或binary64 for 'd'）格式，而不考虑平台使用的浮点格式。

6. 'P'格式字符仅适用于本机字节排序（选为默认值或使用'@'字节顺序字符）。字节顺序字符'='选择基于主机系统使用小端或大端排序。struct模块不会将其解释为本地排序，因此'P'格式不可用。

格式字符可以在整数重复计数之前。例如，格式字符串'4h'的含义与'hhhh'完全相同。

忽略格式之间的空格字符；一个计数和它的格式不能包含空格。

对于's'格式字符，计数被解释为字节的长度，而不是其他格式字符的重复计数；例如，'10s'表示单个10字节字符串，而'10c'表示10个字符。如果未给出计数，则默认为1。对于封装，字符串被截断或填充空字节，以使其适合。对于分拆，生成的字节对象总是具有指定的字节数。作为特殊情况，'0s'表示单个空字符串（而'0c'表示0个字符）。

When packing a value x using one of the integer formats ('b', 'B', 'h', 'H', 'i', 'I', 'l', 'L', 'q', 'Q'), if x is outside the valid range for that format then struct.error is raised.

在版本3.1中已更改：在3.0中，某些整数格式包含超出范围值，并引发了DeprecationWarning，而不是struct.error。

'p'格式字符编码“Pascal字符串”，表示由计数给出的存储在固定字节数中的短可变长度字符串。存储的第一个字节是字符串的长度，或255，取较小者。字符串的字节跟随。如果传递到pack()的字符串太长（长于计数减1），则只存储字符串的前导count-1个字节。如果字符串小于count-1，则用空字节填充，以便使用所有字节。请注意，对于unpack()，'p'格式字符消耗count字节，但返回的字符串永远不能包含超过255字节。

对于'?'格式字符，返回值为True或False。当封装时，使用参数对象的真值。在本地或标准布尔表示中的0或1将被打包，并且当分离时任何非零值将是True。

7.1.2.3.示例

注意

所有示例假定本机字节顺序，大小和与大端机器的对齐。

封装/解包三个整数的基本示例：

>>> from struct import *
>>> pack('hhl', 1, 2, 3)
b'\x00\x01\x00\x02\x00\x00\x00\x03'
>>> unpack('hhl', b'\x00\x01\x00\x02\x00\x00\x00\x03')
(1, 2, 3)
>>> calcsize('hhl')
8

解压缩的字段可以通过将它们分配给变量或将结果包装在命名的元组中来命名：

>>> record = b'raymond   \x32\x12\x08\x01\x08'
>>> name, serialnum, school, gradelevel = unpack('<10sHHb', record)

>>> from collections import namedtuple
>>> Student = namedtuple('Student', 'name serialnum school gradelevel')
>>> Student._make(unpack('<10sHHb', record))
Student(name=b'raymond   ', serialnum=4658, school=264, gradelevel=8)

格式字符的排序可能对大小有影响，因为满足对齐要求所需的填充是不同的：

>>> pack('ci', b'*', 0x12131415)
b'*\x00\x00\x00\x12\x13\x14\x15'
>>> pack('ic', 0x12131415, b'*')
b'\x12\x13\x14\x15*'
>>> calcsize('ci')
8
>>> calcsize('ic')
5

以下格式'llh0l'在结尾指定两个填充字节，假设长整数在4字节边界对齐：

>>> pack('llh0l', 1, 2, 3)
b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'

这只有在原生大小和对齐有效时才起作用；标准尺寸和对齐不强制执行任何对齐。

也可以看看

模块array

同构数据的打包二进制存储。

模块xdrlib

XDR数据的封装和分拆。

7.1.3.类

struct模块还定义了以下类型：

class struct.Struct(format)

返回一个新的Struct对象，根据格式字符串格式写入和读取二进制数据。创建一个Struct对象并调用其方法比调用具有相同格式的struct函数更有效，因为格式字符串只需要编译一次。

编译的Struct对象支持以下方法和属性：

pack(v1, v2, ...)

与pack()函数相同，使用编译的格式。（len(result)将等于size。）

pack_into(buffer, offset, v1, v2, ...)

与pack_into()函数相同，使用编译的格式。

unpack(buffer)

与unpack()函数相同，使用编译后的格式。缓冲区的大小（字节）必须等于size。

unpack_from(buffer, offset=0)

与unpack_from()函数相同，使用编译的格式。缓冲区的大小（以字节为单位）减去offset，必须至少为size。

iter_unpack(buffer)

与iter_unpack()函数相同，使用编译的格式。缓冲区的大小（以字节为单位）必须是size的倍数。

版本3.4中的新功能。

format

用于构造此Struct对象的格式字符串。

size

对应于format的结构（以及因此由pack()方法产生的字节对象）的计算大小。