struct — Интерпретация байтов как упакованные двоичные данные¶
Модуль выполняет преобразования между Python значениями и C структурами, представленными как bytes объекты Python. Может использоваться для обработки двоичных данных, хранящихся в файлах или из сетевых подключений, а также из других источников. Он использует Строки формата в качестве компактного описания макета структур C и предполагаемого преобразования в/из значений Python.
По умолчанию результат упаковки данной C структуры включает в себя байты заполнения, чтобы поддерживать правильное выравнивание для задействованных типов C; аналогично учитывается выравнивание при распаковке. Это поведение выбрано таким образом, чтобы байты упакованной структуры точно соответствовали разметке в памяти соответствующей структуры C. Чтобы обрабатывать независимые от платформы форматы данных или пропускать неявные байты заполнения, используется размер и выравнивание standard вместо размера и выравнивания native : подробности см. в Порядок байтов, размер и выравнивание .
Некоторые функции struct (и методы Struct ) принимают buffer аргумент. Это относится к объектам, которые реализуют Буферный протокол и предоставляют буфер с возможностью чтения или записи и чтения. Наиболее распространенными типами, используемыми для этой цели, являются bytes и bytearray , но многие другие типы, которые можно рассматривать как массив байтов, реализуют протокол буфера, так что их можно читать/заполнять без дополнительного копирования из объекта bytes .
Функции и исключения¶
Модуль определяет следующие исключения и функции:
Исключения возникшие по разным причинам; аргумент — это строка, рассказывающая, что не так.
Возвращает байтовый объект, содержащий значения v1, v2, …, упакованные в соответствии со строкой формата format. Аргументы должны точно соответствовать значениям, требуемым форматом.
Упаковать значения v1, v2, … в соответствии со строкой формата format и записать упакованные байты в записываемый буфер buffer, начиная с позиции offset. Обратите внимание, что offset является обязательным аргументом.
struct. unpack ( format, buffer ) ¶
Распаковать из буфера buffer (предположительно упакованного pack(format, . ) ) в соответствии со строкой формата format. Результатом будет кортеж, даже если он содержит ровно один элемент. Размер буфера в байтах должен соответствовать размеру, требуемому форматом, как это отражено в calcsize() .
struct. unpack_from ( format, buffer, offset=0 ) ¶
Распаковывает из buffer, начиная с позиции offset, в соответствии со строкой формата format. Результатом будет кортеж, даже если он содержит ровно один элемент. Размер буфера в байтах, начиная с позиции offset, должен быть не меньше размера, требуемого форматом, как это отражено в calcsize() .
struct. iter_unpack ( format, buffer ) ¶
Итеративно распаковывает из буфера buffer согласно строке формата format. Функция возвращает итератор, который будет читать куски одинакового размера из буфера до тех пор, пока всё его содержимое не будет использовано. Размер буфера в байтах должен быть кратен размеру, требуемому форматом, как это отражено в calcsize() .
Каждая итерация отдаёт кортеж, указанный в строке формата.
Возвращает размер структуры (и, следовательно, объекта байтов, созданного pack(format, . ) ), соответствующего строке формата format.
Строки формата¶
Строки формата — это используемый механизм для указания ожидаемого макета при упаковке и распаковке данных. Они создаются из Форматные символы , определяющие тип данных, которые должны быть упакованы/распакованы. Кроме того, есть специальные символы для управления Порядок байтов, размер и выравнивание .
Порядок байтов, размер и выравнивание¶
По умолчанию типы C представлены в родном формате и порядке байтов компьютера, а также если это необходимо, выравниваются путём пропуска байтов набивки (pad) (в соответствии с правилами, используемыми C компилятором).
В качестве альтернативы, первый символ строки формата может использоваться для указания порядка байтов, размера и выравнивания упакованных данных в соответствии со следующей таблицей:
| Символ | Порядок байтов | Размер | Выравнивание |
|---|---|---|---|
| @ | родной | родной | родной |
| = | родной | стандарт | никакого |
| little-endian | стандарт | никакого | |
| > | big-endian | стандарт | никакого |
| ! | сеть (= big-endian) | стандарт | никакого |
Если первый символ не является одним из них, предполагается ‘@’ .
Родной порядок байтов — big-endian (от старшего к младшему) или little-endian (от младшего к старшему) байтов, в зависимости от хост-системы. Например, у Intel x86 и AMD64 (x86-64) little-endian; у Motorola 68000 и PowerPC G5 big-endian порядок байтов; ARM и Intel Itanium поддерживают переключаемый порядок следования байтов (bi-endian). Используйте sys.byteorder , чтобы проверить порядок байтов в вашей системе.
Родной размер и выравнивание определяются с помощью выражения sizeof компилятора C. Он всегда сочетается с родным порядком байтов.
Стандартный размер зависит только от форматного символа; см. таблицу в разделе Форматные символы .
Обратите внимание на разницу между ‘@’ и ‘=’ : оба используют родной порядок байтов, но размер и выравнивание последнего стандартизированы.
Форма ‘!’ представляет сетевой порядок байтов, который всегда является big-endian порядком байтов, как определено в IETF RFC 1700.
Невозможно указать неродной порядок байтов (принудительная замена байтов); используйте соответствующий выбор » .
- Заполнение автоматически добавляется только между последовательными членами структуры. Заполнение не добавляется ни в начале, ни в конце закодированной структуры.
- При использовании нестандартного размера и выравнивания отступы не добавляются, например с «», «=» и «!».
- Чтобы выровнять конец структуры в соответствии с требованием выравнивания определенного типа, завершите формат кодом для этого типа с нулевым числом повторений. См. Примеры .
Форматные символы¶
У форматные символы выполняют преобразование между значениями C и Python очевидным образом, с учётом их типов. Столбец «Стандартный размер» относится к размеру упакованного значения в байтах при использовании стандартного размера; т. е., когда строка формата начинается с одного из » , ‘!’ или ‘=’ . При использовании родного размера размер упакованного значения зависит от платформы.
| Формат | C Тип | Python тип | Стандартный размер | Примечания |
|---|---|---|---|---|
| x | байт набивки | нет значения | ||
| c | char | байты длины 1 | 1 | |
| b | signed char | integer | 1 | (1), (2) |
| B | unsigned char | integer | 1 | (2) |
| ? | _Bool | bool | 1 | (1) |
| h | short | integer | 2 | (2) |
| H | unsigned short | integer | 2 | (2) |
| i | int | integer | 4 | (2) |
| I | unsigned int | integer | 4 | (2) |
| l | long | integer | 4 | (2) |
| L | unsigned long | integer | 4 | (2) |
| q | long long | integer | 8 | (2) |
| Q | unsigned long long | integer | 8 | (2) |
| n | ssize_t | integer | (3) | |
| N | size_t | integer | (3) | |
| e | (6) | float | 2 | (4) |
| f | float | float | 4 | (4) |
| d | double | float | 8 | (4) |
| s | char[] | bytes | ||
| p | char[] | bytes | ||
| P | void * | integer | (5) |
Изменено в версии 3.3: Добавлена поддержка ‘n’ и ‘N’ форматов.
Изменено в версии 3.6: Добавлена поддержка ‘e’ формата.
- Код преобразования ‘?’ соответствует типу _Bool , определенному C99. Если этот тип недоступен, он моделируется с помощью char . В стандартном режиме он всегда представлен одним байтом.
- При попытке упаковать нецелое число с использованием любого из кодов преобразования целого числа, то вызывается метод __index__() для преобразования аргумента в целое число перед упаковкой, если у нецелого числа есть данный метод.
Форматному символу может предшествовать целое число повторов. Например, строка формата ‘4h’ означает то же самое, что и ‘hhhh’ .
Пробелы между форматами игнорируются; однако счетчик и его формат не должны содержать пробелов.
Для символа формата ‘s’ счётчик интерпретируется как длина байтов, а не как счётчик повторов, как для других форматных символов; например, ’10s’ означает одну 10-байтовую строку, а ’10c’ означает 10 символов. Если счётчик не указан, по умолчанию он равен 1. Для упаковки строка усекается или дополняется нулевыми байтами, чтобы она соответствовала размеру. Для распаковки у результирующего объекта байтов всегда будет точно указанное количество байтов. В особом случае ‘0s’ означает одну пустую строку (в то время как ‘0c’ означает 0 символов).
При упаковке значения x с использованием одного из целочисленных форматов ( ‘b’ , ‘B’ , ‘h’ , ‘H’ , ‘i’ , ‘I’ , ‘l’ , ‘L’ , ‘q’ , ‘Q’ ), если x выходит за пределы допустимого диапазона для этого формата, тогда возникает struct.error .
Изменено в версии 3.1: В версии 3.0 некоторые целочисленные форматы обёрнуты значениями, выходящие за пределы допустимого диапазона поднимали DeprecationWarning вместо struct.error .
Символ формата ‘p’ кодирует «Pascal строку», означающую короткую строку переменной длины, хранящуюся в фиксированном количестве байтов, заданную счётчиком. Первый сохраненный байт — это длина строки или 255, в зависимости от того, что меньше. Далее следуют байты строки. Если строка, переданная в pack() , слишком длинная (длиннее, чем счетчик минус 1), сохраняются только начальные байты count-1 строки. Если строка короче, чем count-1 , она дополняется нулевыми байтами, чтобы использовалось точное количество байтов. Обратите внимание, что для unpack() форматный символ ‘p’ занимает count байтов, но возвращаемая строка никогда не может содержать более 255 байтов.
Для форматного символа ‘?’ возвращаемое значение — True или False . При упаковке используется значение истинности объекта аргумента. Будут упаковываться либо 0, либо 1 в родном или стандартном логическом представлении, и любое ненулевое значение при распаковке будет True .
Примеры¶
Все примеры предполагают родной порядок байтов, размер и выравнивание с big-endian порядком байт.
Базовый пример упаковки/распаковки трёх целых чисел:
>>> 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(', record) >>> from collections import namedtuple >>> Student = namedtuple('Student', 'name serialnum school gradelevel') >>> Student._make(unpack(', 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'
Это работает только тогда, когда действуют родной размер и выравнивание; стандартный размер и выравнивание не требуют выравнивания.
Модуль array Упакованное двоичное хранилище однородных данных. Модуль xdrlib Упаковка и распаковка XDR данных.
Классы¶
Модуль struct также определяет следующий тип:
class struct. Struct ( format ) ¶
Возвращает новый объект Struct, который записывает и считывает двоичные данные в соответствии со строкой формата format. Создание объекта Struct один раз и вызов его методов более эффективен, чем вызов функций struct с тем же форматом, поскольку строку формата нужно скомпилировать только один раз.
Скомпилированные версии самых последних строк формата, переданных в Struct , и функции уровня модуля кэшируются, поэтому программам, использующим только несколько строк формата, не нужно беспокоиться о повторном использовании одного экземпляра Struct .
Скомпилированные объекты Struct поддерживают следующие методы и атрибуты:
Идентично функции pack() с использованием скомпилированного формата. ( len(result) будет равняться size .)
Идентично функции pack_into() с использованием скомпилированного формата.
Идентично функции unpack() с использованием скомпилированного формата. Размер буфера в байтах должен быть равен size .
unpack_from ( buffer, offset=0 ) ¶
Идентичен функции unpack_from() с использованием скомпилированного формата. Размер буфера в байтах, начиная с позиции offset, должен быть не менее size .
Идентично функции iter_unpack() с использованием скомпилированного формата. Размер буфера в байтах должен быть кратным size .
Строка формата, используемая для создания этого объекта Struct.
Изменено в версии 3.7: Тип форматной строки теперь str вместо bytes .
Вычисленный размер структуры (и, следовательно, объекта байтов, созданного методом pack() ), соответствующего format .