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

Para aplicações que exigem compactação de dados, as funções deste módulo permitem a compactação e a descompactação, usando a biblioteca zlib. A biblioteca zlib tem sua própria página em https://www.zlib.net. Existem algumas incompatibilidades conhecidas entre o Python módulo e as versões da biblioteca zlib anteriores à 1.1.3; a 1.1.3 tem uma vulnerabilidade de segurança, portanto, recomendamos o uso da 1.1.4 ou posterior.

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 em http://www.zlib.net/manual.html 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.compress(data, /, level=-1, wbits=MAX_WBITS)

  Comprime os bytes em data, retornando um objeto de bytes que contém dados comprimidos. level é um inteiro de `0` a `9` ou `-1` que controla o nível de compressão; `1` (Z_BEST_SPEED) é o mais rápido e produz a menor compressão, `9` (Z_BEST_COMPRESSION) é o mais lento e produz a maior. `0` (Z_NO_COMPRESSION) não produz compactação. O valor padrão é `-1` (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION representa um meio termo entre velocidade e compressão (atualmente equivale ao nível 6).

  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=-1, 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 é o nível de compactação – um número inteiro de `0` a `9` ou `-1`. Um valor de `1` (Z_BEST_SPEED) é mais rápido e produz a menor compactação, enquanto um valor de `9` (Z_BEST_COMPRESSION) é mais lento e produz o máximo. `0` (Z_NO_COMPRESSION) é nenhuma compactação. O valor padrão é `-1` (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION representa um meio termo padrão entre velocidade e compactação (atualmente equivalente ao nível 6).

  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` (zlib 1.2.0.1) e `Z_FIXED` (zlib 1.2.2.2).

  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.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 pre-definido de compressão. Se fornecido, deve ser o mesmo dicionário usado pelo compressor 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` (zlib 1.2.3.4) 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 compressão de objetos.

Um objeto do tipo Decompress 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.

  Se o parâmetro opcional max_length for diferente de zero, o valor retornado não será maior que max_length. Isso pode significar que nem toda a entrada compactada poderá ser processada, e os dados não consumidos serão armazenados no atributo `unconsumed_tail` . Esse bytestring deve ser passado para uma chamada subsequente a `decompress()` se a descompressão tiver que continuar. Se max_length for zero, toda a entrada será descompactada e `unconsumed_tail` ficará vazio.

  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 descompressão. Isso pode ser usado para salvar o estado do descompressor 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 descompressão de objetos.

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

http://www.zlib.net

  A página inicial da biblioteca zlib.

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

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

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