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

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

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

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

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

>>> import struct
>>> struct.pack('>h', 1023)
b'\x03\xff'
>>> struct.pack('<h', 1023)
b'\xff\x03'

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

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

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

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

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

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

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

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

Для символа формата '?' возвращаемое значение — либо True, либо False. При упаковке используется значение истинности объекта-аргумента. В упакованный вид будет помещено либо 0, либо 1 в соответствии с представлением типа bool в вашей системе, а любое ненулевое значение при распаковке будет 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' приводит к добавлению двух байтов дополнения в конце, предполагая, что длинные целые числа платформы выровнены по границам в четыре байта:

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