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

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

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

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

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

Родной порядок байтов — это большой или малый порядок байтов в зависимости от системы. Например, Intel x86, AMD64 (x86-64) и Apple M1 имеют малый порядок байтов; IBM z и многие архитектуры наследия — большой порядок байтов. Используйте sys.byteorder для проверки порядка байтов вашей системы.

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

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

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

Форма '!' представляет собой сетевой порядок байтов, который всегда является большим порядком байтов, как определено в 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 «половинной точности» был введен в пересмотре стандарта IEEE 754 2008 года. У него есть бит знака, 5-битный экспонент и 11-битная точность (с 10 битами, явно хранящимися), и он может представлять числа примерно от 6.1e-05 до 6.5e+04 с полной точностью. Этот тип не широко поддерживается компиляторами C: на типичной машине для хранения можно использовать unsigned short, но не для математических операций. См. страницу Википедии о формате чисел с плавающей запятой с половинной точностью для получения дополнительной информации.
7. При упаковке 'x' вставляет один байт NUL.
8. Символ формата 'p' кодирует «строку Паскаля», то есть короткую строку переменной длины, хранящуюся в фиксированном количестве байтов, заданном счетчиком. Первый сохраненный байт — это длина строки или 255, что меньше. За ним следуют байты строки. Если строка, переданная в pack(), слишком длинная (длиннее, чем счетчик минус 1), хранятся только ведущие count-1 байтов строки. Если строка короче count-1, она дополняется нулевыми байтами, чтобы использовалось ровно count байт. Обратите внимание, что для unpack() символ формата 'p' потребляет count байт, но возвращаемая строка никогда не может содержать более 255 байт.
9. Для символа формата 's' счетчик интерпретируется как длина байтов, а не как счетчик повторений, как для других символов формата; например, '10s' означает одну строку из 10 байт, которая отображается или считывается как одна строка Python с байтами, в то время как '10c' означает 10 отдельных элементов по одному байту (например, cccccccccc) которые отображаются или считываются как десять разных байтовых объектов Python. (См. Примеры для конкретной демонстрации разницы.) Если счетчик не указан, он по умолчанию равен 1. При упаковке строка усекается или дополняется нулевыми байтами, чтобы она уместилась. При распаковке полученный объект байтов всегда имеет ровно указанное количество байтов. В качестве специального случая '0s' означает одну пустую строку (в то время как '0c' означает 0 символов).

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

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

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

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

Примеры

Упаковываем и распаковываем целые числа трёх разных размеров, используя порядок байтов big endian:

>>> from struct import *
>>> pack(">bhl", 1, 2, 3)
b'\x01\x00\x02\x00\x00\x00\x03'
>>> unpack('>bhl', b'\x01\x00\x02\x00\x00\x00\x03')
(1, 2, 3)
>>> calcsize('>bhl')
7

Попытка упаковать целое число, которое слишком велико для определённого поля:

>>> pack(">h", 99999)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
struct.error: 'h' format requires -32768 <= number <= 32767

Демонстрация разницы между 's' и 'c' символами формата:

>>> pack("@ccc", b'1', b'2', b'3')
b'123'
>>> pack("@3s", b'123')
b'123'

Распакованные поля могут быть именованы путём присваивания их переменным или путём обертывания результата в именованную кортеж:

>>> 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 вызове ниже, что после упакованного '#' были добавлены три нулевых байта, чтобы выровнять следующее целое число по четырёхбайтовой границе. В этом примере вывод был произведён на машине с порядком байтов little endian:

>>> pack('@ci', b'#', 0x12131415)
b'#\x00\x00\x00\x15\x14\x13\x12'
>>> pack('@ic', 0x12131415, b'#')
b'\x15\x14\x13\x12#'
>>> 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'

Родные форматы

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

Рассмотрим эти два простых примера (на 64-битной машине с порядком байтов little-endian):

>>> calcsize('@lhl')
24
>>> calcsize('@llh')
18

Данные не выравниваются до 8-байтовой границы в конце второй строки формата без использования дополнительного выравнивания. Код нулевой повторяемости решает эту проблему:

>>> calcsize('@llh0l')
24

Символ формата 'x' можно использовать для указания повторения, но для родных форматов лучше использовать формат нулевой повторяемости, например, '0l'.

По умолчанию используется родной порядок байтов и выравнивание, но лучше быть явным и использовать префикс '@'.

Стандартные форматы

При обмене данными за пределами вашего процесса, например, в сетях или при хранении, будьте точны. Укажите точный порядок байтов, размер и выравнивание. Не предполагайте, что они совпадают с родным порядком конкретной машины. Например, сетевой порядок байтов — big-endian, а многие популярные процессоры — little-endian. Определив это явно, пользователю не нужно заботиться о специфике платформы, на которой работает его код. Первый символ обычно должен быть < или > (или !). Выравнивание — ответственность программиста. Код нулевой повторяемости не сработает. Вместо этого пользователь должен явно добавить 'x' байты заполнителя при необходимости. Возвращаясь к примерам из предыдущего раздела, мы имеем:

>>> calcsize('<qh6xq')
24
>>> pack('<qh6xq', 1, 2, 3) == pack('@lhl', 1, 2, 3)
True
>>> calcsize('@llh')
18
>>> pack('@llh', 1, 2, 3) == pack('<qqh', 1, 2, 3)
True
>>> calcsize('<qqh6x')
24
>>> calcsize('@llh0l')
24
>>> pack('@llh0l', 1, 2, 3) == pack('<qqh6x', 1, 2, 3)
True

Указанные выше результаты (выполненные на 64-битной машине) не гарантируют совпадения при выполнении на различных машинах. Например, примеры ниже были выполнены на 32-битной машине:

>>> calcsize('<qqh6x')
24
>>> calcsize('@llh0l')
12
>>> pack('@llh0l', 1, 2, 3) == pack('<qqh6x', 1, 2, 3)
False