13.1. 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 devuelve 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])

Compresses the bytes in data, returning a bytes object containing compressed data. level is an integer from 0 to 9 controlling the level of compression; 1 is fastest and produces the least compression, 9 is slowest and produces the most. 0 is no compression. The default value is 6. Raises the error exception if any error occurs.

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

Devuelve 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. A value of 1 is fastest and produces the least compression, while a value of 9 is slowest and produces the most. 0 is no compression. The default value is -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION represents a default compromise between speed and compression (currently equivalent to level 6).

method is the compression algorithm. Currently, the only supported value is DEFLATED.

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:

  • +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 «checksum» de comprobació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 :program: gzip y «checksum» 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 is used to tune the compression algorithm. Possible values are Z_DEFAULT_STRATEGY, Z_FILTERED, and Z_HUFFMAN_ONLY.

zdict es un diccionario de compresión predefinido. Este es una secuencia de bytes (como un objeto: clase: 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 «checksum» 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 devuelve 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[, bufsize]])

Descomprime los bytes en data, devolviendo 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.

When decompressing a stream, the window size must not be smaller than the size originally used to compress the stream; using a too-small value may result in an error exception. The default wbits value is 15, which corresponds to the largest window size and requires a zlib header and trailer to be included.

bufsize is the initial size of the buffer used to hold decompressed data. If more space is required, the buffer size will be increased as needed, so you don’t have to get this value exactly right; tuning it will only save a few calls to malloc(). The default size is 16384.

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

Devuelve 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 devuelve 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_SYNC_FLUSH, Z_FULL_FLUSH, or Z_FINISH, defaulting to Z_FINISH. Z_SYNC_FLUSH and Z_FULL_FLUSH 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()

Devuelve una copia del objeto compresor. Esto se puede utilizar para comprimir eficientemente un conjunto de datos que comparten un prefijo inicial comú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])

Descomprime data, devolviendo 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 :meth: decompress. Algunos de los datos de entrada pueden conservarse en búfer internos para su posterior procesamiento.

If the optional parameter max_length is non-zero then the return value will be no longer than max_length. This may mean that not all of the compressed input can be processed; and unconsumed data will be stored in the attribute unconsumed_tail. This bytestring must be passed to a subsequent call to decompress() if decompression is to continue. If max_length is not supplied then the whole input is decompressed, and unconsumed_tail is empty.

Decompress.flush([length])

Se procesan todas las entradas pendientes y se devuelve un objeto de bytes que contiene el resto de los datos que se descomprimirán. Después de llamar a :meth: 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()

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

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.