"zlib" --- Compresión compatible con **gzip**
*********************************************

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

Para las aplicaciones que requieren compresión de datos, las funciones
de este módulo permiten la compresión y la descompresión, utilizando
la biblioteca zlib. La biblioteca zlib tiene su propia página de
inicio en http://www.zlib.net. Existen incompatibilidades conocidas
entre el módulo Python y las versiones de la biblioteca zlib
anteriores a 1.1.3; 1.1.3 tiene una vulnerabilidad de seguridad, por
lo que recomendamos usar 1.1.4 o posterior.

Las funciones de zlib tienen muchas opciones y a menudo necesitan ser
utilizadas en un orden particular. Esta documentación no intenta
cubrir todas las permutaciones; consultar el manual de zlib en
http://www.zlib.net/manual.html para obtener información autorizada.

Para leer y escribir archivos ".gz" consultar el módulo "gzip".

La excepción y las funciones disponibles en este módulo son:

exception zlib.error

   Excepción provocada en errores de compresión y descompresión.

zlib.adler32(data[, value])

   Calcula una suma de comprobación Adler-32 de *data*. (Una suma de
   comprobación Adler-32 es casi tan confiable como un CRC32, pero se
   puede calcular mucho más rápidamente). El resultado es un entero de
   32 bits sin signo. Si *value* está presente, se utiliza como el
   valor inicial de la suma de comprobación; de lo contrario, se
   utiliza un valor predeterminado de 1. Pasar *value* permite
   calcular una suma de comprobación en ejecución durante la
   concatenación de varias entradas. El algoritmo no es
   criptográficamente fuerte y no se debe utilizar para la
   autenticación o las firmas digitales. Puesto que está diseñado como
   un algoritmo de suma de comprobación, no es adecuado su uso como un
   algoritmo *hash* general.

   Distinto en la versión 3.0: Siempre retorna un valor sin signo.
   Para generar el mismo valor numérico en todas las versiones y
   plataformas de Python, utilice "adler32(data) & 0xffffffff".

zlib.compress(data, level=-1)

   Comprime los bytes de *data*, retornando un objeto bytes que
   contiene datos comprimidos. *level* es un entero de "0" a "9" o
   "-1" que controla el nivel de compresión; "1" (Z_BEST_SPEED) es más
   rápido y produce la menor compresión, "9" (Z_BEST_COMPRESSION) es
   más lento y produce mayor compresión. "0" (Z_NO_COMPRESSION) no es
   compresión. El valor predeterminado es "-1"
   (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION representa un
   compromiso predeterminado entre velocidad y compresión (actualmente
   equivalente al nivel 6). Genera la excepción "error" si se produce
   algún error.

   Distinto en la versión 3.6: *level* ahora se puede utilizar como
   parámetro de palabra clave.

zlib.compressobj(level=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

   Retorna un objeto de compresión, para ser usado para comprimir
   flujos de datos que no caben en la memoria de una vez.

   *level* es el nivel de compresión -- es un entero de `` 0`` a ``
   9`` o `` -1``. Un valor de `` 1`` (Z_BEST_SPEED) es el más rápido y
   produce la menor compresión, mientras que un valor de `` 9``
   (Z_BEST_COMPRESSION) es el más lento y produce la mayor cantidad.
   "0" (Z_NO_COMPRESSION) no es compresión. El valor predeterminado es
   "-1" (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION representa un
   compromiso predeterminado entre velocidad y compresión (actualmente
   equivalente al nivel 6).

   *method* es el algoritmo de compresión. Actualmente, el único valor
   admitido es "DEFLATED".

   El argumento *wbits* controla el tamaño del búfer histórico (o el
   "tamaño de ventana") utilizado al comprimir datos, y si se incluye
   un encabezado y un avance en la salida. Puede tomar varios rangos
   de valores, por defecto es "15" (MAX_WBITS):

   * +9 a +15: el logaritmo en base dos del tamaño de la ventana, que
     por lo tanto oscila entre 512 y 32768. Los valores más grandes
     producen una mejor compresión a expensas de un mayor uso de
     memoria. Como resultado se incluirá un encabezado y un avance
     específicos de zlib.

   * −9 a −15: utiliza el valor absoluto de *wbits* como el logaritmo
     del tamaño de la ventana, al tiempo que produce una secuencia de
     salida sin encabezado ni suma de verificación.

   * +25 a +31 = 16 + (9 a 15): utiliza los 4 bits bajos del valor
     como el logaritmo del tamaño de la ventana, mientras que incluye
     un encabezado básico **gzip** y suma de verificación en la
     salida.

   El argumento *memLevel* controla la cantidad de memoria utilizada
   para el estado de compresión interna. Los valores posibles varían
   de "1" a "9". Los valores más altos usan más memoria, pero son más
   rápidos y producen una salida más pequeña.

   *strategy* se usa para ajustar el algoritmo de compresión. Los
   valores posibles son "Z_DEFAULT_STRATEGY", "Z_FILtered",
   "Z_HUFFMAN_ONLY", "Z_RLE" (zlib 1.2.0.1) y "Z_FIXED" (zlib
   1.2.2.2).

   *zdict* es un diccionario de compresión predefinido. Este es una
   secuencia de bytes (como un objeto "bytes") que contiene
   subsecuencias que se espera que ocurran con frecuencia en los datos
   que se van a comprimir. Las subsecuencias que se espera que sean
   más comunes deben aparecer al final del diccionario.

   Distinto en la versión 3.3: Se agregó el parámetro *zdict* y el
   soporte de argumentos de palabras clave.

zlib.crc32(data[, value])

   Calcula un suma de comprobación CRC (comprobación de redundancia
   cíclica, por sus siglas en inglés *Cyclic Redundancy Check*) de
   *datos*. El resultado es un entero de 32 bits sin signo. Si *value*
   está presente, se usa como el valor inicial de la suma de
   verificación; de lo contrario, se usa el valor predeterminado 0.
   Pasar *value* permite calcular una suma de verificación en
   ejecución sobre la concatenación de varias entradas. El algoritmo
   no es criptográficamente fuerte y no debe usarse para autenticación
   o firmas digitales. Dado que está diseñado para usarse como un
   algoritmo de suma de verificación, no es adecuado su uso como
   algoritmo *hash* general.

   Distinto en la versión 3.0: Siempre retorna un valor sin signo.
   Para generar el mismo valor numérico en todas las versiones y
   plataformas de Python, use "crc32 (data) & 0xffffffff".

zlib.decompress(data, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

   Descomprime los bytes en *data*, retornando un objeto de bytes que
   contiene los datos sin comprimir. El parámetro *wbits* depende del
   formato de *data*, y se trata más adelante. Si se da *bufsize*, se
   usa como el tamaño inicial del búfer de salida. Provoca la
   excepción "error" si se produce algún error.

   El parámetro *wbits* controla el tamaño del búfer histórico (o el
   "tamaño de ventana") y qué formato de encabezado y cola se espera.
   Es similar al parámetro para "compressobj()", pero acepta más
   rangos de valores:

   * +8 a +15: el logaritmo en base dos del tamaño del búfer. La
     entrada debe incluir encabezado y cola zlib.

   * 0: determina automáticamente el tamaño del búfer desde el
     encabezado zlib. Solo se admite desde zlib 1.2.3.5.

   * -8 to -15: utiliza el valor absoluto de *wbits* como el logaritmo
     del tamaño del búfer. La entrada debe ser una transmisión sin
     formato, sin encabezado ni cola.

   * +24 a +31 = 16 + (8 a 15): utiliza los 4 bits de bajo orden del
     valor como el logaritmo del tamaño del búfer. La entrada debe
     incluir encabezado y cola gzip.

   * +40 a +47 = 32 + (8 a 15): utiliza los 4 bits de bajo orden del
     valor como el logaritmo del tamaño del búfer y acepta
     automáticamente el formato zlib o gzip.

   Al descomprimir una secuencia, el tamaño del búfer no debe ser
   menor al tamaño utilizado originalmente para comprimir la
   secuencia; el uso de un valor demasiado pequeño puede generar una
   excepción "error". El valor predeterminado *wbits* corresponde al
   tamaño más grande de búfer y requiere que se incluya encabezado y
   cola zlib.

   *bufsize* es el tamaño inicial del búfer utilizado para contener
   datos descomprimidos. Si se requiere más espacio, el tamaño del
   búfer aumentará según sea necesario, por lo que no hay que tomar
   este valor como exactamente correcto; al ajustarlo solo se
   guardarán algunas llamadas en "malloc()".

   Distinto en la versión 3.6: *wbits* y *bufsize* se pueden usar como
   argumentos de palabra clave.

zlib.decompressobj(wbits=MAX_WBITS[, zdict])

   Retorna un objeto de descompresión, que se utilizará para
   descomprimir flujos de datos que no caben en la memoria de una vez.

   El parámetro *wbits* controla el tamaño del búfer histórico (o el
   "tamaño de ventana") y qué formato de encabezado y cola se espera.
   Tiene el mismo significado que described for decompress().

   El parámetro *zdict* especifica un diccionario de compresión
   predefinido. Si se proporciona, este debe ser el mismo diccionario
   utilizado por el compresor que produjo los datos que se van a
   descomprimir.

   Nota:

     Si *zdict* es un objeto mutable (como "bytearray"), no se debe
     modificar su contenido entre la llamada "decompressobj()" y la
     primera llamada al método descompresor "decompress()".

   Distinto en la versión 3.3: Se agregó el parámetro *zdict*.

Los objetos de compresión admiten los siguientes métodos:

Compress.compress(data)

   Comprime *data*, y retorna al menos algunos de los datos
   comprimidos como un objeto de bytes. Estos datos deben concatenarse
   a la salida producida por cualquier llamada anterior al método
   "compress()". Algunas entradas pueden mantenerse en un búfer
   interno para su posterior procesamiento.

Compress.flush([mode])

   Se procesan todas las entradas pendientes y se retorna un objeto de
   bytes que contiene la salida comprimida restante. El argumento
   *mode* acepta una de las siguientes constantes "Z_NO_FLUSH",
   "Z_PARTIAL_FLUSH", "Z_SYNC_FLUSH", "Z_FULL_FLUSH", "Z_BLOCK" (zlib
   1.2.3.4), o "Z_FINISH", por defecto "Z_FINISH". Excepto "Z_FINISH",
   todas las constantes permiten comprimir más cadenas de bytes,
   mientras que "Z_FINISH" finaliza el flujo comprimido y evita la
   compresión de más datos. Después de llamar a "flush()" con *mode*
   establecido en "Z_FINISH", el método "compress()" no se puede
   volver a llamar. La única acción posible es eliminar el objeto.

Compress.copy()

   Retorna una copia del objeto compresor. Esto se puede utilizar para
   comprimir eficientemente un conjunto de datos que comparten un
   prefijo inicial común.

Distinto en la versión 3.8: Añadido "copy.copy()" y "copy.deepcopy()"
para el soporte de objetos de compresión.

Los objetos de descompresión admiten los siguientes métodos y
atributos:

Decompress.unused_data

   Un objeto de bytes que contiene todos los bytes restantes después
   de los datos comprimidos. Es decir, esto permanece "b """ hasta que
   esté disponible el último byte que contiene datos de compresión. Si
   la cadena de bytes completa resultó contener datos comprimidos, es
   "b""", un objeto de bytes vacío.

Decompress.unconsumed_tail

   Un objeto de bytes que contiene datos no procesados por la última
   llamada al método "descompress()" , debido a un desbordamiento del
   límite del búfer de datos descomprimidos. Estos datos aún no han
   sido procesados por la biblioteca zlib, por lo que debe enviarlos
   (potencialmente concatenando los datos nuevamente) mediante una
   llamada al método "descompress()" para obtener la salida correcta.

Decompress.eof

   Un valor booleano que indica si se ha alcanzado el final del flujo
   de datos comprimido.

   Esto hace posible distinguir entre un flujo comprimido
   correctamente y un flujo incompleto.

   Nuevo en la versión 3.3.

Decompress.decompress(data, max_length=0)

   Descomprime *data*, retornando un objeto de bytes que contiene al
   menos parte de los datos descomprimidos en *string*. Estos datos
   deben concatenarse con la salida producida por cualquier llamada
   anterior al método "decompress()". Algunos de los datos de entrada
   pueden conservarse en búfer internos para su posterior
   procesamiento.

   Si el parámetro opcional *max_length* no es cero, el valor de
   retorno no será más largo que *max_length*. Esto puede significar
   que no toda la entrada comprimida puede procesarse; y los datos no
   consumidos se almacenarán en el atributo "unconsumed_tail". Esta
   cadena de bytes debe pasarse a una llamada posterior a
   "decompress()" si la descompresión ha de continuar. Si *max_length*
   es cero, toda la entrada se descomprime y "unconsumed_tail" queda
   vacío.

   Distinto en la versión 3.6: *max_length* puede ser utilizado como
   argumento de palabras clave.

Decompress.flush([length])

   Se procesan todas las entradas pendientes y se retorna un objeto de
   bytes que contiene el resto de los datos que se descomprimirán.
   Después de llamar a "flush()", no se puede volver a llamar al
   método "decompress()". La única acción posible es eliminar el
   objeto.

   El parámetro opcional *length* establece el tamaño inicial del
   búfer de salida.

Decompress.copy()

   Retorna una copia del objeto de descompresión. Puede usarlo para
   guardar el estado de la descompresión actual, de modo que pueda
   regresar rápidamente a esta ubicación más tarde.

Distinto en la versión 3.8: Añadido "copy.copy()" y "copy.deepcopy()"
para el soporte de objetos de compresión.

La información sobre la versión de la biblioteca zlib en uso está
disponible a través de las siguientes constantes:

zlib.ZLIB_VERSION

   Versión de la biblioteca zlib utilizada al compilar el módulo.
   Puede ser diferente de la biblioteca zlib utilizada actualmente por
   el sistema, que puede ver en "ZLIB_RUNTIME_VERSION".

zlib.ZLIB_RUNTIME_VERSION

   Cadena que contiene la versión de la biblioteca zlib utilizada
   actualmente por el intérprete.

   Nuevo en la versión 3.3.

Ver también:

  Módulo "gzip"
     Lectura y escritura de los archivos en formato **gzip**.

  http://www.zlib.net
     Página oficial de la biblioteca zlib.

  http://www.zlib.net/manual.html
     El manual de zlib explica la semántica y el uso de las numerosas
     funciones de la biblioteca.
