struct.md

1> **Источник:** https://python-all.ru/3.1/library/struct.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 7.3. `struct` – Интерпретация байтов как упакованных двоичных данных89Этот модуль выполняет преобразования между значениями Python и C-структурами, представленными в виде объектов Python [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes). Его можно использовать для обработки двоичных данных, хранящихся в файлах или получаемых из сетевых соединений, а также других источников. Он использует [*строки форматирования*](https://python-all.ru/3.1/library/struct.html#struct-format-strings) как компактное описание структуры C-структур и предполагаемого преобразования в/из значений Python.1011> **Примечание**12>13> По умолчанию результат упаковки заданной C-структуры включает байты заполнения для сохранения правильного выравнивания соответствующих типов C; аналогично, выравнивание учитывается при распаковке. Такое поведение выбрано для того, чтобы байты упакованной структуры точно соответствовали расположению в памяти соответствующей C-структуры. Для работы с платформонезависимыми форматами данных или для пропуска неявных байтов заполнения используйте *стандартный* размер и выравнивание вместо *собственного* размера и выравнивания: подробнее см. [*Порядок байтов, размер и выравнивание*](https://python-all.ru/3.1/library/struct.html#struct-alignment).1415## 7.3.1. Функции и исключения1617Модуль определяет следующие исключения и функции:1819#### `exception struct.error`2021Исключение, вызываемое в различных ситуациях; аргумент – строка, описывающая, что не так.2223#### `struct.pack(fmt, v1, v2, ...)`2425Возвращает объект bytes, содержащий значения2627*v1*2829,3031*v2*3233, ..., упакованные в соответствии со строкой форматирования3435*fmt*3637. Аргументы должны точно соответствовать значениям, требуемым форматом.3839#### `struct.pack_into(fmt, buffer, offset, v1, v2, ...)`4041Упаковывает значения4243*v1*4445,4647*v2*4849, ... в соответствии со строкой формата5051*fmt*5253и записывает упакованные байты в буфер5455*buffer*5657, начиная с позиции5859*offset*6061. Обратите внимание:6263*offset*6465– обязательный аргумент.6667#### `struct.unpack(fmt, buffer)`6869Распаковывает из буфера7071*buffer*7273(предположительно упакованного с помощью7475`pack(fmt, ...)`7677) в соответствии со строкой форматирования7879*fmt*8081. Результатом является кортеж, даже если он содержит ровно один элемент. Буфер должен содержать ровно столько данных, сколько требуется форматом (8283`len(bytes)`8485должно равняться8687`calcsize(fmt)`8889).9091#### `struct.unpack_from(fmt, buffer, offset=0)`9293Распаковывает из9495*buffer*9697, начиная с позиции9899*offset*100101, в соответствии со строкой форматирования102103*fmt*104105. Результатом является кортеж, даже если он содержит ровно один элемент.106107*buffer*108109должен содержать как минимум столько данных, сколько требуется форматом (110111`len(buffer[offset:])`112113должно быть не меньше114115`calcsize(fmt)`116117).118119#### `struct.calcsize(fmt)`120121Возвращает размер структуры (и, следовательно, объекта bytes, создаваемого122123`pack(fmt, ...)`124125), соответствующий строке форматирования126127*fmt*128129.130131## 7.3.2. Строки формата132133Строки формата – это механизм, используемый для указания ожидаемого расположения данных при упаковке и распаковке. Они составляются из [*символов формата*](https://python-all.ru/3.1/library/struct.html#format-characters), которые задают тип упаковываемых/распаковываемых данных. Кроме того, существуют специальные символы для управления [*порядком байтов, размером и выравниванием*](https://python-all.ru/3.1/library/struct.html#struct-alignment).134135### 7.3.2.1. Порядок байтов, размер и выравнивание136137По умолчанию типы C представляются в собственном формате и порядке байтов машины и правильно выравниваются путём пропуска байтов заполнения при необходимости (в соответствии с правилами, используемыми компилятором C).138139В качестве альтернативы, первый символ строки формата может использоваться для указания порядка байтов, размера и выравнивания упакованных данных, как показано в следующей таблице:140141| Символ | Порядок байтов | Размер | Выравнивание |142| --- | --- | --- | --- |143| `@` | собственный | собственный | собственный |144| `=` | собственный | стандартный | нет |145| `<` | little-endian | стандартный | нет |146| `>` | big-endian | стандартный | нет |147| `!` | сетевой порядок байт (= big-endian) | стандартный | нет |148149Если первый символ не один из этих, предполагается `'@'`.150151Собственный порядок байтов может быть big-endian или little-endian в зависимости от хост-системы. Например, Intel x86 и AMD64 (x86-64) используют little-endian; Motorola 68000 и PowerPC G5 – big-endian; ARM и Intel Itanium поддерживают переключаемый порядок байтов (bi-endian). Используйте `sys.byteorder` для проверки порядка байтов вашей системы.152153Собственный размер и выравнивание определяются с помощью выражения `sizeof` компилятора C. Это всегда сочетается с собственным порядком байтов.154155Стандартный размер зависит только от символа формата; см. таблицу в разделе [*Символы формата*](https://python-all.ru/3.1/library/struct.html#format-characters).156157Обратите внимание на различие между `'@'` и `'='`: оба используют собственный порядок байт, но размер и выравнивание второго стандартизированы.158159Форма `'!'` доступна для тех несчастных, кто утверждает, что не может запомнить, является ли сетевой порядок байтов big-endian или little-endian.160161Нет способа указать несобственный порядок байт (принудительную перестановку байт); используйте соответствующий выбор из `'<'` или `'>'`.162163Примечания:1641651. Заполнение автоматически добавляется только между последовательными членами структуры. Начало и конец закодированной структуры не дополняются.1662. Заполнение не добавляется при использовании несобственного размера и выравнивания, например, с ‘\<’, ‘\>’, ‘=’ и ‘!’.1673. Чтобы выровнять конец структуры по требованию выравнивания конкретного типа, завершите формат кодом этого типа с нулевым количеством повторений. См. [*Примеры*](https://python-all.ru/3.1/library/struct.html#struct-examples).168169### 7.3.2.2. Символы формата170171Символы формата имеют следующее значение; преобразование между значениями C и Python должно быть очевидным, исходя из их типов. Столбец «Стандартный размер» указывает размер упакованного значения в байтах при использовании стандартного размера; то есть когда строка формата начинается с одного из `'<'`, `'>'`, `'!'` или `'='`. При использовании собственного размера размер упакованного значения зависит от платформы.172173| Формат | Тип C | Тип Python | Стандартный размер | Примечания |174| --- | --- | --- | --- | --- |175| `x` | байт заполнения | нет значения |  |  |176| `c` | `char` | строка байт длиной 1 | 1 |  |177| `b` | `знаковый char` | целое число | 1 | (1) |178| `B` | `unsigned char` | целое число | 1 |  |179| `?` | `_Bool` | bool | 1 | (2) |180| `h` | `short` | целое число | 2 |  |181| `H` | `unsigned short` | целое число | 2 |  |182| `i` | `int` | целое число | 4 |  |183| `I` | `unsigned int` | целое число | 4 |  |184| `l` | `long` | целое число | 4 |  |185| `L` | `unsigned long` | целое число | 4 |  |186| `q` | `long long` | целое число | 8 | (3) |187| `Q` | `unsigned long long` | целое число | 8 | (3) |188| `f` | `float` | float | 4 | (4) |189| `d` | `double` | float | 8 | (4) |190| `s` | `char[]` | байты |  | (1) |191| `p` | `char[]` | байты |  | (1) |192| `P` | `void *` | целое число |  | (5) |193194Примечания:1951961. Коды преобразования `c`, `s` и `p` работают с объектами [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), но упаковка с этими кодами также поддерживает объекты [`str`](https://python-all.ru/3.1/library/functions.html#str), которые кодируются с использованием UTF-8.1972. Код преобразования `'?'` соответствует типу `_Bool`, определённому в C99. Если этот тип недоступен, он имитируется с помощью `char`. В стандартном режиме он всегда представлен одним байтом.1983. Коды преобразования `'q'` и `'Q'` доступны в родном режиме, только если компилятор C платформы поддерживает C `long long` или, в Windows, `__int64`. Они всегда доступны в стандартных режимах.1994. Для кодов преобразования `'f'` и `'d'` упакованное представление использует формат IEEE 754 binary32 (для `'f'`) или binary64 (для `'d'`), независимо от формата чисел с плавающей запятой, используемого платформой.2005. Символ формата `'P'` доступен только для родного порядка байтов (выбранного по умолчанию или с помощью символа порядка байтов `'@'`). Символ порядка байтов `'='` выбирает порядок little- или big-endian в зависимости от хост-системы. Модуль struct не интерпретирует это как родной порядок, поэтому формат `'P'` недоступен.201202Символу формата может предшествовать целочисленный счетчик повторений. Например, строка формата `'4h'` означает то же самое, что и `'hhhh'`.203204Пробельные символы между форматами игнорируются; однако счётчик и его формат не должны содержать пробелов.205206Для символа формата `'s'` количество интерпретируется как длина строки в байтах, а не как количество повторений, как для других символов формата; например, `'10s'` означает одну строку длиной 10 байт, тогда как `'10c'` означает 10 символов. При упаковке строка усекается или дополняется нулевыми байтами по мере необходимости, чтобы соответствовать заданной длине. При распаковке результирующий объект bytes всегда содержит ровно указанное количество байт. В частном случае `'0s'` означает одну пустую строку (а `'0c'` означает 0 символов).207208При упаковке значения `x` с использованием одного из целочисленных форматов (`'b'`, `'B'`, `'h'`, `'H'`, `'i'`, `'I'`, `'l'`, `'L'`, `'q'`, `'Q'`), если `x` выходит за допустимый диапазон для этого формата, то возбуждается [`struct.error`](https://python-all.ru/3.1/library/struct.html#struct.error).209210Изменено в версии 3.1: В версии 3.0 некоторые целочисленные форматы обрабатывали значения, выходящие за пределы, и возбуждали [`DeprecationWarning`](https://python-all.ru/3.1/library/exceptions.html#DeprecationWarning) вместо [`struct.error`](https://python-all.ru/3.1/library/struct.html#struct.error).211212Символ формата `'p'` кодирует «строку Паскаля», то есть короткую строку переменной длины, хранящуюся в *фиксированном количестве байтов*, заданном счетчиком. Первый сохраненный байт – это длина строки или 255, в зависимости от того, что меньше. Затем следуют байты строки. Если строка, переданная в [`pack()`](https://python-all.ru/3.1/library/struct.html#struct.pack), слишком длинная (длиннее, чем count минус 1), сохраняются только первые `count-1` байтов строки. Если строка короче `count-1`, она дополняется нулевыми байтами, так что всего используется ровно count байтов. Обратите внимание, что для [`unpack()`](https://python-all.ru/3.1/library/struct.html#struct.unpack) символ формата `'p'` потребляет `count` байтов, но возвращаемая строка никогда не может содержать более 255 байтов.213214Для символа формата `'?'` возвращаемым значением является либо [`True`](https://python-all.ru/3.1/library/constants.html#True), либо [`False`](https://python-all.ru/3.1/library/constants.html#False). При упаковке используется истинностное значение объекта-аргумента. Будет упакован либо 0, либо 1 в нативном или стандартном представлении bool, а при распаковке любое ненулевое значение станет True.215216### 7.3.2.3. Примеры217218> **Примечание**219>220> Все примеры предполагают собственный порядок байтов, размер и выравнивание на машине с big-endian.221222Простой пример упаковки/распаковки трёх целых чисел:223224```python225>>> from struct import *226>>> pack('hhl', 1, 2, 3)227b'\x00\x01\x00\x02\x00\x00\x00\x03'228>>> unpack('hhl', b'\x00\x01\x00\x02\x00\x00\x00\x03')229(1, 2, 3)230>>> calcsize('hhl')2318232```233234Распакованные поля можно именовать, присваивая их переменным или оборачивая результат в именованный кортеж:235236```python237>>> record = b'raymond   \x32\x12\x08\x01\x08'238>>> name, serialnum, school, gradelevel = unpack('<10sHHb', record)239240>>> from collections import namedtuple241>>> Student = namedtuple('Student', 'name serialnum school gradelevel')242>>> Student._make(unpack('<10sHHb', record))243Student(name=b'raymond   ', serialnum=4658, school=264, gradelevel=8)244```245246Порядок символов формата может влиять на размер, поскольку заполнение, необходимое для удовлетворения требований выравнивания, отличается:247248```python249>>> pack('ci', '*', 0x12131415)250b'*\x00\x00\x00\x12\x13\x14\x15'251>>> pack('ic', 0x12131415, '*')252b'\x12\x13\x14\x15*'253>>> calcsize('ci')2548255>>> calcsize('ic')2565257```258259Следующий формат `'llh0l'` указывает два байта заполнения в конце, при условии, что значения long выровнены по границе 4 байта:260261```python262>>> pack('llh0l', 1, 2, 3)263b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'264```265266Это работает только при использовании собственного размера и выравнивания; стандартный размер и выравнивание не обеспечивают никакого выравнивания.267268> **См. также**269>270> **Модуль [`array`](https://python-all.ru/3.1/library/array.html#module-array)**271>272> Упакованное бинарное хранение однородных данных.273>274> **Модуль [`xdrlib`](https://python-all.ru/3.1/library/xdrlib.html#module-xdrlib)**275>276> Упаковка и распаковка данных XDR.277278## 7.3.3. Классы279280Модуль `struct` также определяет следующий тип:281282#### `class struct.Struct(format)`283284Возвращает новый объект Struct, который записывает и читает двоичные данные в соответствии с строкой форматирования *format*. Создание объекта Struct один раз и вызов его методов более эффективно, чем вызов функций `struct` с той же строкой форматирования, поскольку её нужно скомпилировать только один раз.285286Скомпилированные объекты Struct поддерживают следующие методы и атрибуты:287288#### `pack(v1, v2, ...)`289290Идентично функции291292[`pack()`](https://python-all.ru/3.1/library/struct.html#struct.pack)293294с использованием скомпилированного формата. (295296`len(result)`297298будет равно299300`self.size`301302.)303304#### `pack_into(buffer, offset, v1, v2, ...)`305306Идентично функции307308[`pack_into()`](https://python-all.ru/3.1/library/struct.html#struct.pack_into)309310с использованием скомпилированного формата.311312#### `unpack(buffer)`313314Идентично функции315316[`unpack()`](https://python-all.ru/3.1/library/struct.html#struct.unpack)317318с использованием скомпилированного формата. (319320`len(buffer)`321322должно быть равно323324`self.size`325326).327328#### `unpack_from(buffer, offset=0)`329330Идентично функции331332[`unpack_from()`](https://python-all.ru/3.1/library/struct.html#struct.unpack_from)333334с использованием скомпилированного формата. (335336`len(buffer[offset:])`337338должно быть не менее339340`self.size`341342).343344#### `format`345346Строка форматирования, используемая для создания этого объекта Struct.347348#### `size`349350Вычисленный размер структуры (и, соответственно, объекта bytes, создаваемого методом351352[`pack()`](https://python-all.ru/3.1/library/struct.html#struct.pack)353354) для355356[`format`](https://python-all.ru/3.1/library/functions.html#format)357358.359