# `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 comprimir e descomprimir dados usando o algoritmo de compressã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 comprimidos.

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 compressão ou descompressão ou durante a inicialização do estado compressor/descompressor.

## Lendo e escrevendo arquivos comprimidos

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

  Abre um arquivo comprimido 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 comprimido 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 objeto caminho ou similar). Ao agrupar um objeto 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 comprimidos 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` suporta todos os membros especificados por `io.BufferedIOBase`, exceto `detach()` e `truncate()`. Iteração e a instrução `with` são suportadas.

  O seguinte método 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.

## Comprimindo e descomprimindo dados na memória

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

  Cria um objeto compressão, que pode ser usado para comprimir dados de forma incremental.

  Para uma maneira mais conveniente de comprimir 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 compressão e descompressão). Além disso, dados comprimidos dessa maneira não podem ser descomprimidos usando `FORMAT_AUTO` (veja `LZMADecompressor`).

  O argumento check especifica o tipo de verificação de integridade a ser incluída nos dados comprimidos. Essa verificação é usada ao descomprimir, 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 compressão podem ser especificadas como um nível de compressã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 compressão mais lento.

  Nota

  Além de consumir mais CPU, a compressã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 descompressão). 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 Especificando cadeias de filtros personalizadas para detalhes.

  compress(data)

    Comprime data (um objeto `bytes`), retornando um objeto `bytes` contendo dados comprimidos para pelo menos parte da entrada. Alguns dos data podem ser armazenados internamente, para uso em chamadas posteriores para `compress()` e `flush()`. Os dados retornados devem ser concatenados com a saída de quaisquer chamadas anteriores para `compress()`.

  flush()

    Conclui o processo de compressão, retornando um objeto `bytes` contendo todos os dados armazenados nos buffers internos do compressor.

    O compressor não pode ser usado após a chamada deste método.

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

  Cria um objeto descompressor, que pode ser usado para descomprimir dados de forma incremental.

  Para uma maneira mais conveniente de descomprimir um fluxo comprimido inteiro de uma só vez, consulte `decompress()`.

  O argumento format especifica o formato do contêiner que deve ser usado. O padrão é `FORMAT_AUTO`, que pode descomprimir os arquivos `.xz` e `.lzma`. Outros valores possíveis são `FORMAT_XZ`, `FORMAT_ALONE` e `FORMAT_RAW`.

  O argumento memlimit especifica um limite (em bytes) na quantidade de memória que o descompressor pode usar. Quando esse argumento é usado, a descompressão falhará com um `LZMAError` se não for possível descomprimir a entrada dentro do limite de memória fornecido.

  O argumento filters especifica a cadeia de filtros que foi usada para criar o fluxo que está sendo descomprimido. Este argumento é necessário se format for `FORMAT_RAW`, mas não deve ser usado para outros formatos. Veja Especificando cadeias de filtros personalizadas para mais informações sobre cadeias de filtros.

  Nota

  Esta classe não manipula de forma transparente entradas contendo múltiplos fluxos comprimidos, diferentemente de `decompress()` e `LZMAFile`. Para descomprimir uma entrada multi-fluxo com `LZMADecompressor`, você deve criar um novo descompactador para cada fluxo.

  decompress(data, max_length=-1)

    Descomprime dados data (um objeto bytes ou similar), retornando dados não comprimidos 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 descomprimidos. 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 descomprimidos 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 descomprimir 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

    O ID da verificação de integridade usada pelo fluxo de entrada. Pode ser `CHECK_UNKNOWN` até que o suficiente da entrada tenha sido decodificado para determinar qual verificação de integridade ela usa.

  eof

    `True` se o marcador de fim de fluxo foi atingido.

  unused_data

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

    Antes do final do fluxo ser alcançado, isso será `b""`.

  needs_input

    `False` se o método `decompress()` puder fornecer mais dados descomprimidos antes de exigir uma nova entrada não comprimida.

    Novo na versão 3.5.

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

  Comprime data (um objeto `bytes`), retornando os dados comprimidos como um objeto `bytes`.

  Veja `LZMACompressor` acima para uma descrição dos argumentos format, check, preset e filters.

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

  Descomprime data (um objeto `bytes`), retornando os dados não comprimidos como um objeto `bytes`.

  Se data forem a concatenação de vários fluxos comprimidos distintos, descomprime todos esses fluxos e retorna a concatenação dos resultados.

  Veja `LZMADecompressor` acima para uma descrição dos argumentos format, memlimit e filters.

## Diversos

lzma.is_check_supported(check)

  Retorna `True` se a verificação de integridade fornecida for suportada neste sistema.

  `CHECK_NONE` e `CHECK_CRC32` são sempre suportados. `CHECK_CRC64` e `CHECK_SHA256` podem não estar disponíveis se você estiver usando uma versão do liblzma que foi compilada com um conjunto de recursos limitado.

## Especificando cadeias de filtros personalizadas

Um especificador de cadeia de filtros é uma sequência de dicionários, onde cada dicionário contém o ID e as opções para um único filtro. Cada dicionário deve conter a chave `"id"` e pode conter chaves adicionais para especificar opções dependentes do filtro. Os IDs de filtro válidos são os seguintes:

- Filtro Compression:

  - `FILTER_LZMA1` (para ser usado com `FORMAT_ALONE`)

  - `FILTER_LZMA2` (para ser utilizado com `FORMAT_XZ` and `FORMAT_RAW`)

- Filtro delta:

  - `FILTER_DELTA`

- Filtros Branch-Call-Jump (BCJ):

  - `FILTER_X86`

  - `FILTER_IA64`

  - `FILTER_ARM`

  - `FILTER_ARMTHUMB`

  - `FILTER_POWERPC`

  - `FILTER_SPARC`

Uma cadeia de filtros pode consistir em até 4 filtros e não pode estar vazia. O último filtro na cadeia deve ser um filtro de compressão e quaisquer outros filtros devem ser filtros delta ou BCJ.

Os filtros de compressão suportam as seguintes opções (especificadas como entradas adicionais no dicionário que representa o filtro):

- `preset`: Uma predefinição de compressão para usar como fonte de valores padrão para opções que não são especificadas explicitamente.

- `dict_size`: Tamanho do dicionário em bytes. Deve estar entre 4 KiB e 1,5 GiB (inclusive).

- `lc`: Número de bits de contexto literal.

- `lp`: Número de bits de posição literal. A soma `lc + lp` deve ser no máximo 4.

- `pb`: Número de bits de posição; deve ser no máximo 4.

- `mode`: `MODE_FAST` ou `MODE_NORMAL`.

- `nice_len`: O que deve ser considerado um “tamanho agradável” para uma correspondência. Deve ser 273 ou menos.

- `mf`: Qual localizador de correspondências usar – `MF_HC3`, `MF_HC4`, `MF_BT2`, `MF_BT3` ou `MF_BT4`.

- `depth`: Profundidade máxima de pesquisa usada pelo localizador de correspondências. 0 (padrão) significa selecionar automaticamente com base em outras opções de filtro.

O filtro delta armazena as diferenças entre bytes, produzindo uma entrada mais repetitiva para o compressor em certas circunstâncias. Ele suporta uma opção, `dist`. Isso indica a distância entre bytes a ser subtraída. O padrão é 1, ou seja, pega as diferenças entre bytes adjacentes.

Os filtros BCJ são destinados a serem aplicados ao código de máquina. Eles convertem ramificações relativas, chamadas e saltos no código para usar endereçamento absoluto, com o objetivo de aumentar a redundância que pode ser explorada pelo compressor. Esses filtros suportam uma opção, `start_offset`. Isso especifica o endereço que deve ser mapeado para o início dos dados de entrada. O padrão é 0.

## Exemplos

Lendo em um arquivo comprimido:

    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)

Comprimindo dados na memória:

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

Escrevendo dados comprimidos em um arquivo já aberto:

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

Criando um arquivo comprimido usando uma cadeia de filtros 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")