# `binascii` — Convert between binary and ASCII

The `binascii` module contains a number of methods to convert between binary and various ASCII-encoded binary representations. Normally, you will not use these functions directly but use wrapper modules like `base64` instead. The `binascii` module contains low-level functions written in C for greater speed that are used by the higher-level modules.

Nota

Las funciones `a2b_*` aceptan cadenas Unicode que contienen solo caracteres ASCII. Otras funciones solo aceptan objetos tipo binarios (como `bytes`, `bytearray` y otros objetos que admiten el protocolo de búfer).

Distinto en la versión 3.3: Las cadenas unicode con sólo caracteres ASCII son ahora aceptadas por las funciones `a2b_*`.

The `binascii` module defines the following functions:

binascii.a2b_uu(string)

  Convierte una sola línea de datos uuencoded de nuevo a binarios y retorna los datos binarios. Las líneas normalmente contienen 45 bytes (binarios), excepto por la última línea. Los datos de línea pueden ir seguidos de espacios en blanco.

binascii.b2a_uu(data, *, backtick=False)

  Convierte datos binarios a una línea de caracteres ASCII, el valor retornado es la línea convertida, incluido un carácter de nueva línea. La longitud de data debe ser como máximo 45. Si backtick es verdadero, los ceros se representan mediante `'`'` en lugar de espacios.

  Distinto en la versión 3.7: Se ha añadido el parámetro backtick.

binascii.a2b_base64(string, /, *, padded=True, alphabet=BASE64_ALPHABET, strict_mode=False, canonical=False)
binascii.a2b_base64(string, /, *, ignorechars, padded=True, alphabet=BASE64_ALPHABET, strict_mode=True, canonical=False)

  Convierte un bloque de datos en base64 de nuevo a binario y retorna los datos binarios. Se puede pasar más de una línea a la vez.

  Optional alphabet must be a `bytes` object of length 64 which specifies an alternative alphabet.

  If padded is true, the last group of 4 base 64 alphabet characters must be padded with the “=” character. If padded is false, padding is neither required nor recognized: the “=” character is not treated as padding but as a non-alphabet character, which means it is silently discarded when strict_mode is false, or causes an `Error` when strict_mode is true unless b”=” is included in ignorechars.

  If ignorechars is specified, it should be a bytes-like object containing characters to ignore from the input when strict_mode is true. If ignorechars contains the pad character `'='`, the pad characters presented before the end of the encoded data and the excess pad characters will be ignored. The default value of strict_mode is `True` if ignorechars is specified, `False` otherwise.

  Si strict_mode es verdadero, solo se convertirán los datos en base64 válidos. Los datos en base64 no válidos lanzarán `binascii.Error`.

  base64 válido:

  - Conforms to RFC 4648.

  - Contiene solo caracteres del alfabeto base64.

  - No contiene exceso de datos después del relleno (incluye el exceso de relleno, nuevas líneas, etc.).

  - No empieza con un relleno.

  If canonical is true, non-zero padding bits in the last group are rejected with `binascii.Error`, enforcing canonical encoding as defined in RFC 4648 section 3.5. This check is independent of strict_mode.

  Distinto en la versión 3.11: Se ha añadido el parámetro strick_mode.

  Distinto en la versión 3.15: Added the alphabet, canonical, ignorechars, and padded parameters.

binascii.b2a_base64(data, *, padded=True, alphabet=BASE64_ALPHABET, wrapcol=0, newline=True)

  Convert binary data to a line(s) of ASCII characters in base64 coding, as specified in RFC 4648.

  If padded is true (default), pad the encoded data with the “=” character to a size multiple of 4. If padded is false, do not add the pad characters.

  If wrapcol is non-zero, insert a newline (`b'\n'`) character after at most every wrapcol characters. If wrapcol is zero (default), do not insert any newlines.

  If newline is true (default), a newline character will be added at the end of the output.

  Distinto en la versión 3.6: Se ha añadido el parámetro newline.

  Distinto en la versión 3.15: Added the alphabet, padded and wrapcol parameters.

binascii.a2b_ascii85(string, /, *, foldspaces=False, adobe=False, ignorechars=b'', canonical=False)

  Convert Ascii85 data back to binary and return the binary data.

  Valid Ascii85 data contains characters from the Ascii85 alphabet in groups of five (except for the final group, which may have from two to five characters). Each group encodes 32 bits of binary data in the range from `0` to `2 ** 32 - 1`, inclusive. The special character `z` is accepted as a short form of the group `!!!!!`, which encodes four consecutive null bytes. A single-character final group is always rejected as an encoding violation.

  foldspaces is a flag that specifies whether the “y” short sequence should be accepted as shorthand for 4 consecutive spaces (ASCII 0x20). This feature is not supported by the «standard» Ascii85 encoding.

  adobe controls whether the encoded byte sequence is framed with `<~` and `~>`, as in a PostScript base-85 string literal. If adobe is true, a leading `<~` is optionally accepted, while a trailing `~>` is required, and `binascii.Error` is raised if it is not found.

  ignorechars should be a bytes-like object containing characters to ignore from the input. This should only contain whitespace characters.

  If canonical is true, non-canonical encodings are rejected with `binascii.Error`. Here «canonical» means the encoding that `b2a_ascii85()` would produce: the `z` abbreviation must be used for all-zero groups (rather than `!!!!!`), and partial final groups must use the same padding digits as the encoder.

  Invalid Ascii85 data will raise `binascii.Error`.

  Added in version 3.15.

binascii.b2a_ascii85(data, /, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)

  Convert binary data to a formatted sequence of ASCII characters in Ascii85 coding. The return value is the converted data.

  foldspaces is an optional flag that uses the special short sequence “y” instead of 4 consecutive spaces (ASCII 0x20) as supported by “btoa”. This feature is not supported by the «standard» Ascii85 encoding.

  If wrapcol is non-zero, insert a newline (`b'\n'`) character after at most every wrapcol characters. If wrapcol is zero (default), do not insert any newlines.

  If pad is true, the zero-padding applied to the end of the input is fully retained in the output encoding, as done by `btoa`, producing an exact multiple of 5 bytes of output. This is not part of the standard encoding used in PDF, as it does not preserve the length of the data.

  adobe controls whether the encoded byte sequence is framed with `<~` and `~>`, as in a PostScript base-85 string literal. Note that while ASCII85Decode streams in PDF documents must be terminated with `~>`, they must not use a leading `<~`.

  Added in version 3.15.

binascii.a2b_base85(string, /, *, alphabet=BASE85_ALPHABET, ignorechars=b'', canonical=False)

  Convert Base85 data back to binary and return the binary data. More than one line may be passed at a time.

  Valid Base85 data contains characters from the Base85 alphabet in groups of five (except for the final group, which may have from two to five characters). Each group encodes 32 bits of binary data in the range from `0` to `2 ** 32 - 1`, inclusive. A single-character final group is always rejected as an encoding violation.

  Optional alphabet must be a `bytes` object of length 85 which specifies an alternative alphabet.

  ignorechars should be a bytes-like object containing characters to ignore from the input.

  If canonical is true, non-canonical encodings are rejected with `binascii.Error`. Here «canonical» means the encoding that `b2a_base85()` would produce: partial final groups must use the same padding digits as the encoder.

  Invalid Base85 data will raise `binascii.Error`.

  Added in version 3.15.

binascii.b2a_base85(data, /, *, alphabet=BASE85_ALPHABET, wrapcol=0, pad=False)

  Convert binary data to a line of ASCII characters in Base85 coding. The return value is the converted line.

  Optional alphabet must be a bytes-like object of length 85 which specifies an alternative alphabet.

  If wrapcol is non-zero, insert a newline (`b'\n'`) character after at most every wrapcol characters. If wrapcol is zero (default), do not insert any newlines.

  If pad is true, the zero-padding applied to the end of the input is retained in the output, which will always be a multiple of 5 bytes, and thus the length of the data may not be preserved on decoding.

  Added in version 3.15.

binascii.a2b_base32(string, /, *, padded=True, alphabet=BASE32_ALPHABET, ignorechars=b'', canonical=False)

  Convert base32 data back to binary and return the binary data.

  Valid base32 data contains characters from the base32 alphabet specified in RFC 4648 in groups of eight (if necessary, the final group is padded to eight characters with `=`). Each group encodes 40 bits of binary data in the range from `0` to `2 ** 40 - 1`, inclusive.

  Nota

  This function does not map lowercase characters (which are invalid in standard base32) to their uppercase counterparts, nor does it contextually map `0` to `O` and `1` to `I`/`L` as RFC 4648 allows.

  Optional alphabet must be a `bytes` object of length 32 which specifies an alternative alphabet.

  If padded is true, the last group of 8 base 32 alphabet characters must be padded with the “=” character. If padded is false, the “=” character is treated as other non-alphabet characters (depending on the value of ignorechars).

  ignorechars should be a bytes-like object containing characters to ignore from the input. If ignorechars contains the pad character `'='`, the pad characters presented before the end of the encoded data and the excess pad characters will be ignored.

  If canonical is true, non-zero padding bits in the last group are rejected with `binascii.Error`, enforcing canonical encoding as defined in RFC 4648 section 3.5.

  Invalid base32 data will raise `binascii.Error`.

  Added in version 3.15.

binascii.b2a_base32(data, /, *, padded=True, alphabet=BASE32_ALPHABET, wrapcol=0)

  Convert binary data to a line of ASCII characters in base32 coding, as specified in RFC 4648. The return value is the converted line.

  Optional alphabet must be a bytes-like object of length 32 which specifies an alternative alphabet.

  If padded is true (default), pad the encoded data with the “=” character to a size multiple of 8. If padded is false, do not add the pad characters.

  If wrapcol is non-zero, insert a newline (`b'\n'`) character after at most every wrapcol characters. If wrapcol is zero (default), do not insert any newlines.

  Added in version 3.15.

binascii.a2b_qp(data, header=False)

  Convierte un bloque de datos imprimibles entre comillas a binario y retorna los datos binarios. Se puede pasar más de una línea a la vez. Si el argumento opcional header está presente y es verdadero, los guiones bajos se decodificarán como espacios.

binascii.b2a_qp(data, quotetabs=False, istext=True, header=False)

  Convierte datos binarios en una(s) línea(s) de caracteres ASCII en codificación imprimible entre comillas. El valor de retorno son las líneas convertidas. Si el argumento opcional quotetabs está presente y es verdadero, se codificarán todas los tabs y espacios. Si el argumento opcional istext está presente y es verdadero, las nuevas líneas no se codifican, pero se codificarán los espacios en blanco finales. Si el argumento opcional header está presente y es verdadero, los espacios se codificarán como guiones bajos por: rfc: 1522. Si el argumento opcional header está presente y es falso, los caracteres de nueva línea también se codificarán; de lo contrario, la conversión de salto de línea podría dañar el flujo de datos binarios.

binascii.crc_hqx(data, value)

  Calcula un valor CRC de 16 bits de data, comenzando con value como el CRC inicial, y retorna el resultado. Utiliza el polinomio CRC-CCITT x16 + x12 + x5 + 1, a menudo representado como 0x1021. Este CRC se utiliza en el formato binhex4.

binascii.crc32(data[, value])

  Calcula CRC-32, la suma de comprobación de 32 bits de data que no tiene signo, comenzando con un CRC inicial de value. El CRC inicial predeterminado es cero. El algoritmo es consistente con la suma de verificación del archivo ZIP. Dado que el algoritmo está diseñado para usarse como un algoritmo de suma de verificación, no es adecuado para usarlo como algoritmo hash general. Úselo de la siguiente manera:

      print(binascii.crc32(b"hello world"))
      # Or, in two pieces:
      crc = binascii.crc32(b"hello")
      crc = binascii.crc32(b" world", crc)
      print('crc32 = {:#010x}'.format(crc))

  Distinto en la versión 3.0: El resultado siempre es sin signo.

binascii.b2a_hex(data[, sep[, bytes_per_sep=1]])
binascii.hexlify(data[, sep[, bytes_per_sep=1]])

  Retorna la representación hexadecimal del binario data. Cada byte de data se convierte en la representación hexadecimal de 2 dígitos correspondiente. Por lo tanto, el objeto de bytes retornado es el doble de largo que la longitud de data.

  Una funcionalidad similar (pero que retorna una cadena de texto) también es convenientemente accesible usando el método `bytes.hex()`.

  Si se especifica sep, debe ser un solo carácter str o un objeto de bytes. Se insertará en la salida después de cada bytes_per_sep bytes de entrada . La ubicación del separador se cuenta desde el extremo derecho de la salida de forma predeterminada; si desea contar desde el izquierdo, proporcione un valor negativo bytes_per_sep.

      >>> import binascii
      >>> binascii.b2a_hex(b'\xb9\x01\xef')
      b'b901ef'
      >>> binascii.hexlify(b'\xb9\x01\xef', '-')
      b'b9-01-ef'
      >>> binascii.b2a_hex(b'\xb9\x01\xef', b'_', 2)
      b'b9_01ef'
      >>> binascii.b2a_hex(b'\xb9\x01\xef', b' ', -2)
      b'b901 ef'

  Distinto en la versión 3.8: Se agregaron los parámetros sep y bytes_per_sep.

binascii.a2b_hex(hexstr, *, ignorechars=b'')
binascii.unhexlify(hexstr, *, ignorechars=b'')

  Retorna los datos binarios representados por la cadena hexadecimal hexstr. Esta función es la inversa de `b2a_hex()`. hexstr debe contener un número par de dígitos hexadecimales (que pueden ser mayúsculas o minúsculas), de lo contrario se produce una excepción `Error`.

  ignorechars should be a bytes-like object containing characters to ignore from the input.

  Funcionalidad similar (aceptar sólo argumentos de cadena de texto, pero más liberal hacia espacios en blanco) también es accesible mediante el método de clase `bytes.fromhex()`.

  Distinto en la versión 3.15: Added the ignorechars parameter.

exception binascii.Error

  Excepción provocada por errores. Estos suelen ser errores de programación.

exception binascii.Incomplete

  Excepción provocada por datos incompletos. Por lo general, estos no son errores de programación, pero se pueden controlar leyendo un poco más de datos e intentándolo de nuevo.

binascii.BASE64_ALPHABET

  The Base 64 alphabet according to RFC 4648.

  Added in version 3.15.

binascii.URLSAFE_BASE64_ALPHABET

  The «URL and filename safe» Base 64 alphabet according to RFC 4648.

  Added in version 3.15.

binascii.UU_ALPHABET

  The uuencoding alphabet.

  Added in version 3.15.

binascii.CRYPT_ALPHABET

  The Base 64 alphabet used in the crypt(3) routine and in the GEDCOM format.

  Added in version 3.15.

binascii.BINHEX_ALPHABET

  The Base 64 alphabet used in BinHex 4 (HQX) within the classic Mac OS.

  Added in version 3.15.

binascii.BASE85_ALPHABET

  The Base85 alphabet.

  Added in version 3.15.

binascii.ASCII85_ALPHABET

  The Ascii85 alphabet.

  Added in version 3.15.

binascii.Z85_ALPHABET

  The Z85 alphabet.

  Added in version 3.15.

binascii.BASE32_ALPHABET

  The Base 32 alphabet according to RFC 4648.

  Added in version 3.15.

binascii.BASE32HEX_ALPHABET

  The «Extended Hex» Base 32 alphabet according to RFC 4648. Data encoded with this alphabet maintains its sort order during bitwise comparisons.

  Added in version 3.15.

Ver también

Módulo `base64`

  Soporte para compatibilidad con RFC de codificación de estilo base64 en base 16, 32, 64 y 85.

Módulo `quopri`

  Soporte para codificación imprimible entre comillas utilizada en mensajes de correo electrónico MIME.