"binascii" --- Convertir entre binario y ASCII
**********************************************

======================================================================

El módulo "binascii" contiene una serie de métodos para convertir
entre representaciones binarias y varias representaciones binarias
codificadas en ASCII. Normalmente, usted no usará estas funciones
directamente, en su lugar utilice módulos envoltorios (*wrapper*) como
"uu", "base64", o "binhex" en su lugar. El módulo "binascii" contiene
funciones de bajo nivel escritas en C para una mayor velocidad que son
utilizadas por los módulos de nivel superior.

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_*".

El módulo "binascii" define las siguientes funciones:

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)

   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.

binascii.b2a_base64(data, *, newline=True)

   Convierte datos binarios en una línea de caracteres ASCII en
   codificación base64. El valor retornado es la línea convertida,
   incluido un carácter de nueva línea si *newline* es verdadero.  La
   salida de esta función se ajusta a **RFC 3548**.

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

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.a2b_hqx(string)

   Convierte datos ASCII con formato binhex4 a binario, sin
   descomprimir RLE. La cadena debe contener un número completo de
   bytes binarios o (en el caso de la última porción de los datos
   binhex4) tener los bits restantes cero.

   Obsoleto desde la versión 3.9.

binascii.rledecode_hqx(data)

   Realiza descompresión RLE en los datos, según el estándar binhex4.
   El algoritmo usa "0x90" después de un byte como indicador de
   repetición, seguido de un conteo. Un recuento de "0" especifica un
   valor de byte de "0x90". La rutina retorna los datos
   descomprimidos, a menos que los datos de entrada de datos terminen
   en un indicador de repetición huérfano, en cuyo caso se genera la
   excepción "Incomplete".

   Distinto en la versión 3.2: Acepta solo objetos bytestring o
   bytearray  como entrada.

   Obsoleto desde la versión 3.9.

binascii.rlecode_hqx(data)

   Realiza la compresión RLE de estilo binhex4 en *data* y retorna el
   resultado.

   Obsoleto desde la versión 3.9.

binascii.b2a_hqx(data)

   Realiza la traducción de binario hexbin4  a ASCII y retorna la
   cadena resultante. El argumento ya debe estar codificado en RLE y
   tener una longitud divisible por 3 (excepto posiblemente por el
   último fragmento).

   Obsoleto desde la versión 3.9.

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 *x*^16 + *x*^12 + *x*^5 + 1, a menudo representado como
   0x1021. Este CRC se utiliza en el formato binhex4.

binascii.crc32(data[, value])

   Compute CRC-32, the unsigned 32-bit checksum of *data*, starting
   with an initial CRC of *value*.  The default initial CRC is zero.
   The algorithm is consistent with the ZIP file checksum.  Since the
   algorithm is designed for use as a checksum algorithm, it is not
   suitable for use as a general hash algorithm.  Use as follows:

      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: The result is always unsigned. To
   generate the same numeric value when using Python 2 or earlier, use
   "crc32(data) & 0xffffffff".

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)
binascii.unhexlify(hexstr)

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

   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()".

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.

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 "binhex"
     Soporte para el formato *binhex* utilizado en Macintosh.

  Módulo "uu"
     Soporte para codificación *UU* usada en Unix.

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