该模块在Python值和表示为Python bytes对象的C结缓冲区构体之间进行转换。可用于处理存储在文件中或者来自网络连接,以及其它来源的二进制数据。它使用格式化字符串,作为C结构体布局的简洁描述,以及从Python值,或者到Python值的预期转换。
注意:默认情况下,封装给定的C结构体的结构包括填充字节,以便为涉及的C类型保持正确的对齐;类似地,解包时会考虑对齐。选择此行为使得被封装的结构体的字节完全对应于C结构体在内存中的布局。要处理平台无关的数据格式,或者忽略隐式的填充字节,可以使用
standard
大小和对齐,代替native
大小和对齐,查看字节顺序,大小和对齐了解详情。
有几个struct
函数(和Struct
的方法)接收一个buffer
参数。它引用实现了Buffer
协议的对象,并提供一个可读,或可读写的缓存。用于该目的的最常见的类型是bytes
和bytearray
,但是可以视为字节数组的许多其它类型实现了Buffer
协议,因此它们可以读和填充,而不需要额外的从bytes
对象复制。
1 函数和异常
该模块定义了以下异常和函数:
1.1 异常 struct.error
在各种场合下抛出异常;参数是描述错误的字符串。
1.2 struct.pack(fmt, v1, v2, ...)
根据格式化字符串fmt
封装,返回一个包括v1
,v2
等值的字节对象。参数必须与格式化所需的值完全匹配。
1.3 struct.pack_into(ftm, buffer, offset, v1, v2, ...)
根据格式化字符串fmt
,封装v1
,v2
等值,并从位置offset
开始,将封装的字节写入可写缓冲区buffer
中。注意,offset
是必需的参数。
1.4 struct.unpack(fmt, buffer)
根据格式化字符串fmt
,从缓冲区buffer
(假设由pack(fmt, ...)
封装)中解包。即使结果只包含一项,也是一个元组。缓冲区的大小(以字节为单位)必需与格式所需的大小匹配,比如calcsize()
所得的结果。
1.5 struct.unpack_from(fmt, buffer, offset=0)
根据格式化字符串fmt
,从位置offset
开始解包。即使结果只包含一项,也是一个元组。缓冲区的大小(以字节为单位)减去offset
,至少是格式化所需的大小,比如calcsize()
所得的结果。
1.5 struct.iter_unpack(fmt, buffer)
版本3.4中新增。
根据格式化字符串fmt
,从缓冲区buffer
中迭代解包。该函数返回一个iterator
,它将从缓冲区中读取大小相等的块,直到所有内容被耗尽。缓冲区的大小(以字节为单位)必须是格式化所需大小的倍数,比如calcsize()
所得的结果。
每次迭代yield一个由格式化字符串指定的元组。
1.6 struct.calcsize(fmt)
返回对应于格式化字符串fmt
的结构体(以及由pack(fmt, ...)
生成的字节对象)的大小。