lzma — Compresión utilizando el algoritmo LZMA

Nuevo en la versión 3.3.

Código fuente:Lib/lzma.py

Este módulo provee clases y funciones de conveniencia para comprimir y descomprimir datos utilizando el algoritmo de compresión LZMA. También se incluye una interfaz de fichero soportando el .xz y formatos de fichero .lzma heredados utilizados por la utilidad xz, así como flujos comprimidos sin procesar.

La interfaz proporcionada por este módulo es muy similar a la del módulo bz2. Tenga en cuenta que LZMAFile y bz2.BZ2File son seguros para subprocesos not, por lo que si necesita utilizar una única instancia LZMAFile de varios subprocesos, es necesario protegerla con un candado.

exception lzma.LZMAError

Esta excepción es generada cuando un error ocurre durante la compresión o descompresión, o mientras se inicializa el estado de compresor/descompresor.

Leyendo y escribiendo ficheros comprimidos

lzma.open(filename, mode='rb', *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)

Abre un fichero comprimido LZMA in binario o modo texto, retornando un file object.

El argumento filename puede ser un nombre de fichero real (dado como un objeto str, bytes o path-like), en cuyo caso el fichero nombrado es abierto, o puede ser un objeto de fichero existente para leer o escribir.

El argumento mode puede ser cualquiera de "r", "rb", "w", "wb", "x", "xb", "a" o "a" para modo binario, o "rt", "wt", "xt", o "at" para modo texto. Por defecto es "rb".

Al abrir un fichero para lectura, los argumentos format y filters tienen el mismo significado que para LZMADecompressor. En este caso, los argumentos check y preset no deberían ser utilizados.

Al abrir un fichero para lectura, los argumentos format, check, preset y filters tienen el mismo significado que para LZMACompressor.

Para modo binario, esta función es equivalente al constructor LZMAFile: LZMAFile(filename, mode, ...). En este caso, los argumentos encoding, errors y newline no deben ser proveídos.

Para modo texto, un objeto LZMAFile es creado, y envuelto en una instancia io.TextIOWrapper con codificación específica, comportamiento de manejo de errores, y codificación(es) de línea.

Distinto en la versión 3.4: Agregado soporte para los modos "x", "xb" y "xt".

Distinto en la versión 3.6: Acepta un path-like object.

class lzma.LZMAFile(filename=None, mode='r', *, format=None, check=-1, preset=None, filters=None)

Abre un fichero comprimido LZMA en modo binario.

Un LZMAFIle puede envolver un ya abierto file object, u operar directamente en un fichero nombrado. El argumento filename especifica el objeto de fichero a envolver, o el nombre del fichero para abrir (como un str, bytes o un objeto path-like). Al envolver un objeto de fichero existente, el fichero envuelto no será cerrado cuando el LZMAFile es cerrado.

El argumento mode puede ser "r" para lectura (por defecto), "w" para sobreescritura, "x" para creación exclusiva, o "a" para agregado, Estos pueden ser equivalentemente dados como "rb", "wb", "xb" y "ab" respectivamente.

Si filename es un objeto de fichero (en lugar de un nombre de fichero actual), un modo de "w" no trunca el fichero, y en cambio es equivalente a "a".

Al abrir un fichero para escritura, el fichero de entrada puede ser la concatenación para múltiples flujos comprimidos separados. Estos son transparentemente decodificados como un único flujo lógico.

Al abrir un fichero para lectura, los argumentos format y filters tienen el mismo significado que para LZMADecompressor. En este caso, los argumentos check y preset no deberían ser utilizados.

Al abrir un fichero para lectura, los argumentos format, check, preset y filters tienen el mismo significado que para LZMACompressor.

LZMAFile supports all the members specified by io.BufferedIOBase, except for detach() and truncate(). Iteration and the with statement are supported.

El siguiente método también es proveído:

peek(size=-1)

Retorna datos almacenados en búfer sin avanzar la posición del fichero. Al menos un byte de datos será retornado, a menos que EOF es alcanzado. El número exacto de bytes retornado no está especificado (el argumento size es ignorado).

Nota

Mientras que llamar peek() no cambia la posición de fichero del LZMAFile, puede cambiar la posición del objeto de fichero subyacente (por ejemplo si el LZMAFile fue construido pasando un objeto de fichero por filename).

Distinto en la versión 3.4: Agregado soporte para los modos "x" y "xb".

Distinto en la versión 3.5: El método read() acepta ahora un argumento de None.

Distinto en la versión 3.6: Acepta un path-like object.

Comprimiendo y descomprimiendo datos en memoria

class lzma.LZMACompressor(format=FORMAT_XZ, check=-1, preset=None, filters=None)

Crea un objeto compresor, el cual puede ser utilizado para comprimir datos incrementalmente.

Para una forma más conveniente de comprimir un único fragmento de datos, vea compress().

El argumento format especifica qué formato de contenedor debería ser utilizado. Posibles valores son:

  • FORMAT_XZ: El formato de contenedor .xz.

    Este es el formato por defecto.

  • FORMAT_ALONE: El formato de contenedor .lzma heredado.

    Este formato es más limitado que .xz – no soporta chequeos de integridad o múltiples filtros.

  • FORMAT_RAW: Un flujo de datos sin procesar, sin utilizar ningún formato de contenedor.

    Este especificador de formato no soporta chequeos de integridad, y requiere que siempre especifiques una cadena de filtro personalizada (para compresión y descompresión). Adicionalmente, los datos comprimidos de esta manera no pueden ser descomprimidos utilizando FORMAT_AUTO (vea LZMADecompressor).

El argumento check especifica el tipo de chequeo de integridad a incluir en los datos descomprimidos. Este chequeo es utilizado al descomprimir, para asegurarse que los datos no han sido corrompidos. Los posibles valores son:

  • CHECK_NONE: Sin verificación de integridad. Este es el valor por defecto (y el único valor aceptable) para FORMAT_ALONE y FORMAT_RAW.

  • CHECK_CRC32: Chequeo de Redundancia Cíclica de 32 bits.

  • CHECK_CRC64: Chequeo de Redundancia Cíclica de 64 bits. Este es el valor por defecto para FORMAT_XZ.

  • CHECK_SHA256: Algoritmo Hash Seguro de 256 bits.

Si el chequeo especificado no es soportado, un LZMAError es generado.

Las configuraciones de compresión pueden ser especificadas como un nivel de compresión predefinido (con el argumento preset), o en detalle como una cadena de filtro personalizada (con el argumento filters).

El argumento preset (si es proveído) debería ser un entero entre 0 y 9 (inclusive), opcionalmente OR con la constante PRESET_EXTREME. Si no se proporciona preset ni filters, el comportamiento por defecto es utilizar PRESET_DEFAULT (nivel preestablecido 6). Altos preestablecidos producen salidas más pequeñas, pero vuelve el proceso de compresión más lento.

Nota

En adición a ser más CPU-intensivo, la compresión con preestablecidos más altos también requiere mucha más memoria (y produce salida que necesita más memoria a descomprimir). Con un preestablecido de 9 por ejemplo, la sobrecarga para un objeto LZMACompressor puede ser tan alto como 800MiB. Por esta razón, es generalmente mejor quedarse con el preestablecido por defecto.

El argumento filters (si es proveído) debería ser un especificador de cadena de filtro. Vea Especificando cadenas de filtro personalizadas para detalles.

compress(data)

Comprime data (un objeto bytes), retornando un objeto bytes conteniendo información comprimida por al menos parte de la entrada. Algo de data puede ser almacenado internamente, para uso en llamadas posteriores a compress() y flush(). La información retornada debería ser concatenada con la salida en cualquier llamada previa a compress().

flush()

Finiquita el proceso de compresión, retornando un objeto bytes conteniendo cualquier información almacenada en los búferes internos del compresor.

El compresor no puede ser utilizado después de que este método es llamado.

class lzma.LZMADecompressor(format=FORMAT_AUTO, memlimit=None, filters=None)

Crea un objeto descompresor, el cual puede ser utilizado para descomprimir datos incrementalmente.

Para una forma más conveniente de descomprimir un flujo completo de compresión a la vez, vea decompress().

El argumento format especifica el formato de contenedor que debería ser utilizado. El valor por defecto es FORMAT_AUTO, el cual puede descomprimir los ficheros .xz y .lzma. Otros posibles valores son FORMAT_XZ, FORMAT_ALONE, y FORMAT_RAW.

El argumento memlimit especifica un límite (en bytes) en la cantidad de memoria que el descompresor puede utilizar. Cuando este argumento es utilizado, la descompresión fallará con un LZMAError si no es posible descomprimir la entrada dentro del límite de memoria dado.

El argumento filters especifica la cadena de filtro que fue utilizado para crear el flujo que se descomprime. El argumento es requerido si format es FORMAT_RAW, pero no debería ser utilizado para otros formatos. Vea Especificando cadenas de filtro personalizadas para más información sobre cadenas de filtro.

Nota

Esta clase no maneja transparentemente entradas que contienen múltiples flujos comprimidos, a diferencia de decompress() y LZMAFile. Para descomprimir una entrada multi-flujo con LZMADecompressor, debería crear un nuevo descompresor para cada flujo.

decompress(data, max_length=-1)

Descomprime data (un bytes-like object), retornando información sin comprimir como bytes. Alguna data puede ser almacenada internamente, para uso en llamadas posteriores a decompress(). La información retornada debería ser concatenada con la salida de cualquier llamada anterior a decompress().

Si max_length no es negativo, retorna al menos max_length bytes para descomprimir información, Si este límite es alcanzado y salidas adicionales pueden ser producidas, el atributo needs_input será establecido a False. En este caso, la siguiente llamada a decompress() podría proveer data como "b'' para obtener más de la salida.

Si toda la información ingresada fue descomprimida y retornada (ya sea porque esto fue menos que max_length bytes, o porque max_length fue negativo), el atributo needs_input será establecido a True.

Attempting to decompress data after the end of stream is reached raises an EOFError. Any data found after the end of the stream is ignored and saved in the unused_data attribute.

Distinto en la versión 3.5: Agregado el parámetro max_length.

check

El ID del chequeo de integridad utilizado por el flujo de entrada. Esto puede ser CHECK_UNKNOWN hasta que suficiente de la entrada ha sido decodificada para determinar qué chequeo de integridad utiliza.

eof

True si el marcador de fin-de-flujo ha sido alcanzado.

unused_data

Información encontrada después del fin del flujo comprimido.

Antes de que el fin del flujo es alcanzado, este será "b".

needs_input

False si el método decompress() puede proveer más información descomprimida antes de requerir nueva entrada descomprimida.

Nuevo en la versión 3.5.

lzma.compress(data, format=FORMAT_XZ, check=-1, preset=None, filters=None)

Comprime data (un objeto bytes), retornando la información comprimida como un objeto bytes.

Vea LZMACompressor arriba para una descripción de los argumentos format, check, preset y filters.

lzma.decompress(data, format=FORMAT_AUTO, memlimit=None, filters=None)

Descomprime data (un objeto bytes), retornando la información descomprimida como un objeto bytes.

Si data es la concatenación de múltiples flujos comprimidos distintos, descomprime todos esos flujos, y retorna la concatenación de los resultados.

Vea LZMADecompressor arriba para una descripción de los argumentos format, memlimit y filters.

Misceláneas

lzma.is_check_supported(check)

Retorna True si el chequeo de integridad dado es soportado en este sistema.

CHECK_NONE y CHECK_CRC32 son soportados siempre. CHECK_CRC64 y CHECK_SHA256 pueden no estar disponibles si está utilizando una versión de liblzma que fue compilada con un conjunto de funciones limitado.

Especificando cadenas de filtro personalizadas

Un especificador de cadena de filtro es una secuencia de diccionarios, donde cada diccionario contiene el ID y opciones para un único filtro. Cada diccionario debe contener la llave "id", y puede contener llaves adicionales para especificar opciones filtro-dependientes. Los ID de filtro válidos son como sigue:

  • Filtro de compresión:

    • FILTER_LZMA1 (para uso con FORMAT_ALONE)

    • FILTER_LZMA2 (para uso con FORMAT_XZ y bytesFORMAT_RAW)

  • Filtro delta:

    • FILTER_DELTA

  • Filtros Branch-Call-Jump (BCJ):

    • FILTER_X86

    • FILTER_IA64

    • FILTER_ARM

    • FILTER_ARMTHUMB

    • FILTER_POWERPC

    • FILTER_SPARC

Una cadena de filtro puede consistir de hasta 4 filtros, y no puede estar vacía. El último filtro en la cadena debe ser un filtro de compresión, y cualquier otro filtro debe ser un filtro delta o BCJ.

Los filtros de compresión soportan las siguientes opciones (especificadas como entradas adicionales:

  • preset: Un ajuste de compresión a utilizar como una fuente de valores por defecto para opciones que no están especificadas explícitamente.

  • dict_size: Tamaño del diccionario en bytes. Esto debería estar entre 4 kiB y 1.5 GiB (inclusive).

  • lc Número de bits de contexto literal.

  • lp: Número de bits de posición literal. La suma lc + lp debe ser al menos 4.

  • pb: Número de bits de posición; debe ser al menos 4.

  • mode: MODE_FAST o MODE_NORMAL.

  • nice_len: Lo que debería ser considerado una «buena longitud» para una coincidencia. Esto debería ser 273 o menos.

  • mf: Qué buscador de coincidencias utilizar – MF_HC3, MF_HC4. MF_BT2, MF_BT3, o MF_BT4.

  • depth: Profundidad de búsqueda máxima utilizada por el buscador de coincidencias. 0 (por defecto) significa seleccionar automáticamente basado en otras opciones de filtro.

El filtro delta almacena las diferencias entre bytes, produciendo más entrada repetitiva para el compresor en ciertas circunstancias. Soporta una opción, dist. Esto indica la distancia entre bytes a ser sustraída. Por defecto es 1, por ejemplo toma las diferencias entre bytes adyacentes.

Los filtros BCJ están destinados a ser aplicados a código máquina. Convierten ramas, llamadas y saltos relativos en el código para utilizar el direccionamiento absoluto, con el objetivo de incrementar la redundancia que puede ser explotada por el compresor. Estos filtros soportan una opción, start_offset. Esto especifica la dirección que debería ser mapeada al comienzo de la entrada de información. Por defecto es 0.

Ejemplos

Leyendo un fichero comprimido:

import lzma
with lzma.open("file.xz") as f:
    file_content = f.read()

Creando un fichero comprimido:

import lzma
data = b"Insert Data Here"
with lzma.open("file.xz", "w") as f:
    f.write(data)

Comprimiendo información en memoria:

import lzma
data_in = b"Insert Data Here"
data_out = lzma.compress(data_in)

Compresión incremental:

import lzma
lzc = lzma.LZMACompressor()
out1 = lzc.compress(b"Some data\n")
out2 = lzc.compress(b"Another piece of data\n")
out3 = lzc.compress(b"Even more data\n")
out4 = lzc.flush()
# Concatenate all the partial results:
result = b"".join([out1, out2, out3, out4])

Escribiendo información comprimida en fichero ya abierto:

import lzma
with open("file.xz", "wb") as f:
    f.write(b"This data will not be compressed\n")
    with lzma.open(f, "w") as lzf:
        lzf.write(b"This *will* be compressed\n")
    f.write(b"Not compressed\n")

Creando un fichero comprimido utilizando una cadena de filtro personalizada:

import lzma
my_filters = [
    {"id": lzma.FILTER_DELTA, "dist": 5},
    {"id": lzma.FILTER_LZMA2, "preset": 7 | lzma.PRESET_EXTREME},
]
with lzma.open("file.xz", "w", filters=my_filters) as f:
    f.write(b"blah blah blah")