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