# `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` supports all the members specified by `io.BufferedIOBase`, except for `detach()` and `truncate()`. Iteration and the `with` statement are supported.

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