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.

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.