# `struct` — Interpret bytes as packed binary data

Código fuente: Lib/struct.py

Este módulo convierte entre valores de Python y estructuras de C representadas como objetos de Python `bytes`. Las cadenas de formato compacto describen las conversiones previstas hacia/desde valores de Python. Las funciones y objetos del módulo se pueden utilizar para dos aplicaciones en gran medida distintas, el intercambio de datos con fuentes externas (archivos o conexiones de red) o la transferencia de datos entre la aplicación de Python y la capa de C.

Nota

Cuando no se proporciona ningún carácter de prefijo, el modo nativo es el predeterminado. Empaqueta o desempaqueta datos según la plataforma y el compilador en el que se creó el intérprete de Python. El resultado de empaquetar una estructura C determinada incluye bytes de relleno que mantienen la alineación adecuada para los tipos C involucrados; asimismo, se tiene en cuenta la alineación al desempaquetar. Por el contrario, cuando se comunican datos entre fuentes externas, el programador es responsable de definir el orden de bytes y el relleno entre elementos. Ver Orden de bytes, tamaño y alineación para más detalles.

Several `struct` functions (and methods of `Struct`) take a buffer argument. This refers to objects that implement the Protocolo búfer and provide either a readable or read-writable buffer. The most common types used for that purpose are `bytes` and `bytearray`, but many other types that can be viewed as an array of bytes implement the buffer protocol, so that they can be read/filled without additional copying from a `bytes` object.

## Funciones y excepciones

El módulo define la siguiente excepción y funciones:

exception struct.error

  Excepción lanzada en varias ocasiones; el argumento es una string que describe lo que está mal.

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

  Retorna un objeto bytes que contiene los valores v1, v2, … empaquetado de acuerdo con la cadena de formato format. Los argumentos deben coincidir exactamente con los valores requeridos por el formato.

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

  Pack the values v1, v2, … according to the format string format and write the packed bytes into the writable buffer buffer starting at position offset. Note that offset is a required argument. A negative offset counts from the end of buffer.

struct.unpack(format, buffer)

  Desempaqueta del búfer buffer (normalmente empaquetado por `pack(format, ...)`) según la cadena de formato format. El resultado es una tupla incluso si contiene un solo elemento. El tamaño del búfer en bytes debe coincidir con el tamaño requerido por el formato, como se refleja en `calcsize()`.

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

  Unpack from buffer starting at position offset, according to the format string format. The result is a tuple even if it contains exactly one item. The buffer’s size in bytes, starting at position offset, must be at least the size required by the format, as reflected by `calcsize()`. A negative offset counts from the end of buffer.

struct.iter_unpack(format, buffer)

  Desempaqueta de manera iterativa desde el búfer buffer según la cadena de formato format. Esta función retorna un iterador que leerá fragmentos de igual tamaño desde el búfer hasta que se haya consumido todo su contenido. El tamaño del búfer en bytes debe ser un múltiplo del tamaño requerido por el formato, como se refleja en `calcsize()`.

  Cada iteración produce una tupla según lo especificado por la cadena de formato.

  Added in version 3.4.

struct.calcsize(format)

  Retorna el tamaño de la estructura (y, por lo tanto, del objeto bytes generado por `pack(format, ...)`) correspondiente a la cadena de formato format.

## Cadenas de formato

Format strings describe the data layout when packing and unpacking data. They are built up from type codes, 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.

### Orden de bytes, tamaño y alineación

Por defecto, los tipos C se representan en el formato nativo y el orden de bytes de la máquina, y se alinean correctamente omitiendo bytes de relleno si es necesario (según las reglas utilizadas por el compilador de C). Se elige este comportamiento para que los bytes de una estructura empaquetada correspondan correctamente al diseño de memoria de la estructura C correspondiente. El uso de ordenamiento y relleno de bytes nativos o formatos estándar depende de la aplicación.

Como alternativa, el primer carácter de la cadena de formato se puede utilizar para indicar el orden de bytes, el tamaño y la alineación de los datos empaquetados, según la tabla siguiente:

Carácter | Orden de bytes | Tamaño | Alineamiento
--- | --- | --- | ---
`@` | nativo | nativo | nativo
`=` | nativo | standard | none
`<` | little-endian | standard | none
`>` | big-endian | standard | none
`!` | red (= big-endian) | standard | none

Si el primer carácter no es uno de estos, se asume `'@'`.

Nota

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'

El orden de bytes nativo es big-endian o little-endian, dependiendo del sistema host. Por ejemplo, Intel x86, AMD64 (x86-64) y Apple M1 son little-endian; IBM z y muchas arquitecturas heredadas son big-endian; ARM e Intel Itanium tienen la propiedad de trabajar con ambos formatos (middle-endian). Utiliza `sys.byteorder` para comprobar la endianness («extremidad») de tu sistema.

El tamaño y la alineación nativos se determinan mediante la expresión `sizeof` del compilador de C. Esto siempre se combina con el orden de bytes nativo.

Standard size depends only on the type code; see the table in the Type Codes section.

Nótese la diferencia entre `'@'` y `'='` : ambos utilizan el orden de bytes nativo, pero el tamaño y la alineación de este último está estandarizado.

La forma `'!'` representa el orden de bytes en la red, el cuál siempre es big-endian tal como se define en IETF RFC 1700.

No hay manera de indicar el orden de bytes no nativo (forzar el intercambio de bytes); utiliza la elección adecuada de `'<'` o `'>'`.

Notas:

1. El relleno solo se agrega automáticamente entre los miembros sucesivos de la estructura. No se agrega ningún relleno al principio o al final de la estructura codificada.

2. No se añade ningún relleno cuando se utiliza el tamaño y la alineación no nativos, por ejemplo, con “<”, “>”, “=” y “!”.

3. Para alinear el final de una estructura con el requisito de alineación de un tipo determinado, termina el formato con el código de ese tipo con un conteo repetido de ceros. Véase Ejemplos.

### Type Codes

Type codes (or format codes) have the following meaning; the conversion between C and Python values should be obvious given their types. The “Standard size” column refers to the size of the packed value in bytes when using standard size; that is, when the format string starts with one of `'<'`, `'>'`, `'!'` or `'='`. When using native size, the size of the packed value is platform-dependent.

Formato | Tipo C | Tipo Python | Tamaño estándar | Notas
--- | --- | --- | --- | ---
`x` | byte de relleno | sin valor |  | (7)
`c` | char | bytes de longitud 1 | 1 |
`b` | signed char | int | 1 | (2)
`B` | unsigned char | int | 1 | (2)
(2) | _Bool | bool | 1 | (1)
`h` | short | int | 2 | (2)
`H` | unsigned short | int | 2 | (2)
`i` | int | int | 4 | (2)
`I` | unsigned int | int | 4 | (2)
`l` | long | int | 4 | (2)
`L` | unsigned long | int | 4 | (2)
`q` | long long | int | 8 | (2)
`Q` | unsigned long long | int | 8 | (2)
`n` | `ssize_t` | int |  | (2), (3)
`N` | `size_t` | int |  | (2), (3)
`e` | _Float16 | float | 2 | (4), (6)
`f` | float | float | 4 | (4)
`d` | double | float | 8 | (4)
`Zf` | float complex | complex | 8 | (10)
`Zd` | double complex | complex | 16 | (10)
`s` | char[] | bytes |  | (9)
`p` | char[] | bytes |  | (8)
`P` | void* | int |  | (2), (5)

Distinto en la versión 3.3: Soporte añadido para los formatos `'n'` y `'N'`.

Distinto en la versión 3.6: Soporte añadido para el formato `'e'`.

Distinto en la versión 3.14: Added support for the `'F'` and `'D'` formats.

Distinto en la versión 3.15: Added support for the `'Zf'` and `'Zd'` formats.

Distinto en la versión 3.16: `'F'` and `'D'` formats are deprecated.

Ver también

The `array` and ctypes modules, as well as third-party modules like numpy, use similar – but slightly different – type codes.

Notas:

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. Al intentar empaquetar un no entero mediante cualquiera de los códigos de conversión de enteros, si el no entero tiene un método `__index__()`, se llama a ese método para convertir el argumento en un entero antes de empaquetar.

   Distinto en la versión 3.2: Agregado el uso del método `__index__()` para los no enteros.

3. Los códigos de conversión `'n'` y `'N'` solo están disponibles para el tamaño nativo (seleccionado como predeterminado o con el carácter de orden de bytes `'@'`). Para el tamaño estándar, puedes usar cualquiera de los otros formatos enteros que se ajusten a tu aplicación.

4. Para los códigos de conversión `'f'`, `'d'` y `'e'`, la representación empaquetada utiliza el formato IEEE 754 binary32, binary64 o binary16 (para `'f'`, `'d'` o `'e'` respectivamente), independientemente del formato de punto flotante utilizado por la plataforma.

5. The `'P'` type code is only available for the native byte ordering (selected as the default or with the `'@'` byte order character). The byte order character `'='` chooses to use little- or big-endian ordering based on the host system. The struct module does not interpret this as native ordering, so the `'P'` format is not available.

6. The IEEE 754 binary16 «half precision» type was introduced in the 2008 revision of the IEEE 754 standard. It has a sign bit, a 5-bit exponent and 11-bit precision (with 10 bits explicitly stored), and can represent numbers between approximately `6.1e-05` and `6.5e+04` at full precision. This type is not widely supported by C compilers: it’s available as _Float16 type, if the compiler supports the Annex H of the C23 standard. On a typical machine, an unsigned short can be used for storage, but not for math operations. See the Wikipedia page on the half-precision floating-point format for more information.

7. Al empaquetar, `'x'` inserta un byte NUL.

8. The `'p'` type code encodes a «Pascal string», meaning a short variable-length string stored in a fixed number of bytes, given by the count. The first byte stored is the length of the string, or 255, whichever is smaller. The bytes of the string follow. If the byte string passed in to `pack()` is too long (longer than the count minus 1), only the leading `count-1` bytes of the string are stored. If the byte string is shorter than `count-1`, it is padded with null bytes so that exactly count bytes in all are used. Note that for `unpack()`, the `'p'` type code consumes `count` bytes, but that the `bytes` object returned can never contain more than 255 bytes. When packing, arguments of types `bytes` and `bytearray` are accepted.

9. For the `'s'` type code, the count is interpreted as the length of the byte string, not a repeat count like for the other type codes; 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 Ejemplos for a concrete demonstration of the difference.) If a count is not given, it defaults to 1. For packing, the byte 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 byte string (while `'0c'` means 0 characters). When packing, arguments of types `bytes` and `bytearray` are accepted.

10. For the `'Zf'` and `'Zd'` type codes, 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. Note that complex types are available unconditionally, despite complex types being an optional feature in C. As specified in the C11 standard, each complex type is represented by a two-element C array containing, respectively, the real and imaginary parts. The `'F'` and `'D'` (for `'Zf'` and `'Zd'`, respectively) format characters are supported for compatibility.

A type code may be preceded by an integral repeat count. For example, the format string `'4h'` means exactly the same as `'hhhh'`.

Se omiten los caracteres de espacio entre formatos; sin embargo, un recuento y su formato no deben contener espacios en blanco.

Al empaquetar un valor `x` utilizando uno de los formatos enteros (`'b'`, `'B'`, `'h'`, `'H'`, `'i'`, `'I'`, `'l'`, `'L'`, `'q'`, `'Q'`), si `x` está fuera de un rango válido para ese formato, entonces se lanza la excepción `struct.error`.

Distinto en la versión 3.1: Anteriormente, algunos de los formatos enteros ajustaban los valores fuera de rango y lanzaban `DeprecationWarning` en vez de `struct.error`.

For the `'?'` type code, the return value is either `True` or `False`. When packing, the truth value of the argument object is used. Either 0 or 1 in the native or standard bool representation will be packed, and any non-zero value will be `True` when unpacking.

### Ejemplos

Nota

Los ejemplos de orden de bytes nativos (designados por el prefijo de formato `'@'` o la falta de cualquier carácter de prefijo) pueden no coincidir con lo que produce la máquina del lector, ya que eso depende de la plataforma y el compilador.

Empaqueta y desempaqueta enteros de tres tamaños diferentes, utilizando el orden big endian:

    >>> 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

Intenta empaquetar un entero que es demasiado grande para el campo definido:

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

Demuestra la diferencia entre los caracteres de formato `'s'` y `'c'`:

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

Los campos desempaquetados se pueden nombrar asignándolos a variables o ajustando el resultado en una tupla con nombre:

    >>> 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 type codes 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

El siguiente formato `'llh0l'` especifica dos bytes de relleno al final, suponiendo que los tipos longs están alineados en los límites de 4 bytes:

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

Ver también

Módulo `array`

  Almacenamiento binario empaquetado de datos homogéneos.

Módulo `json`

  Codificador y decodificador JSON.

Módulo `pickle`

  Serialización de objetos Python.

## Aplicaciones

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.

### Formatos nativos

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 type 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.

Considera estos dos ejemplos sencillos (en una máquina little-endian de 64 bits):

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

Los datos no se rellenan hasta un límite de 8 bytes al final de la segunda cadena de formato sin el uso de relleno adicional. Un código de formato de repetición cero resuelve ese problema:

    >>> calcsize('@llh0l')
    24

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

De forma predeterminada, se utiliza el orden y la alineación de bytes nativos, pero es mejor ser explícito y utilizar el carácter de prefijo `'@'`.

### Formatos estándar

Cuando intercambia datos más allá de su proceso, como redes o almacenamiento, sé preciso. Especifica el orden de bytes, el tamaño y la alineación exactos. No asumas que coinciden con el orden nativo de una máquina en particular. Por ejemplo, el orden de los bytes de la red es big-endian, mientras que muchas CPU populares son little-endian. Al definir esto explícitamente, el usuario no necesita preocuparse por las especificaciones de la plataforma en la que se ejecuta su código. El primer carácter normalmente debería ser `<` o `>` (o `!`). El relleno es responsabilidad del programador. El carácter de formato de repetición cero no funcionará. En su lugar, el usuario debe agregar explícitamente `'x'` bytes de relleno donde sea necesario. Revisando los ejemplos de la sección anterior, tenemos:

    >>> 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

No se garantiza que los resultados anteriores (ejecutados en una máquina de 64 bits) coincidan cuando se ejecutan en diferentes máquinas. Por ejemplo, los siguientes ejemplos se ejecutaron en una máquina de 32 bits:

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

## Clases

The `struct` module also defines the following type:

class struct.Struct(format)

  Retorna un nuevo objeto Struct que escribe y lee datos binarios según la cadena de formato format. Crear un objeto `Struct` una vez y llamar a sus métodos es más eficaz que llamar a las funciones a nivel de módulo con el mismo formato, ya que la cadena de formato solo se compila una vez.

  Nota

  Las versiones compiladas de las cadenas de formato más recientes pasadas a las funciones de nivel de módulo se almacenan en caché, por lo que los programas que utilizan solo unas pocas cadenas de formato no necesitan preocuparse por volver a usar una sola instancia `Struct`.

  Los objetos Struct compilados admiten los siguientes métodos y atributos:

  pack(v1, v2, ...)

    Idéntico a la función `pack()`, utilizando el formato compilado. (`len(result)` será igual a `size`.)

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

    Idéntico a la función `pack_into()`, utilizando el formato compilado.

  unpack(buffer)

    Idéntico a la función `unpack()`, utilizando el formato compilado. El tamaño del búfer en bytes debe ser igual a `size`.

  unpack_from(buffer, offset=0)

    Idéntico a la función `unpack_from()`, utilizando el formato compilado. El tamaño del búfer en bytes, comenzando en la posición offset, debe ser al menos `size`.

  iter_unpack(buffer)

    Idéntico a la función `iter_unpack()`, utilizando el formato compilado. El tamaño del búfer en bytes debe ser un múltiplo de `size`.

    Added in version 3.4.

  format

    Cadena de formato utilizada para construir este objeto Struct.

    Distinto en la versión 3.7: El tipo de cadena de formato es ahora `str` en lugar de `bytes`.

  size

    El tamaño calculado de la estructura (y, por lo tanto, del objeto bytes generado por el método `pack()`) correspondiente a `format`.

  Distinto en la versión 3.13: The repr() of structs has changed. It is now:

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