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

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

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

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

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

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

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

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

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

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

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

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

Примечания:

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

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

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

Примечания:

1. Код преобразования '?' соответствует типу _Bool, определённому стандартами C начиная с C99. В стандартном режиме он представлен одним байтом.

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

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

3. Коды преобразования 'n' и 'N' доступны только для нативного размера (выбираемого по умолчанию или с помощью символа порядка байтов '@'). Для стандартного размера можно использовать любой другой целочисленный формат, подходящий для вашей задачи.
4. Для кодов преобразования 'f', 'd' и 'e' в упакованном представлении используются форматы IEEE 754 binary32, binary64 или binary16 (для 'f', 'd' или 'e' соответственно), независимо от формата чисел с плавающей точкой, используемого платформой.
5. Символ формата 'P' доступен только для нативного порядка байтов (выбираемого по умолчанию или с помощью символа порядка байтов '@'). Символ порядка байтов '=' выбирает порядок от младшего к старшему или от старшего к младшему в зависимости от хост-системы. Модуль 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' кодирует «строку Pascal», то есть строку переменной длины, хранящуюся в фиксированном количестве байтов, заданном счётчиком. Первый сохранённый байт содержит длину строки или число 255, если длина больше. За ним следуют байты строки. Если строка, переданная в pack(), слишком длинная (длиннее, чем счётчик минус 1), сохраняются только первые count-1 байтов строки. Если строка короче count-1, она дополняется нулевыми байтами, чтобы общее количество использованных байтов точно соответствовало счётчику. Обратите внимание: при вызове unpack() символ формата 'p' занимает count байтов, однако возвращаемая строка не может содержать более 255 байтов.
9. Для символа формата 's' счётчик интерпретируется как длина байтов, а не как число повторений, как для остальных символов формата; например, '10s' означает одну строку длиной 10 байтов, преобразуемую в одну строку байтов Python или обратно, тогда как '10c' означает 10 отдельных односимвольных элементов длиной в один байт (например, cccccccccc), преобразуемых в десять разных объектов bytes 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.

Примеры

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

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

>>> 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-разрядной архитектурой и порядком байтов от младшего к старшему):

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

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

>>> calcsize('@llh0l')
24

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

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

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

При обмене данными за пределами процесса, например по сети или при хранении, необходимо указывать точные параметры: порядок байтов, размер и выравнивание. Не следует считать, что они совпадают с нативным порядком на конкретном компьютере. Например, в сетевом порядке байты располагаются от старшего к младшему, тогда как многие популярные процессоры используют порядок от младшего к старшему. Если определить эти параметры явно, пользователю не придётся учитывать особенности платформы, на которой выполняется код. Обычно первым символом должен быть < или > (либо !). За добавление заполнителей отвечает программист. Символ формата с нулевым числом повторений здесь не подойдёт. Вместо этого пользователь должен явно добавлять '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