"zlib" --- Compression compatible with **gzip**
***********************************************

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

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

zlib's functions have many options and often need to be used in a
particular order.  This documentation doesn't attempt to cover all of
the permutations; consult the zlib manual for authoritative
information.

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: El resultado es siempre sin signo.

zlib.compress(data, /, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)

   Compresses the bytes in *data*, returning a bytes object containing
   compressed data. *level* is an integer from "0" to "9" or "-1"
   controlling the level of compression; See "Z_BEST_SPEED" ("1"),
   "Z_BEST_COMPRESSION" ("9"), "Z_NO_COMPRESSION" ("0"), and the
   default, "Z_DEFAULT_COMPRESSION" ("-1") for more information about
   these values.

   The *wbits* argument controls the size of the history buffer (or
   the "window size") used when compressing data, and whether a header
   and trailer is included in the output.  It can take several ranges
   of values, defaulting to "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.

   Lanza la excepción "error" si ocurre cualquier error.

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

   Distinto en la versión 3.11: El parámetro *wbits* está ahora
   disponible para establecer bits de la ventana y tipo de compresión.

zlib.compressobj(level=Z_DEFAULT_COMPRESSION, 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* is the compression level -- an integer from "0" to "9" or
   "-1". See "Z_BEST_SPEED" ("1"), "Z_BEST_COMPRESSION" ("9"),
   "Z_NO_COMPRESSION" ("0"), and the default, "Z_DEFAULT_COMPRESSION"
   ("-1") for more information about these values.

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

   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 será usado.
   Tiene el mismo significado que el descrito para decompress().

   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* is used to tune the compression algorithm. Possible
   values are "Z_DEFAULT_STRATEGY", "Z_FILTERED", "Z_HUFFMAN_ONLY",
   "Z_RLE" and "Z_FIXED".

   *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: El resultado es siempre sin signo.

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

   All pending input is processed, and a bytes object containing the
   remaining compressed output is returned.  *mode* can be selected
   from the constants "Z_NO_FLUSH", "Z_PARTIAL_FLUSH", "Z_SYNC_FLUSH",
   "Z_FULL_FLUSH", "Z_BLOCK", or "Z_FINISH", defaulting to "Z_FINISH".
   Except "Z_FINISH", all constants allow compressing further
   bytestrings of data, while "Z_FINISH" finishes the compressed
   stream and prevents compressing any more data.  After calling
   "flush()" with *mode* set to "Z_FINISH", the "compress()" method
   cannot be called again; the only realistic action is to delete the
   object.

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 uno incompleto o truncado.

   Added in version 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.

The following constants are available to configure compression and
decompression behavior:

zlib.DEFLATED

   The deflate compression method.

zlib.MAX_WBITS

   The maximum window size, expressed as a power of 2. For example, if
   "MAX_WBITS" is "15" it results in a window size of "32 KiB".

zlib.DEF_MEM_LEVEL

   The default memory level for compression objects.

zlib.DEF_BUF_SIZE

   The default buffer size for decompression operations.

zlib.Z_NO_COMPRESSION

   Compression level "0"; no compression.

   Added in version 3.6.

zlib.Z_BEST_SPEED

   Compression level "1"; fastest and produces the least compression.

zlib.Z_BEST_COMPRESSION

   Compression level "9"; slowest and produces the most compression.

zlib.Z_DEFAULT_COMPRESSION

   Default compression level ("-1"); a compromise between speed and
   compression. Currently equivalent to compression level "6".

zlib.Z_DEFAULT_STRATEGY

   Default compression strategy, for normal data.

zlib.Z_FILTERED

   Compression strategy for data produced by a filter (or predictor).

zlib.Z_HUFFMAN_ONLY

   Compression strategy that forces Huffman coding only.

zlib.Z_RLE

   Compression strategy that limits match distances to one (run-length
   encoding).

   This constant is only available if Python was compiled with zlib
   1.2.0.1 or greater.

   Added in version 3.6.

zlib.Z_FIXED

   Compression strategy that prevents the use of dynamic Huffman
   codes.

   This constant is only available if Python was compiled with zlib
   1.2.2.2 or greater.

   Added in version 3.6.

zlib.Z_NO_FLUSH

   Flush mode "0". No special flushing behavior.

   Added in version 3.6.

zlib.Z_PARTIAL_FLUSH

   Flush mode "1". Flush as much output as possible.

zlib.Z_SYNC_FLUSH

   Flush mode "2". All output is flushed and the output is aligned to
   a byte boundary.

zlib.Z_FULL_FLUSH

   Flush mode "3". All output is flushed and the compression state is
   reset.

zlib.Z_FINISH

   Flush mode "4". All pending input is processed, no more input is
   expected.

zlib.Z_BLOCK

   Flush mode "5". A deflate block is completed and emitted.

   This constant is only available if Python was compiled with zlib
   1.2.2.2 or greater.

   Added in version 3.6.

zlib.Z_TREES

   Flush mode "6", for inflate operations. Instructs inflate to return
   when it gets to the next deflate block boundary.

   This constant is only available if Python was compiled with zlib
   1.2.3.4 or greater.

   Added in version 3.6.

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.

   Added in version 3.3.

Ver también:

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

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

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

  In case gzip (de)compression is a bottleneck, the python-isal
  package speeds up (de)compression with a mostly compatible API.
