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

Этот модуль выполняет преобразования между значениями Python и C-структурами, представленными в Python как строки. Это может использоваться для обработки двоичных данных, хранящихся в файлах или полученных из сетевых соединений, среди прочих источников. Он использует Строки формата в качестве компактных описаний структуры C-структур и предназначенного преобразования к/из значений Python.

1. Функции и исключения

Модуль определяет следующие исключения и функции:

exception struct.error

Исключение, генерируемое в различных случаях; аргумент — строка, описывающая проблему.

struct.pack(fmt, v1, v2, ...)

Возвращает строку, содержащую значения v1, v2, ... , упакованные в соответствии с заданным форматом. Аргументы должны точно соответствовать значениям, требуемым форматом.

struct.pack_into(fmt, buffer, offset, v1, v2, ...)

Упаковывает значения v1, v2, ... в соответствии с заданным форматом, записывает упакованные байты в изменяемый буфер, начиная с смещения. Обратите внимание, что смещение является обязательным аргументом.

Добавлена в версии 2.5.

struct.unpack(fmt, string)

Распаковывает строку (предположительно упакованную с помощью pack(fmt, ...) ) в соответствии с заданным форматом. Результат — кортеж, даже если он содержит ровно один элемент. Строка должна содержать ровно количество данных, требуемое форматом (len(string) должно равняться calcsize(fmt)).

struct.unpack_from(fmt, buffer[, offset=0])

Распаковывает буфер в соответствии с заданным форматом. Результат — кортеж, даже если он содержит ровно один элемент. Буфер должен содержать по крайней мере количество данных, требуемое форматом (len(buffer[offset:]) должен быть по крайней мере calcsize(fmt)).

Добавлена в версии 2.5.

struct.calcsize(fmt)

Возвращает размер структуры (и, следовательно, строки), соответствующей заданному формату.

2. Строки формата

Строки формата — это механизм, используемый для указания ожидаемой структуры при упаковке и распаковке данных. Они строятся из символов формата, которые определяют тип данных, подлежащих упаковке/распаковке. Кроме того, есть специальные символы для управления порядком байтов, размером и выравниванием.

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

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

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

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

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

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

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

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

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

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

Примечания:

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

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

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

Примечания:

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

   Добавлена в версии 2.6.

2. Коды преобразования 'q' и 'Q' доступны только в родном режиме, если платформа компилятор C поддерживает C long long, или, в Windows, __int64. Они всегда доступны в стандартных режимах.

   Добавлена в версии 2.2.

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

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

   Изменено в версии 2.7: До версии 2.7 не все коды преобразования целых чисел использовали метод __int__() для преобразования, и DeprecationWarning поднимался только для аргументов типа float.

4. Для кодов преобразования 'f' и 'd' упакованное представление использует формат IEEE 754 binary32 (для 'f') или binary64 (для 'd') независимо от формата чисел с плавающей точкой, используемого платформой.
5. Форматный символ 'P' доступен только для родного порядка байтов (выбран по умолчанию или с символом порядка байтов '@'). Символ порядка байтов '=' выбирает порядок little-endian или big-endian на основе системы хоста. Модуль struct не интерпретирует это как родной порядок, поэтому формат 'P' недоступен.

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

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

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

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

Для форматного символа 'P' возвращаемое значение — целое число Python или длинное целое число Python, в зависимости от размера, необходимого для хранения указателя, когда он преобразован в целочисленный тип. Указатель NULL всегда возвращается как целое число Python 0. При упаковке могут использоваться целочисленные объекты Python или длинные целочисленные объекты Python.

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

2.3. Примеры

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

>>> from struct import *
>>> pack('hhl', 1, 2, 3)
'\x00\x01\x00\x02\x00\x00\x00\x03'
>>> unpack('hhl', '\x00\x01\x00\x02\x00\x00\x00\x03')
(1, 2, 3)
>>> calcsize('hhl')
8

Распакованные поля можно именовать, присваивая их переменным или заключая результат в именованный кортеж:

>>> record = '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='raymond   ', serialnum=4658, school=264, gradelevel=8)

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

>>> pack('ci', '*', 0x12131415)
'*\x00\x00\x00\x12\x13\x14\x15'
>>> pack('ic', 0x12131415, '*')
'\x12\x13\x14\x15*'
>>> calcsize('ci')
8
>>> calcsize('ic')
5

Следующий формат 'llh0l' задаёт два байта заполнения в конце, предполагая, что длинные целые числа выровнены на границах 4 байтов:

>>> pack('llh0l', 1, 2, 3)
'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'

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

3. Классы

Модуль struct также определяет следующий тип:

class struct.Struct(format)

Возвращает новый объект Struct, который записывает и считывает двоичные данные в соответствии со строкой формата format. Создание объекта Struct один раз и вызов его методов более эффективно, чем вызов функций struct с тем же форматом, поскольку строка формата компилируется только один раз.

Добавлена в версии 2.5.

Компилированные объекты Struct поддерживают следующие методы и атрибуты:

pack(v1, v2, ...)

Идентичен функции pack(), используя скомпилированный формат. (len(result) будет равно self.size.)

pack_into(buffer, offset, v1, v2, ...)

Идентичен функции pack_into(), используя скомпилированный формат.

unpack(string)

Идентичен функции unpack(), используя скомпилированный формат. (len(string) должно быть равно self.size).

unpack_from(buffer, offset=0)

Идентичен функции unpack_from(), используя скомпилированный формат. (len(buffer[offset:]) должно быть по крайней мере self.size).

format

Строка формата, используемая для создания этого объекта Struct.

size

Вычисленный размер структуры (и, следовательно, строки), соответствующий format.