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