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.

Las funciones de zlib tienen muchas opciones y, a menudo, deben usarse en un orden particular. Esta documentación no intenta cubrir todas las permutaciones; consulte 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: El resultado es siempre sin signo.

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

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 comprimir. 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)

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.

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

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

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.

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.