[Python] struct.unpack() 用法详解

struct.unpack()用法详解

---

struct.unpack() 是 Python 中用于将二进制数据（字节序列）解析为 Python 数据类型的函数，通常与 struct.pack() 配对使用。它根据指定的格式字符串（format string）解析字节流，并返回一个包含解析结果的元组。

---

一、函数语法

struct.unpack(format, buffer)

• format：格式字符串，定义数据的解析规则（字节顺序、数据类型、数量等）。
• buffer：包含二进制数据的缓冲区（如 bytes、bytearray 或支持缓冲协议的对象）。

返回值：包含解析后数据的元组。

---

二、格式字符串详解

格式字符串由两部分组成：

1. 字节顺序/对齐字符（可选）：

   字符	含义	大小端
   @	本地顺序（默认）	系统依赖
   =	本地标准大小	系统依赖
   <	小端（Little-Endian）	低位在前
   >	大端（Big-Endian）	高位在前
   !	网络顺序（大端）	RFC 标准

2. 数据类型字符（必选）：

   字符	C 类型	Python 类型	字节数
   x	填充字节	跳过字节	1
   c	char	bytes (长度1)	1
   b	signed char	int	1
   B	unsigned char	int	1
   ?	_Bool	bool	1
   h	short	int	2
   H	unsigned short	int	2
   i	int	int	4
   I	unsigned int	int	4
   l	long	int	4
   L	unsigned long	int	4
   q	long long	int	8
   Q	unsigned long long	int	8
   f	float	float	4
   d	double	float	8
   s	char[]	bytes	长度见下文
   p	Pascal 字符串	bytes	1+长度
   P	void*	int	系统依赖

   特殊用法：

   • s：需指定长度，如 10s 表示解析 10 字节的字符串。
   • 数字前缀：3I 表示连续解析 3 个无符号整数。

---

三、使用示例

示例 1：解析整数和浮点数

import struct

# 二进制数据：小端顺序 (<) + int (i) + float (f)
buffer = b'\x01\x00\x00\x00\xcd\xcc\x8c@'
data = struct.unpack('<if', buffer)  # 解析1个int和1个float

print(data)  # 输出: (1, 7.000000476837158)

示例 2：解析字符串

# 数据：大端 (>) + 4字节字符串 (4s)
buffer = b'ABCD'
data = struct.unpack('>4s', buffer)

print(data)  # 输出: (b'ABCD',)

示例 3：解析混合类型

# 数据：小端 (<) + short (h) + 3字节字符串 (3s) + float (f)
buffer = b'\x01\x00XYZ\x00\x00\x80?'
data = struct.unpack('<h3sf', buffer)

print(data)  # 输出: (1, b'XYZ', 1.0)

示例 4：跳过填充字节

# 格式: 小端 (<) + char (c) + 填充1字节 (x) + int (i)
buffer = b'A\x00\x02\x00\x00\x00'
data = struct.unpack('<cx i', buffer)

print(data)  # 输出: (b'A', 2)

示例 5：解析数组

# 解析3个连续的 unsigned short (H)
buffer = b'\x01\x00\x02\x00\x03\x00'
data = struct.unpack('<3H', buffer)

print(data)  # 输出: (1, 2, 3)

---

四、关键注意事项

1. 缓冲区长度必须匹配
   使用 struct.calcsize(format) 验证格式字符串所需的字节数：

   fmt = '<2i f'
   buffer = b'\x00' * struct.calcsize(fmt)  # 创建匹配长度的缓冲区
   

2. 字节顺序至关重要
   大端/小端错误会导致解析数值异常：

   # 错误示例：大端数据用小端解析
   buffer = b'\x00\x00\x00\x01'  # 大端表示的整数 1
   struct.unpack('<I', buffer)   # 错误！解析为 16777216 (0x01000000)
   

3. 字符串处理
   s 类型返回 bytes 对象，需用 .decode() 转为字符串：

   data = struct.unpack('5s', b'Hello')[0]
   print(data.decode('utf-8'))  # 输出: 'Hello'
   

4. 内存对齐问题
   默认格式 @ 会按本地对齐方式插入填充字节。使用 = 或标准顺序（</>）避免对齐。

---

五、常见错误

• struct.error: unpack requires a buffer of X bytes
  缓冲区长度与格式字符串不匹配。
• 解析指针类型 (P)
  结果依赖平台（32/64位），通常应避免使用。

通过合理设计格式字符串，struct.unpack() 可高效处理二进制协议（如网络数据、文件格式）。

---

研究学习不易，点赞易。
工作生活不易，收藏易，点收藏不迷茫 ：）

---