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.

zlib’s functions have many options and often need to be used in a particular order. This documentation doesn’t attempt to cover all of the permutations; consult the zlib manual for authoritative information.

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.

The following constants are available to configure compression and decompression behavior:

zlib.DEFLATED

The deflate compression method.

zlib.MAX_WBITS

The maximum window size, expressed as a power of 2. For example, if MAX_WBITS is 15 it results in a window size of 32 KiB.

zlib.DEF_MEM_LEVEL

The default memory level for compression objects.

zlib.DEF_BUF_SIZE

The default buffer size for decompression operations.

zlib.Z_NO_COMPRESSION

Compression level 0.

Adicionado na versão 3.6.

zlib.Z_BEST_SPEED

Compression level 1.

zlib.Z_BEST_COMPRESSION

Compression level 9.

zlib.Z_DEFAULT_COMPRESSION

Default compression level (-1).

zlib.Z_DEFAULT_STRATEGY

Default compression strategy, for normal data.

zlib.Z_FILTERED

Compression strategy for data produced by a filter (or predictor).

zlib.Z_HUFFMAN_ONLY

Compression strategy that forces Huffman coding only.

zlib.Z_RLE

Compression strategy that limits match distances to one (run-length encoding).

This constant is only available if Python was compiled with zlib 1.2.0.1 or greater.

Adicionado na versão 3.6.

zlib.Z_FIXED

Compression strategy that prevents the use of dynamic Huffman codes.

This constant is only available if Python was compiled with zlib 1.2.2.2 or greater.

Adicionado na versão 3.6.

zlib.Z_NO_FLUSH

Flush mode 0. No special flushing behavior.

Adicionado na versão 3.6.

zlib.Z_PARTIAL_FLUSH

Flush mode 1. Flush as much output as possible.

zlib.Z_SYNC_FLUSH

Flush mode 2. All output is flushed and the output is aligned to a byte boundary.

zlib.Z_FULL_FLUSH

Flush mode 3. All output is flushed and the compression state is reset.

zlib.Z_FINISH

Flush mode 4. All pending input is processed, no more input is expected.

zlib.Z_BLOCK

Flush mode 5. A deflate block is completed and emitted.

This constant is only available if Python was compiled with zlib 1.2.2.2 or greater.

Adicionado na versão 3.6.

zlib.Z_TREES

Flush mode 6, for inflate operations. Instructs inflate to return when it gets to the next deflate block boundary.

This constant is only available if Python was compiled with zlib 1.2.3.4 or greater.

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)compressão do gzip seja um gargalo, o pacote python-isal acelera a (des)compressão com uma API quase sempre compatível.