Skip to main content

7.1. struct —将字节解释为打包二进制数据

源代码: Lib/struct.py


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

注解

默认情况下,打包给定C结构的结果包括填充字节,以便为所涉及的C类型保持适当的对齐;类似地,在拆包时考虑对准。选择此行为,以便打包结构的字节完全对应于对应C结构的内存中的布局。要处理平台无关的数据格式或省略隐式填充字节,请使用 standard 大小和对齐而不是 native 大小和对齐:有关详细信息,请参阅 字节顺序,大小和对齐

几个 struct 函数(和 Struct 的方法)采用 buffer 参数。这指的是实现 缓冲区协议 并提供可读或可读写缓冲区的对象。用于该目的的最常见的类型是 bytesbytearray,但是可以被视为字节数组的许多其它类型实现缓冲器协议,使得它们可以被读取/填充而无需来自 bytes 对象的额外复制。

7.1.1. 函数和异常

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

exception struct.error

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

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

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

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

根据格式字符串 fmt 打包值 v1v2,...,并将打包字节写入从位置 offset 开始的可写缓冲器 buffer。请注意,offset 是必需的参数。

struct.unpack(fmt, buffer)

从缓冲区 buffer (假定由 pack(fmt, ...) 打包)根据格式字符串 fmt 解包。结果是一个元组,即使它只包含一个项目。缓冲区的大小(以字节为单位)必须与格式所要求的大小相符,如 calcsize() 所示。

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

offset 开始,根据格式字符串 fmtbuffer 解包。结果是一个元组,即使它只包含一个项目。缓冲区的大小(以字节为单位,减去 offset)必须至少为格式所需的大小,如 calcsize() 所反映。

struct.iter_unpack(fmt, buffer)

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

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

3.4 新版功能.

struct.calcsize(fmt)

返回对应于格式字符串 fmt 的结构体(以及由此由 pack(fmt, ...) 产生的字节对象)的大小。

7.1.2. 格式字符串

格式字符串是用于在打包和解包数据时指定预期布局的机制。它们由 格式字符 构建,其指定正在打包/解包的数据的类型。此外,还有用于控制 字节顺序,大小和对齐 的特殊字符。

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

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

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

字符

字节顺序

尺寸

对准

@

本机

本机

本机

=

本机

标准

没有

<

小端

标准

没有

>

大端

标准

没有

!

network(= big-endian)

标准

没有

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

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

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

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

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

'!' 形式适用于那些声称不能记住网络字节顺序是大端还是小端的可怜的灵魂。

没有办法指示非本地字节顺序(强制字节交换);使用适当的选择 '<''>'

笔记:

  1. 填充仅在连续的结构成员之间自动添加。在编码结构的开始或结尾处不添加填充。

  2. 当使用非本地大小和对齐时,不添加填充。与’<’,’>’,’=’和’!’。

  3. 要将结构的末尾与特定类型的对齐要求对齐,请使用重复计数为零的该类型的代码结束格式。见 例子

7.1.2.2. 格式字符

格式字符具有以下含义; C和Python值之间的转换应该是显而易见的,因为它们的类型。 “标准大小”列是指使用标准大小时的打包值的大小(以字节为单位);即当格式串以 '<''>''!''=' 中的一个开始时。当使用原生大小时,打包值的大小取决于平台。

格式

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)

e

(7)

浮动

2

(5)

f

float

浮动

4

(5)

d

double

浮动

8

(5)

s

char[]

字节

   

p

char[]

字节

   

P

void *

整数

 

(6)

在 3.3 版更改: 添加了对 'n''N' 格式的支持。

在 3.6 版更改: 添加了对 'e' 格式的支持。

笔记:

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

  2. 仅当平台C编译器支持C long long 或在Windows上为 __int64 时,'q''Q' 转换代码才可在纯模式下使用。它们总是在标准模式下可用。

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

    在 3.2 版更改: 在3.2中使用 __index__() 方法作为非整数是新的。

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

  5. 对于 'f''d''e' 转换代码,打包表示使用IEEE 754二进制32,二进制64或二进制16格式(分别用于 'f''d''e'),而不考虑平台使用的浮点格式。

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

  7. IEEE 754 standard 的2008年版中引入了IEEE 754二进制16“半精度”类型。它具有符号位,5位指数和11位精度(显式存储10位),并且可以以全精度表示大约 6.1e-056.5e+04 之间的数字。 C编译器不广泛支持此类型:在典型的机器上,无符号短整数可用于存储,但不用于数学运算。有关详细信息,请参阅 half-precision floating-point format 上的维基百科页面。

格式字符可以在整数重复计数之前。例如,格式字符串 '4h' 意味着与 'hhhh' 完全相同。

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

对于 's' 格式字符,计数被解释为字节的长度,而不是其他格式字符的重复计数;例如,'10s' 表示单个10字节字符串,而 '10c' 表示10个字符。如果没有给出计数,它默认为1.对于打包,字符串被截断或填充空字节,以使其适合。对于解包,生成的字节对象总是具有指定的字节数。作为特殊情况,'0s' 表示单个空字符串(而 '0c' 表示0个字符)。

当使用整数格式('b''B''h''H''i''I''l''L''q''Q')之一打包值 x 时,如果 x 在该格式的有效范围之外,则引发 struct.error

在 3.1 版更改: 在3.0中,一些整数格式包裹了超范围值,并提高了 DeprecationWarning,而不是 struct.error

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

对于 '?' 格式字符,返回值为 TrueFalse。当打包时,使用参数对象的真值。在本地或标准布尔表示中的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对象,根据格式字符串 format 写入和读取二进制数据。创建一个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() 方法产生的字节对象)的计算大小。