struct.md

1> **Источник:** https://python-all.ru/3.3/library/struct.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 7.1. [`struct`](https://python-all.ru/3.3/library/struct.html#module-struct) – интерпретация байтов как упакованных двоичных данных89Этот модуль выполняет преобразования между значениями Python и C-структурами, представленными в виде объектов Python [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes). Его можно использовать для обработки двоичных данных, хранящихся в файлах или получаемых из сетевых соединений, а также других источников. Он использует [*строки форматирования*](https://python-all.ru/3.3/library/struct.html#struct-format-strings) как компактное описание структуры C-структур и предполагаемого преобразования в/из значений Python.1011> **Примечание**12>13> По умолчанию результат упаковки заданной C-структуры включает байты заполнения для сохранения правильного выравнивания задействованных C-типов; аналогично выравнивание учитывается при распаковке. Такое поведение выбрано для того, чтобы байты упакованной структуры в точности соответствовали расположению в памяти соответствующей C-структуры. Для обработки платформо-независимых форматов данных или отказа от неявных байтов заполнения используйте `стандартный` размер и выравнивание вместо `собственного` размера и выравнивания: подробнее см. [*Порядок байтов, размер и выравнивание*](https://python-all.ru/3.3/library/struct.html#struct-alignment).1415## 7.1.1. Функции и исключения1617Модуль определяет следующие исключения и функции:1819#### `exception struct.error`2021Исключение, вызываемое в различных ситуациях; аргумент – строка, описывающая, что не так.2223#### `struct.pack(fmt, v1, v2, ...)`2425Возвращает объект bytes, содержащий значения *v1*, *v2*, ..., упакованные в соответствии со строкой форматирования *fmt*. Аргументы должны точно соответствовать значениям, требуемым форматом.2627#### `struct.pack_into(fmt, buffer, offset, v1, v2, ...)`2829Упаковывает значения *v1*, *v2*, ... в соответствии со строкой формата *fmt* и записывает упакованные байты в буфер *buffer*, начиная с позиции *offset*. Обратите внимание: *offset* – обязательный аргумент.3031#### `struct.unpack(fmt, buffer)`3233Распаковывает из буфера *buffer* (предположительно упакованного с помощью `pack(fmt, ...)`) в соответствии со строкой форматирования *fmt*. Результатом является кортеж, даже если он содержит ровно один элемент. Буфер должен содержать ровно столько данных, сколько требуется форматом (`len(bytes)` должно равняться `calcsize(fmt)`).3435#### `struct.unpack_from(fmt, buffer, offset=0)`3637Распаковывает из *buffer*, начиная с позиции *offset*, в соответствии со строкой форматирования *fmt*. Результатом является кортеж, даже если он содержит ровно один элемент. *buffer* должен содержать как минимум столько данных, сколько требуется форматом (`len(buffer[offset:])` должно быть не меньше `calcsize(fmt)`).3839#### `struct.calcsize(fmt)`4041Возвращает размер структуры (и, следовательно, объекта bytes, создаваемого `pack(fmt, ...)`), соответствующий строке форматирования *fmt*.4243## 7.1.2. Строки формата4445Строки формата – это механизм, используемый для указания ожидаемого расположения данных при упаковке и распаковке. Они составляются из [*символов формата*](https://python-all.ru/3.3/library/struct.html#format-characters), которые задают тип упаковываемых/распаковываемых данных. Кроме того, существуют специальные символы для управления [*порядком байтов, размером и выравниванием*](https://python-all.ru/3.3/library/struct.html#struct-alignment).4647### 7.1.2.1. Порядок байтов, размер и выравнивание4849По умолчанию типы C представляются в собственном формате и порядке байтов машины и правильно выравниваются путём пропуска байтов заполнения при необходимости (в соответствии с правилами, используемыми компилятором C).5051В качестве альтернативы, первый символ строки формата может использоваться для указания порядка байтов, размера и выравнивания упакованных данных, как показано в следующей таблице:5253| Символ | Порядок байтов | Размер | Выравнивание |54| --- | --- | --- | --- |55| `@` | собственный | собственный | собственный |56| `=` | собственный | стандартный | нет |57| `<` | little-endian | стандартный | нет |58| `>` | big-endian | стандартный | нет |59| `!` | сетевой порядок байт (= big-endian) | стандартный | нет |6061Если первый символ не один из этих, предполагается `'@'`.6263Собственный порядок байтов может быть big-endian или little-endian в зависимости от хост-системы. Например, Intel x86 и AMD64 (x86-64) используют little-endian; Motorola 68000 и PowerPC G5 – big-endian; ARM и Intel Itanium поддерживают переключаемый порядок байтов (bi-endian). Используйте `sys.byteorder` для проверки порядка байтов вашей системы.6465Собственный размер и выравнивание определяются с помощью выражения `sizeof` компилятора C. Это всегда сочетается с собственным порядком байтов.6667Стандартный размер зависит только от символа формата; см. таблицу в разделе [*Символы формата*](https://python-all.ru/3.3/library/struct.html#format-characters).6869Обратите внимание на различие между `'@'` и `'='`: оба используют собственный порядок байт, но размер и выравнивание второго стандартизированы.7071Форма `'!'` доступна для тех несчастных, кто утверждает, что не может запомнить, является ли сетевой порядок байтов big-endian или little-endian.7273Нет способа указать несобственный порядок байт (принудительную перестановку байт); используйте соответствующий выбор из `'<'` или `'>'`.7475Примечания:76771. Заполнение автоматически добавляется только между последовательными членами структуры. Начало и конец закодированной структуры не дополняются.782. Заполнение не добавляется при использовании несобственного размера и выравнивания, например, с ‘\<’, ‘\>’, ‘=’ и ‘!’.793. Чтобы выровнять конец структуры по требованию выравнивания конкретного типа, завершите формат кодом этого типа с нулевым количеством повторений. См. [*Примеры*](https://python-all.ru/3.3/library/struct.html#struct-examples).8081### 7.1.2.2. Символы формата8283Символы формата имеют следующее значение; преобразование между значениями C и Python должно быть очевидным, исходя из их типов. Столбец «Стандартный размер» указывает размер упакованного значения в байтах при использовании стандартного размера; то есть когда строка формата начинается с одного из `'<'`, `'>'`, `'!'` или `'='`. При использовании собственного размера размер упакованного значения зависит от платформы.8485| Формат | Тип C | Тип Python | Стандартный размер | Примечания |86| --- | --- | --- | --- | --- |87| `x` | байт заполнения | нет значения |  |  |88| `c` | `char` | строка байт длиной 1 | 1 |  |89| `b` | `signed char` | целое число | 1 | (1),(3) |90| `B` | `unsigned char` | целое число | 1 | (3) |91| `?` | `_Bool` | bool | 1 | (1) |92| `h` | `short` | целое число | 2 | (3) |93| `H` | `unsigned short` | целое число | 2 | (3) |94| `i` | `int` | целое число | 4 | (3) |95| `I` | `unsigned int` | целое число | 4 | (3) |96| `l` | `long` | целое число | 4 | (3) |97| `L` | `unsigned long` | целое число | 4 | (3) |98| `q` | `long long` | целое число | 8 | (2), (3) |99| `Q` | `unsigned long long` | целое число | 8 | (2), (3) |100| `n` | `ssize_t` | целое число |  | (4) |101| `N` | `size_t` | целое число |  | (4) |102| `f` | `float` | float | 4 | (5) |103| `d` | `double` | float | 8 | (5) |104| `s` | `char[]` | байты |  |  |105| `p` | `char[]` | байты |  |  |106| `P` | `void *` | целое число |  | (6) |107108Изменено в версии 3.3: Добавлена поддержка форматов `'n'` и `'N'`.109110Примечания:1111121. Код преобразования `'?'` соответствует типу `_Bool`, определённому в C99. Если этот тип недоступен, он имитируется с помощью `char`. В стандартном режиме он всегда представлен одним байтом.1132. Коды преобразования `'q'` и `'Q'` доступны в родном режиме, только если компилятор C платформы поддерживает C `long long` или, в Windows, `__int64`. Они всегда доступны в стандартных режимах.1143. При попытке упаковать нецелое число с помощью любого из кодов целочисленного преобразования, если у нецелого числа есть метод [`__index__()`](https://python-all.ru/3.3/reference/datamodel.html#object.__index__), то этот метод вызывается для преобразования аргумента в целое число перед упаковкой.115116   Изменено в версии 3.2: Использование метода [`__index__()`](https://python-all.ru/3.3/reference/datamodel.html#object.__index__) для нецелых чисел появилось в версии 3.2.1174. Коды преобразования `'n'` и `'N'` доступны только для родного размера (выбранного по умолчанию или с помощью символа порядка байтов `'@'`). Для стандартного размера можно использовать любой другой целочисленный формат, подходящий для вашего приложения.1185. Для кодов преобразования `'f'` и `'d'` упакованное представление использует формат IEEE 754 binary32 (для `'f'`) или binary64 (для `'d'`), независимо от формата чисел с плавающей запятой, используемого платформой.1196. Символ формата `'P'` доступен только для родного порядка байтов (выбранного по умолчанию или с помощью символа порядка байтов `'@'`). Символ порядка байтов `'='` выбирает порядок little- или big-endian в зависимости от хост-системы. Модуль struct не интерпретирует это как родной порядок, поэтому формат `'P'` недоступен.120121Символу формата может предшествовать целочисленный счетчик повторений. Например, строка формата `'4h'` означает то же самое, что и `'hhhh'`.122123Пробельные символы между форматами игнорируются; однако счётчик и его формат не должны содержать пробелов.124125Для символа формата `'s'` счетчик интерпретируется как длина строки в байтах, а не как счетчик повторений, как для других символов формата; например, `'10s'` означает одну строку из 10 байтов, тогда как `'10c'` означает 10 символов. Если счетчик не задан, по умолчанию он равен 1. При упаковке строка усекается или дополняется нулевыми байтами по мере необходимости, чтобы соответствовать. При распаковке результирующий объект bytes всегда содержит ровно указанное количество байтов. Как частный случай, `'0s'` означает одну пустую строку (тогда как `'0c'` означает 0 символов).126127При упаковке значения `x` с использованием одного из целочисленных форматов (`'b'`, `'B'`, `'h'`, `'H'`, `'i'`, `'I'`, `'l'`, `'L'`, `'q'`, `'Q'`), если `x` выходит за допустимый диапазон для этого формата, то возбуждается [`struct.error`](https://python-all.ru/3.3/library/struct.html#struct.error).128129Изменено в версии 3.1: В версии 3.0 некоторые целочисленные форматы обрабатывали значения, выходящие за пределы, и возбуждали [`DeprecationWarning`](https://python-all.ru/3.3/library/exceptions.html#DeprecationWarning) вместо [`struct.error`](https://python-all.ru/3.3/library/struct.html#struct.error).130131Символ формата `'p'` кодирует «строку Паскаля», то есть короткую строку переменной длины, хранящуюся в *фиксированном количестве байтов*, заданном счетчиком. Первый сохраненный байт – это длина строки или 255, в зависимости от того, что меньше. Затем следуют байты строки. Если строка, переданная в [`pack()`](https://python-all.ru/3.3/library/struct.html#struct.pack), слишком длинная (длиннее, чем count минус 1), сохраняются только первые `count-1` байтов строки. Если строка короче `count-1`, она дополняется нулевыми байтами, так что всего используется ровно count байтов. Обратите внимание, что для [`unpack()`](https://python-all.ru/3.3/library/struct.html#struct.unpack) символ формата `'p'` потребляет `count` байтов, но возвращаемая строка никогда не может содержать более 255 байтов.132133Для символа формата `'?'` возвращаемое значение – либо [`True`](https://python-all.ru/3.3/library/constants.html#True), либо [`False`](https://python-all.ru/3.3/library/constants.html#False). При упаковке используется истинностное значение объекта-аргумента. Будет упаковано 0 или 1 в родном или стандартном представлении bool, а при распаковке любое ненулевое значение станет `True`.134135### 7.1.2.3. Примеры136137> **Примечание**138>139> Все примеры предполагают собственный порядок байтов, размер и выравнивание на машине с big-endian.140141Простой пример упаковки/распаковки трёх целых чисел:142143```python144>>> from struct import *145>>> pack('hhl', 1, 2, 3)146b'\x00\x01\x00\x02\x00\x00\x00\x03'147>>> unpack('hhl', b'\x00\x01\x00\x02\x00\x00\x00\x03')148(1, 2, 3)149>>> calcsize('hhl')1508151```152153Распакованные поля можно именовать, присваивая их переменным или оборачивая результат в именованный кортеж:154155```python156>>> record = b'raymond   \x32\x12\x08\x01\x08'157>>> name, serialnum, school, gradelevel = unpack('<10sHHb', record)158159>>> from collections import namedtuple160>>> Student = namedtuple('Student', 'name serialnum school gradelevel')161>>> Student._make(unpack('<10sHHb', record))162Student(name=b'raymond   ', serialnum=4658, school=264, gradelevel=8)163```164165Порядок символов формата может влиять на размер, поскольку заполнение, необходимое для удовлетворения требований выравнивания, отличается:166167```python168>>> pack('ci', b'*', 0x12131415)169b'*\x00\x00\x00\x12\x13\x14\x15'170>>> pack('ic', 0x12131415, b'*')171b'\x12\x13\x14\x15*'172>>> calcsize('ci')1738174>>> calcsize('ic')1755176```177178Следующий формат `'llh0l'` указывает два байта заполнения в конце, при условии, что значения long выровнены по границе 4 байта:179180```python181>>> pack('llh0l', 1, 2, 3)182b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'183```184185Это работает только при использовании собственного размера и выравнивания; стандартный размер и выравнивание не обеспечивают никакого выравнивания.186187> **См. также**188>189> **Модуль [`array`](https://python-all.ru/3.3/library/array.html#module-array)**190>191> Упакованное бинарное хранение однородных данных.192>193> **Модуль [`xdrlib`](https://python-all.ru/3.3/library/xdrlib.html#module-xdrlib)**194>195> Упаковка и распаковка данных XDR.196197## 7.1.3. Классы198199Модуль [`struct`](https://python-all.ru/3.3/library/struct.html#module-struct) также определяет следующий тип:200201#### `class struct.Struct(format)`202203Возвращает новый объект Struct, который записывает и читает бинарные данные в соответствии со строкой формата *format*. Создание объекта Struct один раз и вызов его методов более эффективно, чем вызов функций [`struct`](https://python-all.ru/3.3/library/struct.html#module-struct) с тем же форматом, поскольку строку формата нужно скомпилировать только один раз.204205Скомпилированные объекты Struct поддерживают следующие методы и атрибуты:206207#### `pack(v1, v2, ...)`208209Идентично функции [`pack()`](https://python-all.ru/3.3/library/struct.html#struct.pack) с использованием скомпилированного формата. (`len(result)` будет равно `self.size`.)210211#### `pack_into(buffer, offset, v1, v2, ...)`212213Идентично функции [`pack_into()`](https://python-all.ru/3.3/library/struct.html#struct.pack_into) с использованием скомпилированного формата.214215#### `unpack(buffer)`216217Идентично функции [`unpack()`](https://python-all.ru/3.3/library/struct.html#struct.unpack) с использованием скомпилированного формата. (`len(buffer)` должно быть равно `self.size`).218219#### `unpack_from(buffer, offset=0)`220221Идентично функции [`unpack_from()`](https://python-all.ru/3.3/library/struct.html#struct.unpack_from) с использованием скомпилированного формата. (`len(buffer[offset:])` должно быть не менее `self.size`).222223#### `format`224225Строка форматирования, используемая для создания этого объекта Struct.226227#### `size`228229Вычисленный размер структуры (и, соответственно, объекта bytes, создаваемого методом [`pack()`](https://python-all.ru/3.3/library/struct.html#struct.pack)) для [`format`](https://python-all.ru/3.3/library/functions.html#format).230