lzma — Compactação usando o algoritmo LZMA

Novo na versão 3.3.

Código-fonte: Lib/lzma.py

Este módulo fornece classes e funções de conveniência para compactar e descompactar dados usando o algoritmo de compactação LZMA. Também está incluída uma interface de arquivo que oferece suporte aos formatos de arquivo .xz e legado .lzma usados pelo utilitário xz, bem como fluxos brutos compactados.

A interface fornecida por este módulo é muito semelhante à do módulo bz2. Observe que LZMAFile e bz2.BZ2File não são seguro para thread, portanto, se você precisar usar uma única instância LZMAFile de vários threads, é necessário protegê-la com uma trava.

exception lzma.LZMAError

Essa exceção é levantada quando ocorre um erro durante a compactação ou descompactação ou durante a inicialização do estado compactador/descompactador.

Lendo e escrevendo arquivos compactados

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

Abre um arquivo compactado com LZMA no modo binário ou texto, retornando um objeto arquivo.

O argumento filename pode ser um nome de arquivo real (dado como um objeto str, bytes ou caminho ou similar), neste caso o arquivo nomeado é aberto , ou pode ser um objeto arquivo existente para leitura ou escrita.

O argumento mode pode ser qualquer um de "r", "rb", "w", "wb", "x", "xb", "a" ou "ab" para modo binário, ou "rt", "wt", "xt" , ou "at" para o modo de texto. O padrão é "rb".

Ao abrir um arquivo para leitura, os argumentos format e filters têm os mesmos significados que em LZMADecompressor. Neste caso, os argumentos check e preset não devem ser usados.

Ao abrir um arquivo para escrita, os argumentos format, check, preset e filters têm os mesmos significados que em LZMACompressor.

Para o modo binário, esta função é equivalente ao construtor LZMAFile: LZMAFile(filename, mode, ...). Nesse caso, os argumentos encoding, errors e newline não devem ser fornecidos.

Para o modo texto, um objeto LZMAFile é criado e encapsulado em uma instância io.TextIOWrapper com a codificação especificada, comportamento de tratamento de erros e final(is) de linha.

Alterado na versão 3.4: Adicionado suporte para os modos "x", "xb" e "xt".

Alterado na versão 3.6: Aceita um objeto caminho ou similar.

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

Abre um arquivo compactado com LZMA no modo binário.

Um LZMAFile pode envolver um objeto arquivo já aberto, ou operar diretamente em um arquivo nomeado. O argumento filename especifica o objeto arquivo a ser encapsulado ou o nome do arquivo a ser aberto (como um objeto str, bytes ou caminho ou similar). Ao agrupar um objeto de arquivo existente, o arquivo agrupado não será fechado quando o LZMAFile for fechado.

O argumento mode pode ser "r" para leitura (padrão), "w" para substituição, "x" para criação exclusiva ou "a" para anexar. Estes podem ser equivalentemente dados como "rb", "wb", "xb" e "ab" respectivamente.

Se filename for um objeto arquivo (em vez de um nome de arquivo real), um modo de "w" não truncará o arquivo e será equivalente a "a".

Ao abrir um arquivo para leitura, o arquivo de entrada pode ser a concatenação de vários fluxos compactados separados. Estes são decodificados de forma transparente como um único fluxo lógico.

Ao abrir um arquivo para leitura, os argumentos format e filters têm os mesmos significados que em LZMADecompressor. Neste caso, os argumentos check e preset não devem ser usados.

Ao abrir um arquivo para escrita, os argumentos format, check, preset e filters têm os mesmos significados que em LZMACompressor.

LZMAFile oferece suporte a todos os membros especificados por io.BufferedIOBase, exceto detach() e truncate(). Iteração e a instrução with são suportadas.

O método a seguir também é fornecido:

peek(size=- 1)

Retorna dados armazenados em buffer sem avançar a posição do arquivo. Pelo menos um byte de dados será retornado, a menos que o EOF tenha sido atingido. O número exato de bytes retornados não é especificado (o argumento size é ignorado).

Nota

Enquanto chamar peek() não altera a posição do arquivo de LZMAFile, pode alterar a posição do objeto arquivo subjacente (por exemplo, se o LZMAFile foi construído passando um objeto arquivo para nome do arquivo).

Alterado na versão 3.4: Adicionado suporte para os modos "x" e "xb".

Alterado na versão 3.5: O método read() agora aceita um argumento de None.

Alterado na versão 3.6: Aceita um objeto caminho ou similar.

Compactando e descompactando dados na memória

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

Cria um objeto compactador, que pode ser usado para compactar dados de forma incremental.

Para uma maneira mais conveniente de compactar um único bloco de dados, consulte compress().

O argumento format especifica qual formato de contêiner deve ser usado. Os valores possíveis são:

  • FORMAT_XZ: O formato de contêiner .xz.

    Este é o formato padrão.

  • FORMAT_ALONE: O formato de contêiner legado .lzma.

    Este formato é mais limitado que .xz – ele não oferece suporte a verificações de integridade ou filtros múltiplos.

  • FORMAT_RAW: Um fluxo de dados brutos, que não usa nenhum formato de contêiner.

    Esse especificador de formato não oferece suporte a verificações de integridade e exige que você sempre especifique uma cadeia de filtros personalizada (para compactação e descompactação). Além disso, dados compactados dessa maneira não podem ser descompactados usando FORMAT_AUTO (veja LZMADecompressor).

O argumento check especifica o tipo de verificação de integridade a ser incluída nos dados compactados. Essa verificação é usada ao descompactar, para garantir que os dados não foram corrompidos. Os valores possíveis são:

  • CHECK_NONE: Sem verificação de integridade. Este é o padrão (e o único valor aceitável) para FORMAT_ALONE e FORMAT_RAW.

  • CHECK_CRC32: Verificação de redundância cíclica de 32 bits.

  • CHECK_CRC64: Verificação de redundância cíclica de 64 bits. Este é o padrão para FORMAT_XZ.

  • CHECK_SHA256: Algoritmo de hash seguro de 256 bits.

Se a verificação especificada não for suportada, uma exceção LZMAError será levantada.

As configurações de compactação podem ser especificadas como um nível de compactação predefinido (com o argumento preset) ou em detalhes como uma cadeia de filtros personalizada (com o argumento filters).

O argumento preset (se fornecido) deve ser um inteiro entre 0 e 9 (inclusive), opcionalmente com OR com a constante PRESET_EXTREME. Se nem preset nem filters forem fornecidos, o comportamento padrão é usar PRESET_DEFAULT (nível predefinido 6). Predefinições mais altas produzem uma saída menor, mas tornam o processo de compactação mais lento.

Nota

Além de consumir mais CPU, a compactação com predefinições mais altas também requer muito mais memória (e produz uma saída que precisa de mais memória para descompactar). Com a predefinição 9 por exemplo, a sobrecarga para um objeto LZMACompressor pode chegar a 800 MiB. Por esse motivo, geralmente é melhor ficar com a predefinição padrão.

O argumento filters (se fornecido) deve ser um especificador de cadeia de filtros. Veja Specifying custom filter chains para detalhes.

compress(data)

Compress data (a bytes object), returning a bytes object containing compressed data for at least part of the input. Some of data may be buffered internally, for use in later calls to compress() and flush(). The returned data should be concatenated with the output of any previous calls to compress().

flush()

Finish the compression process, returning a bytes object containing any data stored in the compressor’s internal buffers.

The compressor cannot be used after this method has been called.

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

Create a decompressor object, which can be used to decompress data incrementally.

For a more convenient way of decompressing an entire compressed stream at once, see decompress().

The format argument specifies the container format that should be used. The default is FORMAT_AUTO, which can decompress both .xz and .lzma files. Other possible values are FORMAT_XZ, FORMAT_ALONE, and FORMAT_RAW.

The memlimit argument specifies a limit (in bytes) on the amount of memory that the decompressor can use. When this argument is used, decompression will fail with an LZMAError if it is not possible to decompress the input within the given memory limit.

The filters argument specifies the filter chain that was used to create the stream being decompressed. This argument is required if format is FORMAT_RAW, but should not be used for other formats. See Specifying custom filter chains for more information about filter chains.

Nota

This class does not transparently handle inputs containing multiple compressed streams, unlike decompress() and LZMAFile. To decompress a multi-stream input with LZMADecompressor, you must create a new decompressor for each stream.

decompress(data, max_length=- 1)

Descompacta dados data (um objeto bytes ou similar), retornando dados não compactados como bytes. Alguns dos data podem ser armazenados em buffer internamente, para uso em chamadas posteriores para decompress(). Os dados retornados devem ser concatenados com a saída de qualquer chamada anterior para decompress().

Se max_length for não negativo, retornará no máximo max_length bytes de dados descompactados. Se este limite for atingido e mais saída puder ser produzida, o atributo needs_input será definido como False. Neste caso, a próxima chamada para decompress() pode fornecer data como b'' para obter mais saída.

Se todos os dados de entrada foram descompactados e retornados (seja porque era menor que max_length bytes, ou porque max_length era negativo), o atributo needs_input será definido como True .

A tentativa de descompactar os dados após o final do fluxo ser atingido gera um EOFError. Quaisquer dados encontrados após o final do fluxo são ignorados e salvos no atributo unused_data.

Alterado na versão 3.5: Adicionado o parâmetro max_length.

check

The ID of the integrity check used by the input stream. This may be CHECK_UNKNOWN until enough of the input has been decoded to determine what integrity check it uses.

eof

True se o marcador de fim de fluxo foi atingido.

unused_data

Dados encontrados após o término do fluxo compactado.

Before the end of the stream is reached, this will be b"".

needs_input

False se o método decompress() puder fornecer mais dados descompactados antes de exigir uma nova entrada descompactada.

Novo na versão 3.5.

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

Compress data (a bytes object), returning the compressed data as a bytes object.

See LZMACompressor above for a description of the format, check, preset and filters arguments.

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

Decompress data (a bytes object), returning the uncompressed data as a bytes object.

If data is the concatenation of multiple distinct compressed streams, decompress all of these streams, and return the concatenation of the results.

See LZMADecompressor above for a description of the format, memlimit and filters arguments.

Diversos

lzma.is_check_supported(check)

Return True if the given integrity check is supported on this system.

CHECK_NONE and CHECK_CRC32 are always supported. CHECK_CRC64 and CHECK_SHA256 may be unavailable if you are using a version of liblzma that was compiled with a limited feature set.

Specifying custom filter chains

A filter chain specifier is a sequence of dictionaries, where each dictionary contains the ID and options for a single filter. Each dictionary must contain the key "id", and may contain additional keys to specify filter-dependent options. Valid filter IDs are as follows:

  • Filtro Compression:

    • FILTER_LZMA1 (para ser usado com FORMAT_ALONE)

    • FILTER_LZMA2 (para ser utilizado com FORMAT_XZ and FORMAT_RAW)

  • Delta filter:

    • FILTER_DELTA

  • Branch-Call-Jump (BCJ) filters:

    • FILTER_X86

    • FILTER_IA64

    • FILTER_ARM

    • FILTER_ARMTHUMB

    • FILTER_POWERPC

    • FILTER_SPARC

A filter chain can consist of up to 4 filters, and cannot be empty. The last filter in the chain must be a compression filter, and any other filters must be delta or BCJ filters.

Compression filters support the following options (specified as additional entries in the dictionary representing the filter):

  • preset: A compression preset to use as a source of default values for options that are not specified explicitly.

  • dict_size: Dictionary size in bytes. This should be between 4 KiB and 1.5 GiB (inclusive).

  • lc: Number of literal context bits.

  • lp: Number of literal position bits. The sum lc + lp must be at most 4.

  • pb: Number of position bits; must be at most 4.

  • mode: MODE_FAST or MODE_NORMAL.

  • nice_len: What should be considered a “nice length” for a match. This should be 273 or less.

  • mf: What match finder to use – MF_HC3, MF_HC4, MF_BT2, MF_BT3, or MF_BT4.

  • depth: Maximum search depth used by match finder. 0 (default) means to select automatically based on other filter options.

The delta filter stores the differences between bytes, producing more repetitive input for the compressor in certain circumstances. It supports one option, dist. This indicates the distance between bytes to be subtracted. The default is 1, i.e. take the differences between adjacent bytes.

The BCJ filters are intended to be applied to machine code. They convert relative branches, calls and jumps in the code to use absolute addressing, with the aim of increasing the redundancy that can be exploited by the compressor. These filters support one option, start_offset. This specifies the address that should be mapped to the beginning of the input data. The default is 0.

Exemplos

Reading in a compressed file:

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

Criando um arquivo comprimido:

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

Compressing data in memory:

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

Compressão 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])

Writing compressed data to an already-open file:

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

Creating a compressed file using a custom filter chain:

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