struct.md

1> **Источник:** https://python-all.ru/3.0/library/struct.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `struct` – Интерпретация байтов как упакованных двоичных данных89Этот модуль выполняет преобразования между значениями Python и C-структурами, представленными в виде объектов [`bytes`](https://python-all.ru/3.0/library/functions.html#bytes). В нём используются *строки формата* (описаны ниже) как компактные описания расположения C-структур и предполагаемого преобразования в/из значений Python. Это может использоваться для обработки двоичных данных, хранящихся в файлах или полученных из сетевых соединений, среди прочих источников.1011Модуль определяет следующие исключения и функции:1213#### `[struct.error]exception struct.error`1415Исключение, возникающее в различных ситуациях; аргумент – строка, описывающая, что не так.1617#### `[struct.pack]struct.pack(fmt, v1, v2, ...)`1819Возвращает объект bytes, содержащий значения2021`v1, v2, ...`2223, упакованные в соответствии с заданным форматом. Аргументы должны точно соответствовать значениям, требуемым форматом.2425#### `[struct.pack_into]struct.pack_into(fmt, buffer, offset, v1, v2, ...)`2627Упаковывает значения2829`v1, v2, ...`3031в соответствии с заданным форматом и записывает упакованные байты в записываемый3233*buffer*3435, начиная с3637*offset*3839. Обратите внимание, что смещение является обязательным аргументом.4041#### `[struct.unpack]struct.unpack(fmt, bytes)`4243Распаковывает байты (предположительно упакованные с помощью4445`pack(fmt, ...)`4647) в соответствии с заданным форматом. Результатом является кортеж, даже если он содержит ровно один элемент. Байты должны содержать ровно столько данных, сколько требуется форматом (4849`len(bytes)`5051должно равняться5253`calcsize(fmt)`5455).5657#### `[struct.unpack_from]struct.unpack_from(fmt, buffer[, offset=0])`5859Распаковывает6061*buffer*6263в соответствии с заданным форматом. Результатом является кортеж, даже если он содержит ровно один элемент.6465*buffer*6667должен содержать как минимум столько данных, сколько требуется форматом (6869`len(buffer[offset:])`7071должно быть не меньше7273`calcsize(fmt)`7475).7677#### `[struct.calcsize]struct.calcsize(fmt)`7879Возвращает размер структуры (и, соответственно, байтов), соответствующий заданному формату.8081Символы формата имеют следующее значение; преобразование между значениями C и Python должно быть очевидным, учитывая их типы:8283| Формат | Тип C | Python | Примечания |84| --- | --- | --- | --- |85| `x` | байт заполнения | нет значения |  |86| `c` | `char` | строка байт длиной 1 |  |87| `b` | `знаковый char` | целое число | (1) |88| `B` | `unsigned char` | целое число |  |89| `?` | `_Bool` | bool | (2) |90| `h` | `short` | целое число |  |91| `H` | `unsigned short` | целое число |  |92| `i` | `int` | целое число |  |93| `I` | `unsigned int` | целое число |  |94| `l` | `long` | целое число |  |95| `L` | `unsigned long` | целое число |  |96| `q` | `long long` | целое число | (3) |97| `Q` | `unsigned long long` | целое число | (3) |98| `f` | `float` | float |  |99| `d` | `double` | float |  |100| `s` | `char[]` | байты | (1) |101| `p` | `char[]` | байты | (1) |102| `P` | `void *` | целое число |  |103104Примечания:1051061. Коды преобразования `c`, `s` и `p` работают с объектами [`bytes`](https://python-all.ru/3.0/library/functions.html#bytes), но упаковка с этими кодами также поддерживает объекты [`str`](https://python-all.ru/3.0/library/functions.html#str), которые кодируются с использованием UTF-8.1072. Код преобразования `'?'` соответствует типу `_Bool`, определённому в C99. Если этот тип недоступен, он имитируется с помощью `char`. В стандартном режиме он всегда представлен одним байтом.1083. Коды преобразования `'q'` и `'Q'` доступны в родном режиме, только если компилятор C платформы поддерживает C `long long` или, в Windows, `__int64`. Они всегда доступны в стандартных режимах.109110Символу формата может предшествовать целочисленный счетчик повторений. Например, строка формата `'4h'` означает то же самое, что и `'hhhh'`.111112Пробельные символы между форматами игнорируются; однако счётчик и его формат не должны содержать пробелов.113114Для символа формата `'s'` количество интерпретируется как длина строки в байтах, а не как количество повторений, как для других символов формата; например, `'10s'` означает одну строку длиной 10 байт, тогда как `'10c'` означает 10 символов. При упаковке строка усекается или дополняется нулевыми байтами по мере необходимости, чтобы соответствовать заданной длине. При распаковке результирующий объект bytes всегда содержит ровно указанное количество байт. В частном случае `'0s'` означает одну пустую строку (а `'0c'` означает 0 символов).115116Символ формата `'p'` кодирует «строку Паскаля», то есть короткую строку переменной длины, хранящуюся в фиксированном количестве байтов. Значение count – это общее количество сохраняемых байтов. Первый сохраняемый байт – это длина строки или 255, в зависимости от того, что меньше. Затем следуют байты строки. Если строка, переданная в [`pack()`](https://python-all.ru/3.0/library/struct.html#struct.pack), слишком длинная (длиннее, чем count минус 1), сохраняются только первые count-1 байтов строки. Если строка короче count-1, она дополняется нулевыми байтами, чтобы в итоге было использовано ровно count байтов. Обратите внимание, что для [`unpack()`](https://python-all.ru/3.0/library/struct.html#struct.unpack) символ формата `'p'` потребляет count байтов, но возвращаемая строка никогда не может содержать более 255 байтов.117118Для символа формата `'?'` возвращаемым значением является либо [`True`](https://python-all.ru/3.0/library/constants.html#True), либо [`False`](https://python-all.ru/3.0/library/constants.html#False). При упаковке используется истинностное значение объекта-аргумента. Будет упакован либо 0, либо 1 в нативном или стандартном представлении bool, а при распаковке любое ненулевое значение станет True.119120По умолчанию числа C представляются в собственном формате и порядке байтов машины и выравниваются должным образом путём пропуска байтов заполнения при необходимости (в соответствии с правилами, используемыми компилятором C).121122В качестве альтернативы, первый символ строки формата может использоваться для указания порядка байтов, размера и выравнивания упакованных данных, как показано в следующей таблице:123124| Символ | Порядок байтов | Размер и выравнивание |125| --- | --- | --- |126| `@` | собственный | собственный |127| `=` | собственный | стандартный |128| `<` | little-endian | стандартный |129| `>` | big-endian | стандартный |130| `!` | сетевой порядок байт (= big-endian) | стандартный |131132Если первый символ не один из этих, предполагается `'@'`.133134Родной порядок байт – big-endian или little-endian, в зависимости от хост-системы. Например, процессоры Motorola и Sun – big-endian, а Intel и DEC – little-endian.135136Собственный размер и выравнивание определяются с помощью выражения `sizeof` компилятора C. Это всегда сочетается с собственным порядком байтов.137138Стандартные размеры и выравнивание: для любого типа не требуется выравнивание (поэтому необходимо использовать байты заполнения); `short` занимает 2 байта; `int` и `long` – 4 байта; `long long` (`__int64` в Windows) – 8 байт; `float` и `double` – 32-битные и 64-битные числа с плавающей точкой IEEE соответственно. `_Bool` занимает 1 байт.139140Обратите внимание на различие между `'@'` и `'='`: оба используют собственный порядок байт, но размер и выравнивание второго стандартизированы.141142Форма `'!'` доступна для тех несчастных, кто утверждает, что не может запомнить, является ли сетевой порядок байтов big-endian или little-endian.143144Нет способа указать несобственный порядок байт (принудительную перестановку байт); используйте соответствующий выбор из `'<'` или `'>'`.145146Символ формата `'P'` доступен только для родного порядка байт (выбранного по умолчанию или с помощью символа порядка байт `'@'`). Символ порядка байт `'='` выбирает порядок little-endian или big-endian в зависимости от хост-системы. Модуль struct не интерпретирует это как родной порядок, поэтому формат `'P'` недоступен.147148Примеры (все используют родной порядок байт, размеры и выравнивание, на big-endian машине):149150```python151>>> from struct import *152>>> pack('hhl', 1, 2, 3)153b'\x00\x01\x00\x02\x00\x00\x00\x03'154>>> unpack('hhl', b'\x00\x01\x00\x02\x00\x00\x00\x03')155(1, 2, 3)156>>> calcsize('hhl')1578158```159160Подсказка: чтобы выровнять конец структуры под требование выравнивания конкретного типа, завершите формат кодом этого типа с нулевым счётчиком повторений. Например, формат `'llh0l'` задаёт два байта заполнения в конце (в предположении, что long выравниваются по 4-байтовым границам). Это работает только в режиме родных размеров и выравнивания; в стандартном режиме выравнивание не навязывается.161162Распакованные поля можно именовать, присваивая их переменным или оборачивая результат в именованный кортеж:163164```python165>>> record = b'raymond   \x32\x12\x08\x01\x08'166>>> name, serialnum, school, gradelevel = unpack('<10sHHb', record)167168>>> from collections import namedtuple169>>> Student = namedtuple('Student', 'name serialnum school gradelevel')170>>> Student._make(unpack('<10sHHb', record))171Student(name=b'raymond   ', serialnum=4658, school=264, gradelevel=8)172```173174> **См. также**175>176> **Модуль [`array`](https://python-all.ru/3.0/library/array.html#module-array)**177>178> Упакованное бинарное хранение однородных данных.179>180> **Модуль [`xdrlib`](https://python-all.ru/3.0/library/xdrlib.html#module-xdrlib)**181>182> Упаковка и распаковка данных XDR.183184## Объекты Struct185186Модуль `struct` также определяет следующий тип:187188#### `[struct.Struct]class struct.Struct(format)`189190Возвращает новый объект Struct, который записывает и читает двоичные данные в соответствии со строкой формата *format*. Создание объекта Struct один раз и вызов его методов эффективнее, чем вызов функций `struct` с тем же форматом, поскольку строку формата нужно скомпилировать только один раз.191192Скомпилированные объекты Struct поддерживают следующие методы и атрибуты:193194#### `[struct.Struct.pack]pack(v1, v2, ...)`195196Идентично функции197198[`pack()`](https://python-all.ru/3.0/library/struct.html#struct.pack)199200с использованием скомпилированного формата. (201202`len(result)`203204будет равно205206`self.size`207208.)209210#### `[struct.Struct.pack_into]pack_into(buffer, offset, v1, v2, ...)`211212Идентично функции213214[`pack_into()`](https://python-all.ru/3.0/library/struct.html#struct.pack_into)215216с использованием скомпилированного формата.217218#### `[struct.Struct.unpack]unpack(bytes)`219220Идентична функции221222[`unpack()`](https://python-all.ru/3.0/library/struct.html#struct.unpack)223224, использующей скомпилированный формат. (225226`len(bytes)`227228должно быть равно229230`self.size`231232).233234#### `[struct.Struct.unpack_from]unpack_from(buffer[, offset=0])`235236Идентично функции237238[`unpack_from()`](https://python-all.ru/3.0/library/struct.html#struct.unpack_from)239240с использованием скомпилированного формата. (241242`len(buffer[offset:])`243244должно быть не менее245246`self.size`247248).249250#### `[struct.Struct.format]format`251252Строка форматирования, используемая для создания этого объекта Struct.253254#### `[struct.Struct.size]size`255256Вычисленный размер структуры (и, соответственно, размер байтовой строки), соответствующий257258[`format`](https://python-all.ru/3.0/library/functions.html#format)259260.261