struct — Интерпретация байтов как упакованных двоичных данных

Порядок байтов, размер и выравнивание

По умолчанию, C-типы представляются в родном формате машины и порядке байтов и правильно выравниваются путем пропуска байтов заполнения при необходимости (согласно правилам, используемым C-компилятором).

В качестве альтернативы, первый символ строки формата может использоваться для указания порядка байтов, размера и выравнивания упакованных данных, в соответствии со следующей таблицей:

Если первый символ не является одним из этих, предполагается '@'.

Родной порядок байтов — большой или малый порядок байтов, в зависимости от системы. Например, Intel x86 и AMD64 (x86-64) имеют малый порядок байтов; Motorola 68000 и PowerPC G5 имеют большой порядок байтов; ARM и Intel Itanium имеют переключаемый порядок байтов (двусторонний). Используйте sys.byteorder для проверки порядка байтов вашей системы.

Родные размер и выравнивание определяются с помощью выражения sizeof C-компилятора. Это всегда сочетается с родным порядком байтов.

Стандартный размер зависит только от символа формата; см. таблицу в разделе Символы формата.

Обратите внимание на различие между '@' и '=': оба используют родной порядок байтов, но размер и выравнивание последнего стандартизированы.

Форма '!' представляет сетевой порядок байтов, который всегда является большим порядком байтов, как определено в IETF RFC 1700.

Нет способа указать неродной порядок байтов (принудительное переключение байтов); используйте соответствующий выбор '<' или '>'.

Примечания:

1. Заполнение добавляется только автоматически между последовательными членами структуры. Заполнение не добавляется в начале или в конце кодируемой структуры.
2. Заполнение не добавляется при использовании неродного размера и выравнивания, например, с помощью ‘<’, ‘>’, ‘=’, и ‘!’.
3. Для выравнивания конца структуры по требованиям выравнивания определённого типа завершите формат кодом для этого типа с повторяемостью ноль. См. Примеры.

Символы формата

Символы формата имеют следующее значение; преобразование между значениями C и Python должно быть очевидным, учитывая их типы. Столбец «Стандартный размер» относится к размеру упакованного значения в байтах при использовании стандартного размера; то есть, когда строка формата начинается с одного из '<', '>', '!' или '='. При использовании размера по умолчанию размер упакованного значения зависит от платформы.

Примечания:

1. Код преобразования '?' соответствует типу _Bool, определенному в C99. Если этот тип недоступен, он моделируется с помощью char. В стандартном режиме он всегда представляется одним байтом.

2. При попытке упаковать не целое число с использованием любого из кодов преобразования целых чисел, если у нецелого числа есть метод __index__(), то этот метод вызывается для преобразования аргумента в целое число перед упаковкой.

   Изменено в версии 3.2: Добавлена поддержка метода __index__() для нецелых чисел.

3. Коды преобразования 'n' и 'N' доступны только для размера по умолчанию (выбранного по умолчанию или с символом порядка байтов '@'). Для стандартного размера можно использовать любой другой формат целых чисел, подходящий для вашего приложения.
4. Для кодов преобразования 'f', 'd' и 'e', упакованное представление использует формат IEEE 754 binary32, binary64 или binary16 (соответственно для 'f', 'd' или 'e') независимо от формата чисел с плавающей точкой, используемого платформой.
5. Символ формата 'P' доступен только для родного порядка байтов (выбранного по умолчанию или с символом порядка байтов '@'). Символ порядка байтов '=' выбирает использование порядка little-endian или big-endian в зависимости от системы. Модуль struct не интерпретирует это как порядок по умолчанию, поэтому формат 'P' недоступен.
6. Тип IEEE 754 binary16 «полуточной точности» был введен в редакции 2008 года стандарта IEEE 754. Он имеет бит знака, 5-битный экспоненту и 11-битную точность (с 10 битами, явно хранимыми) и может представлять числа примерно от 6.1e-05 до 6.5e+04 при полной точности. Этот тип не широко поддерживается компиляторами C: на типичной машине можно использовать беззнаковый short для хранения, но не для математических операций. См. страницу Википедии о формате чисел с плавающей точкой полуточной точности для получения дополнительной информации.

Символу формата может предшествовать целое число, указывающее количество повторений. Например, строка формата '4h' означает ровно то же самое, что и 'hhhh'.

Пробельные символы между форматами игнорируются; однако счетчик и его формат не должны содержать пробелов.

Для символа формата 's' счетчик интерпретируется как длина байтов, а не как счетчик повторений, как для других символов формата; например, '10s' означает одну строку из 10 байтов, а '10c' означает 10 символов. Если счетчик не указан, он по умолчанию равен 1. При упаковке строка усекается или дополняется нулевыми байтами, как это необходимо для соответствия. При распаковке возвращаемый объект bytes всегда имеет ровно указанное количество байтов. В качестве специального случая, '0s' означает одну пустую строку (в то время как '0c' означает 0 символов).

При упаковке значения x с использованием одного из форматов целых чисел ('b', 'B', 'h', 'H', 'i', 'I', 'l', 'L', 'q', 'Q'), если x находится вне допустимого диапазона для этого формата, то генерируется исключение struct.error.

Символ формата 'p' кодирует «строку Паскаля», означающую короткую строку переменной длины, хранимую в фиксированном количестве байтов, заданном счетчиком. Первый хранимый байт — длина строки или 255, в зависимости от того, что меньше. За ним следуют байты строки. Если строка, переданная в pack(), слишком длинная (длиннее, чем счетчик минус 1), хранятся только ведущие count-1 байты строки. Если строка короче count-1, она дополняется нулевыми байтами таким образом, что используется ровно count байтов. Обратите внимание, что для unpack(), символ формата 'p' потребляет count байтов, но возвращаемая строка никогда не может содержать более 255 байтов.

Для символа формата '?' возвращаемое значение — либо True, либо False. При упаковке используется истинностное значение объекта-аргумента. При упаковке используется либо 0, либо 1 в представлении bool по умолчанию или стандартном, а любое ненулевое значение будет True при распаковке.

Примеры

Базовый пример упаковки/распаковки трех целых чисел:

>>> 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'

Это работает только когда действуют родной размер и выравнивание; стандартный размер и выравнивание не накладывают никаких ограничений на выравнивание.