# `zlib` — Compactação compatível com gzip

Para aplicações que requerem compactação de dados, as funções neste módulo permitem compactação e descompactação, utilizando a biblioteca zlib.

Este é um módulo opcional. Se ele estiver faltando na sua cópia do CPython, procure a documentação do seu distribuidor (ou seja, quem lhe forneceu o Python). Se você for o distribuidor, consulte Requisitos para módulos opcionais.

As funções do zlib têm muitas opções e geralmente precisam ser usadas em uma ordem específica. Esta documentação não tenta cobrir todas as permutações; consulte o manual do zlib para obter informações oficiais.

Para leitura e escrita de arquivos `.gz`, consulte o módulo `gzip`.

A exceção e as funções disponíveis neste módulo são:

exception zlib.error

  Exceção levantada em erros de compactação e descompactação.

zlib.adler32(data[, value])

  Calcula uma soma de verificação Adler-32 de data. (Uma soma de verificação Adler-32 é quase tão confiável quanto uma CRC32, mas pode ser calculada muito mais rapidamente.) O resultado é um número inteiro sem sinal de 32 bits. Se value estiver presente, ele será usado como o valor inicial da soma de verificação; caso contrário, um valor padrão de 1 é usado. A passagem de value permite calcular uma soma de verificação em execução através da concatenação de várias entradas. O algoritmo não é criptograficamente forte e não deve ser usado para autenticação ou assinaturas digitais. Como o algoritmo foi projetado para uso como um algoritmo de soma de verificação, não é adequado para uso como um algoritmo de hash geral.

  Alterado na versão 3.0: O resultado é sempre sem sinal.

zlib.adler32_combine(adler1, adler2, len2, /)

  Combine two Adler-32 checksums into one.

  Given the Adler-32 checksum adler1 of a sequence `A` and the Adler-32 checksum adler2 of a sequence `B` of length len2, return the Adler-32 checksum of `A` and `B` concatenated.

  This function is typically useful to combine Adler-32 checksums that were concurrently computed. To compute checksums sequentially, use `adler32()` with the running checksum as the `value` argument.

  Adicionado na versão 3.15.

zlib.compress(data, /, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)

  Compacta os bytes em data, retornando um objeto bytes contendo dados compactados. level é um inteiro de `0` a `9` ou `-1` que controla o nível de compactação; Consulte `Z_BEST_SPEED` (`1`), `Z_BEST_COMPRESSION` (`9`), `Z_NO_COMPRESSION` (`0`) e o padrão, `Z_DEFAULT_COMPRESSION` (`-1`) para obter mais informações sobre esses valores.

  O argumento wbits controla o tamanho do buffer do histórico (ou o “tamanho da janela”) usado ao compactar dados e se um cabeçalho e um trailer estão incluídos na saída. Pode levar vários intervalos de valores, padronizando para `15` (`MAX_WBITS`):

  - +9 a +15: o logaritmo de base dois do tamanho da janela, que varia entre 512 e 32768. Valores maiores produzem melhor compactação às custas de maior uso de memória. A saída resultante incluirá um cabeçalho e uma sequência específicos para zlib.

  - -9 a -15: Usa o valor absoluto de wbits como o logaritmo do tamanho da janela, enquanto produz um fluxo de saída bruto sem cabeçalho ou soma de verificação à direita.

  - +25 a +31 = 16 + (9 a 15): Usa os 4 bits baixos do valor como logaritmo do tamanho da janela, incluindo um cabeçalho básico gzip e a soma de verificação à direita na saída.

  Levanta uma exceção do tipo `error`, se ocorrer algum erro.

  Alterado na versão 3.6: level pode agora ser usado como um palavra reservada nomeada.

  Alterado na versão 3.11: O parâmetro wbits agora está disponível para definir janelas de bits e tipo de compactação.

zlib.compressobj(level=Z_DEFAULT_COMPRESSION, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

  Retorna um objeto de compactação, a ser usado para compactar fluxos de dados que não cabem na memória de uma só vez.

  level é um nível de compactação – um inteiro de `0` a `9` ou `-1`. Consulte `Z_BEST_SPEED` (`1`), `Z_BEST_COMPRESSION` (`9`), `Z_NO_COMPRESSION` (`0`) e o padrão, `Z_DEFAULT_COMPRESSION` (`-1`) para obter mais informações sobre esses valores.

  method é o algoritmo de compactação. Atualmente, o único valor suportado é `DEFLATED`.

  O parâmetro wbits controla o tamanho do histórico buffer (ou o “tamanho da janela do buffer”) e qual o formato do cabeçalho e do trailer serão usados. Ele tem o mesmo significado que o descrito para compress().

  O argumento memLevel controla a quantidade de memória usada para o estado de compactação interno. Os valores válidos variam de `1` a `9`. Valores mais altos usam mais memória, mas são mais rápidos e produzem uma saída menor.

  strategy é usado para ajustar o algoritmo de compactação. Os valores possíveis são `Z_DEFAULT_STRATEGY`, `Z_FILTERED`, `Z_HUFFMAN_ONLY`, `Z_RLE` e `Z_FIXED`.

  zdict é um dicionário de compactação predefinido. Esta é uma sequência de bytes (como um objeto `bytes`) que contém subsequências que se espera que ocorram com frequência nos dados a serem compactados. As subsequências que se espera serem mais comuns devem aparecer no final do dicionário.

  Alterado na versão 3.3: Adicionado o suporte ao parâmetro e argumento nomeado zdict.

zlib.crc32(data[, value])

  Calcula uma soma de verificação CRC (Cyclic Redundancy Check) de data. O resultado é um número inteiro sem sinal de 32 bits. Se value estiver presente, ele será usado como o valor inicial da soma de verificação; caso contrário, um valor padrão de 1 é usado. A passagem de value permite calcular uma soma de verificação em execução através da concatenação de várias entradas. O algoritmo não é criptograficamente forte e não deve ser usado para autenticação ou assinaturas digitais. Como o algoritmo foi projetado para uso como um algoritmo de soma de verificação, não é adequado para uso como um algoritmo de hash geral.

  Alterado na versão 3.0: O resultado é sempre sem sinal.

zlib.crc32_combine(crc1, crc2, len2, /)

  Combine two CRC-32 checksums into one.

  Given the CRC-32 checksum crc1 of a sequence `A` and the CRC-32 checksum crc2 of a sequence `B` of length len2, return the CRC-32 checksum of `A` and `B` concatenated.

  This function is typically useful to combine CRC-32 checksums that were concurrently computed. To compute checksums sequentially, use `crc32()` with the running checksum as the `value` argument.

  Adicionado na versão 3.15.

zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

  Descompacta os bytes em data, retornando um objeto de bytes que contém os dados não compactados. O parâmetro wbits depende do formato de data e é discutido mais abaixo. Se bufsize for fornecido, ele será usado como o tamanho inicial do buffer de saída. Levanta a exceção `error` se ocorrer algum erro.

  O parâmetro wbits controla o tamanho do buffer do histórico (ou “tamanho da janela”) e qual formato de cabeçalho e sequência é esperado. É semelhante ao parâmetro para `compressobj()`, mas aceita mais intervalos de valores:

  - +8 a +15: O logaritmo de base dois do tamanho da janela. A entrada deve incluir um cabeçalho e uma sequência de zlib.

  - 0: Determina automaticamente o tamanho da janela no cabeçalho zlib. Suportado apenas desde o zlib 1.2.3.5.

  - −8 a −15: Usa o valor absoluto de wbits como o logaritmo do tamanho da janela. A entrada deve ser um fluxo bruto sem cabeçalho ou sequência.

  - +24 a +31 = 16 + (8 a 15): Usa os 4 bits baixos do valor como logaritmo do tamanho da janela. A entrada deve incluir um cabeçalho e sequência de gzip.

  - +40 a +47 = 32 + (8 a 15): Usa os 4 bits baixos do valor como logaritmo do tamanho da janela e aceita automaticamente o formato zlib ou gzip.

  Ao descompactar um fluxo, o tamanho da janela não deve ser menor que o tamanho originalmente usado para compactar o fluxo; o uso de um valor muito pequeno pode resultar em uma exceção `error`. O valor padrão wbits corresponde ao maior tamanho da janela e requer que um cabeçalho e uma sequência de zlib sejam incluídos.

  bufsize é o tamanho inicial do buffer usado para armazenar dados descompactados. Se for necessário mais espaço, o tamanho do buffer será aumentado conforme necessário, para que você não precise obter esse valor exatamente correto; sintonizando, apenas algumas chamadas serão salvas em `malloc()`.

  Alterado na versão 3.6: wbits e bufsize podem ser usados como argumentos nomeados.

zlib.decompressobj(wbits=MAX_WBITS[, zdict])

  Retorna um objeto descompactado, a ser usado para descompactar fluxos de dados que não cabem na memória de uma só vez.

  O parâmetro wbits controla o tamanho do histórico do buffer (ou o “tamanho da janela do buffer”) e qual formato do cabeçalho e trailer são esperados. Ele tem o mesmo significado que o descrito para decompress().

  O parâmetro zdict especifica uma dicionário predefinido de compactação. Se fornecido, deve ser o mesmo dicionário usado pelo compactador que produziu os dados a serem descompactados.

  Nota

  Se zdict for um objeto mutável (como um `bytearray`), você não deve modificar seu conteúdo entre a chamada de `decompressobj()` e a primeira chamada para o método de descompatação `decompress()`.

  Alterado na versão 3.3: Adicionado o parâmetro zdict.

Um objeto do tipo Compress oferece suporte aos seguintes métodos:

Compress.compress(data)

  Comprime data, retornando um objeto de bytes que contém dados compactados para pelo menos parte dos dados em data. Esses dados devem ser concatenados à saída produzida por quaisquer chamadas anteriores ao método `compress()`. Algumas entradas podem ser mantidas em buffers internos para processamento posterior.

Compress.flush([mode])

  Toda a entrada pendente é processada e um objeto de bytes contendo a saída compactada restante é retornado. O mode pode ser selecionado entre constantes `Z_NO_FLUSH` , `Z_PARTIAL_FLUSH`, `Z_SYNC_FLUSH`, `Z_FULL_FLUSH`, `Z_BLOCK` ou `Z_FINISH`, com o padrão sendo `Z_FINISH`. Exceto `Z_FINISH`, todas as demais constantes permitem a compactação de mais bytestrings de dados, enquanto `Z_FINISH` finaliza o fluxo compactado e impede a compactação de mais dados. Depois de chamar `flush()` com mode definido como `Z_FINISH`, o método `compress()` não pode ser chamado novamente; a única ação restante possível é excluir o objeto.

Compress.copy()

  Retorna uma cópia do objeto de compactação. Isso pode ser usado para compactar com eficiência um conjunto de dados que compartilham um prefixo inicial comum.

Alterado na versão 3.8: As funções `copy.copy()` e `copy.deepcopy()` foram adicionadas como suporte para a compactação de objetos.

Um objeto de descompactação oferece suporte aos seguintes métodos:

Decompress.unused_data

  Um objeto de bytes que contém todos os bytes após o final dos dados compactados. Ou seja, ele permanece `b""` até que o último byte que contém dados compactados esteja disponível. Se todo o bytestring contiver dados compactados, este será `b""`, um objeto de bytes vazio.

Decompress.unconsumed_tail

  Um objeto de bytes que contém todos os dados que não foram consumidos pela última chamada `decompress()` porque excederam o limite dos dados não compactados no buffer. Esses dados ainda não foram vistos pela zlib, portanto, você deve alimentá-los (possivelmente com outros dados concatenados a eles) em uma chamada subsequente para o método `decompress()` e, com isso, obter a saída correta.

Decompress.eof

  Um booleano indicando se o fim do fluxo de dados compactados foi alcançado.

  Isso permite distinguir entre um fluxo compactado formado corretamente e um fluxo incompleto ou truncado.

  Adicionado na versão 3.3.

Decompress.decompress(data, max_length=0)

  Descompacta data, retornando um objeto de bytes que contém os dados não compactados correspondentes a pelo menos uma parte dos dados em string. Esses dados devem ser concatenados com a saída produzida por quaisquer chamadas anteriores ao método `decompress()` . Alguns dos dados de entrada podem ser preservados em buffers internos para processamento posterior.

  If the optional parameter max_length is non-zero then the return value will be no longer than max_length. This may mean that not all of the compressed input can be processed; and unconsumed data will be stored in the attribute `unconsumed_tail`. This bytestring must be passed to a subsequent call to `decompress()` if decompression is to continue. If max_length is zero then the whole input is decompressed, and `unconsumed_tail` is empty. For example, the full content could be read like:

      process_output(d.decompress(data, max_length))
      while chunk := d.decompress(d.unconsumed_tail, max_length):
          process_output(chunk)

  Alterado na versão 3.6: max_length pode ser usado como argumento nomeado.

Decompress.flush([length])

  Toda a entrada que estiver pendente é processada e um objeto de bytes contendo a saída descompactada restante é retornado. Depois de chamar `flush()`, o método `decompress()` não pode ser chamado novamente; a única ação possível é excluir o objeto.

  O parâmetro opcional comprimento define o tamanho inicial da saída do buffer.

Decompress.copy()

  Retorna uma cópia do objeto de descompactação. Isso pode ser usado para salvar o estado do descompactador no meio do fluxo de dados, a fim de acelerar as buscas aleatórias no fluxo em um ponto futuro.

Alterado na versão 3.8: As funções `copy.copy()` e `copy.deepcopy()` foram adicionadas como suporte para a objetos de descompactação.

As constantes a seguir estão disponíveis para configurar o comportamento de compactação e descompactação:

zlib.DEFLATED

  O método de compactação de deflação.

zlib.MAX_WBITS

  O tamanho máximo da janela, expresso como uma potência de 2. Por exemplo, se `MAX_WBITS` for `15`, isso resultará em um tamanho de janela de `32 KiB`.

zlib.DEF_MEM_LEVEL

  O nível de memória padrão para objetos de compactação.

zlib.DEF_BUF_SIZE

  O tamanho padrão do buffer para operações de descompactação.

zlib.Z_NO_COMPRESSION

  Nível de compactação `0`; sem compactação.

  Adicionado na versão 3.6.

zlib.Z_BEST_SPEED

  Nível de compactação `1`; mais rápido e produz a menor compactação.

zlib.Z_BEST_COMPRESSION

  Nível de compactação `9`; mais lento e produz a maior compactação.

zlib.Z_DEFAULT_COMPRESSION

  Nível de compactação padrão (`-1`); um meio-termo entre velocidade e compactação. Atualmente equivalente ao nível de compactação `6`.

zlib.Z_DEFAULT_STRATEGY

  Estratégia de compactação padrão, para dados normais.

zlib.Z_FILTERED

  Estratégia de compactação para dados produzidos por um filtro (ou preditor).

zlib.Z_HUFFMAN_ONLY

  Estratégia de compactação que força codificação Huffman apenas.

zlib.Z_RLE

  Estratégia de compactação que limita distâncias de correspondência a um (codificação run-length).

  Esta constante só estará disponível se o Python foi construído com zlib 1.2.0.1 ou superior.

  Adicionado na versão 3.6.

zlib.Z_FIXED

  Estratégia de compactação que impede o uso de códigos dinâmicos de Huffman.

  Esta constante só estará disponível se o Python foi construído com zlib 1.2.2.2 ou superior.

  Adicionado na versão 3.6.

zlib.Z_NO_FLUSH

  Modo de saída `0`. Nenhum comportamento especial de saída.

  Adicionado na versão 3.6.

zlib.Z_PARTIAL_FLUSH

  Modo de saída `1`. Emite o máximo de saída possível.

zlib.Z_SYNC_FLUSH

  Modo de saída `2`. Toda saída é emitida e é alinhada a um limite de bytes.

zlib.Z_FULL_FLUSH

  Modo de saída `3`. Toda a saída é emitida e o estado de compactação é redefinido.

zlib.Z_FINISH

  Modo de saída `4`. Toda entrada pendente é processada, nenhuma outra entrada é esperada.

zlib.Z_BLOCK

  Modo de saída `5`. Um bloco de deflação é concluído e emitido.

  Esta constante só estará disponível se o Python foi construído com zlib 1.2.2.2 ou superior.

  Adicionado na versão 3.6.

zlib.Z_TREES

  Modo de saída `6`, para operações de inflação. Instrui a inflação a retornar ao atingir o próximo limite do bloco de desinflação.

  Esta constante está disponível apenas se o Python foi compilado com zlib 1.2.3.4 ou superior.

  Adicionado na versão 3.6.

As informações sobre o versão da biblioteca zlib em uso estão disponíveis no seguinte constantes:

zlib.ZLIB_VERSION

  Uma string com a versão da biblioteca zlib que foi usada para construir o módulo. Isso pode ser diferente da biblioteca zlib realmente usada no tempo de execução, que está disponível como `ZLIB_RUNTIME_VERSION`.

zlib.ZLIB_RUNTIME_VERSION

  Uma string com a versão da biblioteca zlib atualmente utilizada pelo interpretador.

  Adicionado na versão 3.3.

zlib.ZLIBNG_VERSION

  A string de versão da biblioteca zlib-ng que foi usada para construir o módulo, caso o zlib-ng tenha sido usado. Quando presentes, as constantes `ZLIB_VERSION` e `ZLIB_RUNTIME_VERSION` refletem a versão da API zlib fornecida pelo zlib-ng.

  Se zlib-ng não foi usado para construir o módulo, esta constante estará ausente.

  Adicionado na versão 3.14.

Ver também

módulo `gzip`

  Leia e escreva arquivos no formato gzip

https://www.zlib.net

  A página inicial da biblioteca zlib.

https://www.zlib.net/manual.html

  O manual da zlib explica a semântica e uso de diversas funções desta biblioteca.

Caso a (des)compactação do gzip seja um gargalo, o pacote python-isal acelera a (des)compactação com uma API quase sempre compatível.