struct?Python 原生類型(int、float、str)與 C 結構體/網絡協議的二進制佈局不直接對應。struct 模組提供**格式字符串**描述二進制佈局,實現 Python 值 ↔ 字節流(bytes)的雙向轉換,是網絡編程、文件格式解析、C 擴展交互、嵌入式通訊的基石。
| 函數 | 用途 | 簽名 |
|---|---|---|
pack(fmt, v1, v2, ...) | 值 → bytes | bytes |
unpack(fmt, buffer) | bytes → 元組 | tuple |
calcsize(fmt) | 計算格式佔用字節數 | int |
pack_into(fmt, buffer, offset, v1, ...) | 寫入預分配緩衝區 | None |
unpack_from(fmt, buffer, offset=0) | 從緩衝區偏移解包 | tuple |
iter_unpack(fmt, buffer) | 迭代解包多個結構 | iterator |
| 格式 | C 類型 | Python 類型 | 標準大小 | 備註 |
|---|---|---|---|---|
x | pad byte | 無 | 1 | 對齊填充 |
c | char | bytes (len=1) | 1 | |
b | signed char | int | 1 | -128~127 |
B | unsigned char | int | 1 | 0~255 |
? | _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 | C long 大小平台相關 |
L | unsigned long | int | 4 | |
q | long long | int | 8 | 8 字節整數 |
Q | unsigned long long | int | 8 | |
f | float | float | 4 | IEEE 754 single |
d | double | float | 8 | IEEE 754 double |
s | char[] | bytes | n | 10s 固定 10 字節 |
p | char[] (Pascal string) | bytes | n | 首字節長度 |
P | void* | int | 平台相關 | 指針大小 |
| 字符 | 字節序 | 大小/對齊 |
|---|---|---|
@ | 本地 | 本地(預設,平台相關) |
= | 本地 | 標準(無對齊填充) |
< | 小端 | 標準 |
> | 大端 | 標準 |
! | 網絡(大端) | 標準 |
網絡協議必用 ! 或 >**,確保跨平台一致性。
import struct
# 打包兩個 int (小端)
data = struct.pack('
pack_into / unpack_from 零拷貝緩衝區操作
from ctypes import create_string_buffer
import struct
buf = create_string_buffer(12) # 可變 bytes 緩衝區
print(buf.raw.hex()) # 000000000000000000000000
struct.pack_into('
適用於高效能網絡收發、共享內存、mmapped 文件、硬體寄存器映射。
# 協議定義:
# Magic(2B) | Version(1B) | Cmd(1B) | Seq(4B) | PayloadLen(2B) | Payload(N) | CRC16(2B)
# 全部大端 (!)
HEADER_FMT = '!HBBBH'
HEADER_SIZE = struct.calcsize(HEADER_FMT)
def encode_packet(cmd: int, seq: int, payload: bytes) -> bytes:
header = struct.pack(HEADER_FMT, 0xA5A5, 1, cmd, seq, len(payload))
crc = crc16(header + payload) # 假設有 crc16 函數
return header + payload + struct.pack('!H', crc)
def decode_packet(data: bytes):
if len(data) < HEADER_SIZE + 2:
raise ValueError("Packet too short")
magic, ver, cmd, seq, plen = struct.unpack_from(HEADER_FMT, data, 0)
if magic != 0xA5A5: raise ValueError("Bad magic")
payload = data[HEADER_SIZE:HEADER_SIZE+plen]
crc = struct.unpack_from('!H', data, HEADER_SIZE+plen)[0]
# 校驗 CRC...
return cmd, seq, payload
@ (默認) 使用本地對齊,**跨平台交互必須指定 =, <, >, !**。struct.pack('B', 300) → struct.error。預先 & 0xFF 或用 ctypes.c_ubyte。s 格式固定長度:pack('10s', b'hi') → b'hi\x00\x00\x00\x00\x00\x00\x00\x00',解包時需 .rstrip(b'\x00')。unpack('1000i', data) 創建巨大元組,改用 iter_unpack 或 numpy.frombuffer。@hi 可能在 short 後插入 2 字節 padding,=hi 無 padding。調試用 calcsize 驗證。Struct 對象:st = struct.Struct('!ii'),調用 st.pack(), st.unpack(), st.unpack_from(),避免重複解析格式串。array.array, numpy, memoryview 零拷貝轉換。struct.unpack_from 直接從 bytearray/memoryview 讀取,無切片拷貝。struct 是 Python 處理二進制數據的瑞士軍刀。掌握**格式字符串語法、字節序控制、Struct 對象預編譯、緩衝區零拷貝操作**,能高效完成網絡協議解析、文件格式讀寫、C 互操作等任務。現代高效能場景建議配合 memoryview + numpy 或 construct/kaitai-struct 等聲明式解析庫使用。