struct — Interpret bytes as packed binary data

소스 코드: Lib/struct.py

This module converts between Python values and C structs represented as Python bytes objects. Compact format strings describe the intended conversions to/from Python values. The module’s functions and objects can be used for two largely distinct applications, data exchange with external sources (files or network connections), or data transfer between the Python application and the C layer.

참고

When no prefix character is given, native mode is the default. It packs or unpacks data based on the platform and compiler on which the Python interpreter was built. The result of packing a given C struct includes pad bytes which maintain proper alignment for the C types involved; similarly, alignment is taken into account when unpacking. In contrast, when communicating data between external sources, the programmer is responsible for defining byte ordering and padding between elements. See 바이트 순서, 크기 및 정렬 for details.

여러 struct 함수(그리고 Struct 의 메서드)는 buffer 인자를 취합니다. 이는 버퍼 프로토콜을 구현하고 읽을 수 있거나 읽고 쓸 수 있는 버퍼를 제공하는 객체를 나타냅니다. 이 목적으로 사용되는 가장 일반적인 형은 bytes와 bytearray지만, 바이트 배열로 볼 수 있는 많은 다른 형이 버퍼 프로토콜을 구현하므로, bytes 객체에서 추가로 복사하지 않고도 읽고 채울 수 있습니다.

함수와 예외

이 모듈은 다음과 같은 예외와 함수를 정의합니다:

exception struct.error

여러 상황에서 발생하는 예외; 인자는 무엇이 잘못되었는지 설명하는 문자열입니다.

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

v1, v2, … 값을 포함하고 포맷 문자열 format에 따라 패킹 된 바이트열 객체를 반환합니다. 인자는 포맷이 요구하는 값과 정확히 일치해야 합니다.

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

포맷 문자열 format에 따라 값 v1, v2, … 를 패킹하고 패킹 된 바이트열을 쓰기 가능한 버퍼 buffer에 offset 위치에서부터 씁니다. offset은 필수 인자임에 유의하십시오.

struct.unpack(format, buffer)

포맷 문자열 format에 따라 버퍼 buffer(아마도 pack(format, ...)으로 패킹 된)에서 언 패킹 합니다. 정확히 하나의 항목을 포함하더라도 결과는 튜플입니다. 바이트 단위의 버퍼 크기는 (calcsize()에 의해 반영되는) 포맷이 요구하는 크기와 일치해야 합니다.

struct.unpack_from(format, /, buffer, offset=0)

포맷 문자열 format에 따라, offset 위치에서 시작하여 buffer에서 언 패킹 합니다. 정확히 하나의 항목을 포함하더라도 결과는 튜플입니다. offset 위치에서 시작하여 바이트 단위로 측정한 버퍼 크기는 (calcsize()에 의해 반영되는) 포맷이 요구하는 크기 이상이어야 합니다.

struct.iter_unpack(format, buffer)

Iteratively unpack from the buffer buffer according to the format string format. This function returns an iterator which will read equally sized chunks from the buffer until all its contents have been consumed. The buffer’s size in bytes must be a multiple of the size required by the format, as reflected by calcsize().

각 이터레이션은 포맷 문자열에 지정된 대로 튜플을 산출합니다.

Added in version 3.4.

struct.calcsize(format)

포맷 문자열 format에 해당하는 구조체(pack(format, ...)에 의해 생성되는 바이트열 객체)의 크기를 반환합니다.

포맷 문자열

Format strings describe the data layout when packing and unpacking data. They are built up from format characters, which specify the type of data being packed/unpacked. In addition, special characters control the byte order, size and alignment. Each format string consists of an optional prefix character which describes the overall properties of the data and one or more format characters which describe the actual data values and padding.

바이트 순서, 크기 및 정렬

By default, C types are represented in the machine’s native format and byte order, and properly aligned by skipping pad bytes if necessary (according to the rules used by the C compiler). This behavior is chosen so that the bytes of a packed struct correspond exactly to the memory layout of the corresponding C struct. Whether to use native byte ordering and padding or standard formats depends on the application.

또는, 다음 표에 따라, 포맷 문자열의 첫 번째 문자를 사용하여 패킹 된 데이터의 바이트 순서, 크기 및 정렬을 표시할 수 있습니다:

문자

바이트 순서

크기

정렬

@

네이티브

네이티브

네이티브

=

네이티브

표준

none

<

리틀 엔디안

표준

none

>

빅 엔디안

표준

none

!

네트워크 (= 빅 엔디안)

표준

none

첫 번째 문자가 이들 중 하나가 아니면, '@'로 가정합니다.

참고

The number 1023 (0x3ff in hexadecimal) has the following byte representations:

  • 03 ff in big-endian (>)

  • ff 03 in little-endian (<)

Python example:

>>> import struct
>>> struct.pack('>h', 1023)
b'\x03\xff'
>>> struct.pack('<h', 1023)
b'\xff\x03'

Native byte order is big-endian or little-endian, depending on the host system. For example, Intel x86, AMD64 (x86-64), and Apple M1 are little-endian; IBM z and many legacy architectures are big-endian. Use sys.byteorder to check the endianness of your system.

네이티브 크기와 정렬은 C 컴파일러의 sizeof 표현식을 사용하여 결정됩니다. 이것은 항상 네이티브 바이트 순서와 결합합니다.

표준 크기는 포맷 문자에만 의존합니다; 포맷 문자 섹션의 표를 참조하십시오.

'@'과 '='의 차이점에 유의하십시오; 둘 다 네이티브 바이트 순서를 사용하지만, 후자는 크기와 정렬이 표준화됩니다.

'!' 형식은 IETF RFC 1700에 정의된 대로 항상 빅 엔디안인 네트워크 바이트 순서를 나타냅니다.

네이티브가 아닌 바이트 순서(강제 바이트 스와핑)를 표시하는 방법은 없습니다; '<'나 '>'를 적절히 선택하십시오.

노트:

  1. 패딩은 연속되는 구조체 멤버 간에만 자동으로 추가됩니다. 인코딩된 구조체의 시작이나 끝에는 패딩이 추가되지 않습니다.

  2. 네이티브가 아닌 크기와 정렬을 사용할 때는 패딩이 추가되지 않습니다, 예를 들어 ‘<’, ‘>’, ‘=’ 및 ‘!’ 에서.

  3. 구조체의 끝을 특정 형의 정렬 요구 사항에 맞추려면, 반복 횟수가 0인 해당 형의 코드로 포맷을 끝내십시오. 예를 참조하십시오.

포맷 문자

포맷 문자는 다음과 같은 의미가 있습니다; C와 파이썬 값 사이의 변환은 형을 주면 분명해야 합니다. ‘표준 크기’ 열은 표준 크기를 사용할 때 패킹 된 값의 크기를 바이트 단위로 나타냅니다; 즉, 포맷 문자열이 '<', '>', '!' 또는 '=' 중 하나로 시작하는 경우입니다. 네이티브 크기를 사용할 때, 패킹 된 값의 크기는 플랫폼에 따라 다릅니다.

포맷

C형

파이썬 형

표준 크기

노트

x

패드 바이트

값이 없습니다

(7)

c

char

길이가 1인 bytes

1

b

signed char

정수

1

(1), (2)

B

unsigned char

정수

1

(2)

?

_Bool

bool

1

(1)

h

short

정수

2

(2)

H

unsigned short

정수

2

(2)

i

int

정수

4

(2)

I

unsigned int

정수

4

(2)

l

long

정수

4

(2)

L

unsigned long

정수

4

(2)

q

long long

정수

8

(2)

Q

unsigned long long

정수

8

(2)

n

ssize_t

정수

(3)

N

size_t

정수

(3)

e

(6)

float

2

(4)

f

float

float

4

(4)

d

double

float

8

(4)

s

char[]

bytes

(9)

p

char[]

bytes

(8)

P

void*

정수

(5)

Additionally, if IEC 60559 compatible complex arithmetic (Annex G of the C11 standard) is supported, the following format characters are available:

포맷

C형

파이썬 형

표준 크기

노트

E

float complex

complex

8

(10)

C

double complex

complex

16

(10)

버전 3.3에서 변경: 'n'과 'N' 포맷에 대한 지원이 추가되었습니다.

버전 3.6에서 변경: 'e' 포맷에 대한 지원이 추가되었습니다.

버전 3.14에서 변경: Added support for the 'E' and 'C' formats.

노트:

  1. The '?' conversion code corresponds to the _Bool type defined by C standards since C99. In standard mode, it is represented by one byte.

  2. When attempting to pack a non-integer using any of the integer conversion codes, if the non-integer has a __index__() method then that method is called to convert the argument to an integer before packing.

    버전 3.2에서 변경: Added use of the __index__() method for non-integers.

  3. 'n'과 'N' 변환 코드는 (기본값이나 '@' 바이트 순서 문자로 선택된) 네이티브 크기에만 사용할 수 있습니다. 표준 크기의 경우, 응용 프로그램에 맞는 다른 정수 포맷을 사용할 수 있습니다.

  4. 'f', 'd' 및 'e' 변환 코드의 경우, 패킹 된 표현은 플랫폼에서 사용하는 부동 소수점 형식과 관계없이 IEEE 754 binary32, binary64 또는 binary16 형식을 사용합니다 (각각 'f', 'd' 또는 'e').

  5. 'P' 포맷 문자는 (기본값이나 '@' 바이트 순서 문자로 선택된) 네이티브 바이트 순서에만 사용할 수 있습니다. 바이트 순서 문자 '='는 호스트 시스템에 따라 리틀이나 빅 엔디안 순서를 사용하도록 선택합니다. struct 모듈은 이를 네이티브 순서로 해석하지 않아서, 'P' 형식을 사용할 수 없습니다.

  6. IEEE 754 binary16 “반 정밀도” 형은 2008년 IEEE 754 표준 개정판에서 도입되었습니다. 부호 비트, 5비트 지수 및 11비트 정밀도(10비트가 명시적으로 저장됩니다)를 가지며, 전체 정밀도에서 대략 6.1e-05와 6.5e+04 사이의 숫자를 나타낼 수 있습니다. 이 형은 C 컴파일러에서 널리 지원되지 않습니다: 일반적인 기계에서는, unsigned short를 저장에 사용할 수 있지만, 수학 연산에는 사용할 수 없습니다. 자세한 내용은 half-precision floating-point format의 Wikipedia 페이지를 참조하십시오.

  7. When packing, 'x' inserts one NUL byte.

  8. 'p' 포맷 문자는 “파스칼 문자열”을 인코딩하는데, 이는 카운트에 의해 주어진 고정된 바이트 수에 저장된 짧은 가변 길이 문자열을 의미합니다. 저장된 첫 번째 바이트는 문자열의 길이나 255중 작은 값입니다. 문자열의 바이트가 그 뒤에 옵니다. pack()에 전달된 문자열이 너무 길면 (횟수 빼기 1보다 길면), 문자열의 선행 count-1 바이트만 저장됩니다. 문자열이 count-1보다 짧으면, 전부 정확한 바이트 수가 되도록 널 바이트로 채워집니다. unpack()의 경우, 'p' 포맷 문자는 count 바이트를 소비하지만, 반환된 문자열은 255바이트를 초과할 수 없음에 유의하십시오.

  9. For the 's' format character, the count is interpreted as the length of the bytes, not a repeat count like for the other format characters; for example, '10s' means a single 10-byte string mapping to or from a single Python byte string, while '10c' means 10 separate one byte character elements (e.g., cccccccccc) mapping to or from ten different Python byte objects. (See 예 for a concrete demonstration of the difference.) If a count is not given, it defaults to 1. For packing, the string is truncated or padded with null bytes as appropriate to make it fit. For unpacking, the resulting bytes object always has exactly the specified number of bytes. As a special case, '0s' means a single, empty string (while '0c' means 0 characters).

  10. For the 'E' and 'C' format characters, the packed representation uses the IEEE 754 binary32 and binary64 format for components of the complex number, regardless of the floating-point format used by the platform.

포맷 문자 앞에는 정수 반복 횟수가 올 수 있습니다. 예를 들어, 포맷 문자열 '4h'는 'hhhh'와 정확히 같습니다.

포맷 사이의 공백 문자는 무시됩니다; 횟수와 형식 사이에는 공백이 없어야 합니다.

정수 형식 ('b', 'B', 'h', 'H', 'i', 'I', 'l', 'L', 'q', 'Q') 중 하나를 사용하여 값 x를 패킹할 때, x가 해당 포맷의 유효한 범위를 벗어나면 struct.error가 발생합니다.

버전 3.1에서 변경: 이전에는, 일부 정수 포맷은 범위를 벗어난 값을 래핑하고 struct.error 대신 DeprecationWarning을 발생시켰습니다.

'?' 포맷 문자의 경우, 반환 값은 True나 False입니다. 패킹할 때, 인자 객체의 논리값이 사용됩니다. 네이티브나 표준 bool 표현에서 0이나 1이 패킹 되고, 언 패킹할 때 모든 0이 아닌 값은 True가 됩니다.

예

참고

Native byte order examples (designated by the '@' format prefix or lack of any prefix character) may not match what the reader’s machine produces as that depends on the platform and compiler.

Pack and unpack integers of three different sizes, using big endian ordering:

>>> from struct import *
>>> pack(">bhl", 1, 2, 3)
b'\x01\x00\x02\x00\x00\x00\x03'
>>> unpack('>bhl', b'\x01\x00\x02\x00\x00\x00\x03')
(1, 2, 3)
>>> calcsize('>bhl')
7

Attempt to pack an integer which is too large for the defined field:

>>> pack(">h", 99999)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
struct.error: 'h' format requires -32768 <= number <= 32767

Demonstrate the difference between 's' and 'c' format characters:

>>> pack("@ccc", b'1', b'2', b'3')
b'123'
>>> pack("@3s", b'123')
b'123'

언 패킹 된 필드는 변수에 대입하거나 결과를 네임드 튜플로 감싸서 이름을 붙일 수 있습니다:

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

The ordering of format characters may have an impact on size in native mode since padding is implicit. In standard mode, the user is responsible for inserting any desired padding. Note in the first pack call below that three NUL bytes were added after the packed '#' to align the following integer on a four-byte boundary. In this example, the output was produced on a little endian machine:

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

The following format 'llh0l' results in two pad bytes being added at the end, assuming the platform’s longs are aligned on 4-byte boundaries:

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

더 보기

모듈 array

동종 데이터의 패킹 된 바이너리 저장소.

Module json

JSON encoder and decoder.

Module pickle

Python object serialization.

Applications

Two main applications for the struct module exist, data interchange between Python and C code within an application or another application compiled using the same compiler (native formats), and data interchange between applications using agreed upon data layout (standard formats). Generally speaking, the format strings constructed for these two domains are distinct.

Native Formats

When constructing format strings which mimic native layouts, the compiler and machine architecture determine byte ordering and padding. In such cases, the @ format character should be used to specify native byte ordering and data sizes. Internal pad bytes are normally inserted automatically. It is possible that a zero-repeat format code will be needed at the end of a format string to round up to the correct byte boundary for proper alignment of consecutive chunks of data.

Consider these two simple examples (on a 64-bit, little-endian machine):

>>> calcsize('@lhl')
24
>>> calcsize('@llh')
18

Data is not padded to an 8-byte boundary at the end of the second format string without the use of extra padding. A zero-repeat format code solves that problem:

>>> calcsize('@llh0l')
24

The 'x' format code can be used to specify the repeat, but for native formats it is better to use a zero-repeat format like '0l'.

By default, native byte ordering and alignment is used, but it is better to be explicit and use the '@' prefix character.

Standard Formats

When exchanging data beyond your process such as networking or storage, be precise. Specify the exact byte order, size, and alignment. Do not assume they match the native order of a particular machine. For example, network byte order is big-endian, while many popular CPUs are little-endian. By defining this explicitly, the user need not care about the specifics of the platform their code is running on. The first character should typically be < or > (or !). Padding is the responsibility of the programmer. The zero-repeat format character won’t work. Instead, the user must explicitly add 'x' pad bytes where needed. Revisiting the examples from the previous section, we have:

>>> calcsize('<qh6xq')
24
>>> pack('<qh6xq', 1, 2, 3) == pack('@lhl', 1, 2, 3)
True
>>> calcsize('@llh')
18
>>> pack('@llh', 1, 2, 3) == pack('<qqh', 1, 2, 3)
True
>>> calcsize('<qqh6x')
24
>>> calcsize('@llh0l')
24
>>> pack('@llh0l', 1, 2, 3) == pack('<qqh6x', 1, 2, 3)
True

The above results (executed on a 64-bit machine) aren’t guaranteed to match when executed on different machines. For example, the examples below were executed on a 32-bit machine:

>>> calcsize('<qqh6x')
24
>>> calcsize('@llh0l')
12
>>> pack('@llh0l', 1, 2, 3) == pack('<qqh6x', 1, 2, 3)
False

클래스

struct 모듈은 또한 다음 형을 정의합니다:

class struct.Struct(format)

Return a new Struct object which writes and reads binary data according to the format string format. Creating a Struct object once and calling its methods is more efficient than calling module-level functions with the same format since the format string is only compiled once.

참고

The compiled versions of the most recent format strings passed to the module-level functions are cached, so programs that use only a few format strings needn’t worry about reusing a single Struct instance.

컴파일된 Struct 객체는 다음 메서드와 어트리뷰트를 지원합니다:

pack(v1, v2, ...)

pack() 함수와 동일하고, 컴파일된 포맷을 사용합니다. (len(result)는 size와 같게 됩니다.)

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

pack_into() 함수와 동일하고, 컴파일된 포맷을 사용합니다.

unpack(buffer)

unpack() 함수와 동일하고, 컴파일된 포맷을 사용합니다. 바이트 단위의 버퍼 크기는 size와 같아야 합니다.

unpack_from(buffer, offset=0)

unpack_from() 함수와 동일하고, 컴파일된 포맷을 사용합니다. offset 위치에서 시작하는 바이트 단위의 버퍼 크기는 size 이상이어야 합니다.

iter_unpack(buffer)

iter_unpack() 함수와 동일하고, 컴파일된 포맷을 사용합니다. 바이트 단위의 버퍼 크기는 size의 배수이어야 합니다.

Added in version 3.4.

format

이 Struct 객체를 구성하는 데 사용된 포맷 문자열.

버전 3.7에서 변경: 포맷 문자열형은 이제 bytes 대신 str입니다.

size

format에 해당하는 구조체(pack() 메서드에 의해 생성된 바이트열 객체)의 계산된 크기.

버전 3.13에서 변경: The repr() of structs has changed. It is now:

>>> Struct('i')
Struct('i')