"gzip" --- Support for **gzip** files
*************************************

**Código-fonte:** Lib/gzip.py

======================================================================

Esse módulo disponibiliza uma interface simples para comprimir e
extrair arquivos como os programas GNU **gzip** e **gunzip** fazem.

A compressão de dados é realizada pelo módulo "zlib".

O módulo "gzip" fornece a classe "GzipFile", bem como as funções de
conveniência "open()", "compress()" e "decompress()". A classe
"GzipFile" lê e grava arquivos no formato **gzip**, compactando ou
descompactando automaticamente os dados para que se pareçam com um
*objeto arquivo* comum.

Observe que formatos de arquivo adicionais que podem ser
descompactados pelos programas **gzip** e **gunzip**, como aqueles
produzidos por **compress** e **pack**, não são suportados por este
módulo.

Este módulo define os seguintes itens:

gzip.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

   Abre um arquivo comprimido com gzip em modo binário ou texto,
   retornando *objeto arquivo*.

   O argumento *filename* pode ser um nome de arquivo real (um objeto
   "str" ou "bytes"), ou um objeto arquivo existente para ler ou
   gravar.

   O argumento *mode* pode ser qualquer um de "'r'", "'rb'", "'a'",
   "'ab'", "'w'", "'wb'", "'x'" ou "'xb'" para modo binário, ou
   "'rt'", "'at'", "'wt'" ou "'xt'" para modo texto. O padrão é
   "'rb'".

   O argumento *compresslevel* é um inteiro de 0 a 9, como para o
   construtor de "GzipFile".

   Para o modo binário, esta função equivale ao construtor de
   "GzipFile": "GzipFile(filename, mode, compresslevel)". Neste caso,
   os argumentos *encoding*, *errors* e *newline* não devem ser
   fornecidos.

   Para o modo texto, um objeto "GzipFile" é criado e encapsulado em
   uma instância "io.TextIOWrapper" com a codificação especificada,
   comportamento de tratamento de erros e final(is) de linha.

   Alterado na versão 3.3: Adicionado suporte para *filename* ser um
   objeto arquivo, suporte para modo texto e os argumentos *encoding*,
   *errors* e *newline*.

   Alterado na versão 3.4: Adicionado suporte para os modos "'x'",
   "'xb'" e "'xt'".

   Alterado na versão 3.6: Aceita um *objeto caminho ou similar*.

exception gzip.BadGzipFile

   Uma exceção levantada para arquivos gzip inválidos. Herda de
   "OSError". "EOFError" e "zlib.error" também podem ser levantadas
   para arquivos gzip inválidos.

   Novo na versão 3.8.

class gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)

   Construtor para a classe "GzipFile", que simula a maioria dos
   métodos de um *objeto arquivo*, com exceção do método "truncate()".
   Pelo menos um dos métodos *fileobj* e *filename* deve receber um
   valor não trivial.

   A nova instância de classe é baseada em *fileobj*, que pode ser um
   arquivo comum, um objeto "io.BytesIO" ou qualquer outro objeto que
   simule um arquivo. O padrão é "None", caso em que *filename* é
   aberto para fornecer um objeto arquivo.

   Quando *fileobj* não é "None", o argumento *filename* é usado
   apenas para ser incluído no cabeçalho do arquivo **gzip**, que pode
   incluir o nome original do arquivo descompactado. O padrão é o nome
   de arquivo *fileobj*, se discernível; caso contrário, o padrão é a
   string vazia e, neste caso, o nome original do arquivo não é
   incluído no cabeçalho.

   O argumento *mode* pode ser qualquer um dos seguintes: "'r'",
   "'rb'", "'a'", "'ab'", "'w'", "'wb'", "'x'" ou "'xb'", dependendo
   se o arquivo será lido ou escrito. O padrão é o modo de *fileobj*,
   se discernível; caso contrário, o padrão é "'rb'". Em versões
   futuras do Python, o modo de *fileobj* não será usado. É melhor
   sempre especificar *mode* para escrita.

   Observe que o arquivo é sempre aberto em modo binário. Para abrir
   um arquivo compactado em modo texto, use "open()" (ou envolva seu
   "GzipFile" com um "io.TextIOWrapper").

   O argumento *compresslevel* é um inteiro de "0" a "9" que controla
   o nível de compressão; "1" é o mais rápido e produz a menor
   compressão, e "9" é o mais lento e produz a maior compressão. "0"
   significa sem compressão. O padrão é "9".

   The *mtime* argument is an optional numeric timestamp to be written
   to the last modification time field in the stream when compressing.
   It should only be provided in compression mode.  If omitted or
   "None", the current time is used.  See the "mtime" attribute for
   more details.

   Chamar o método "close()" de um objeto "GzipFile" não fecha
   *fileobj*, pois você pode querer adicionar mais material após os
   dados compactados. Isso também permite que você passe um objeto
   "io.BytesIO" aberto para escrita como *fileobj* e recupere o buffer
   de memória resultante usando o método "getvalue()" do objeto
   "io.BytesIO".

   "GzipFile" suporta a interface "io.BufferedIOBase", incluindo
   iteração e a instrução "with". Apenas o método "truncate()" não é
   implementado.

   "GzipFile" também disponibiliza os seguintes métodos e atributos:

   peek(n)

      Read *n* uncompressed bytes without advancing the file position.
      At most one single read on the compressed stream is done to
      satisfy the call.  The number of bytes returned may be more or
      less than requested.

      Nota:

        Embora chamar "peek()" não altere a posição do arquivo
        "GzipFile", ele pode alterar a posição do objeto arquivo
        subjacente (por exemplo, se o "GzipFile" foi construído com o
        parâmetro *fileobj*).

      Novo na versão 3.2.

   mtime

      When decompressing, the value of the last modification time
      field in the most recently read header may be read from this
      attribute, as an integer.  The initial value before reading any
      headers is "None".

      All **gzip** compressed streams are required to contain this
      timestamp field.  Some programs, such as **gunzip**, make use of
      the timestamp.  The format is the same as the return value of
      "time.time()" and the "st_mtime" attribute of the object
      returned by "os.stat()".

   name

      O caminho para o arquivo gzip no disco, como "str" ou "bytes".
      Equivalente à saída de "os.fspath()" no caminho de entrada
      original, sem nenhuma outra normalização, resolução ou expansão.

   Alterado na versão 3.1: Foi adicionado suporte para a instrução
   "with", juntamente com o argumento do construtor *mtime* e o
   atributo "mtime".

   Alterado na versão 3.2: Foi adicionado suporte para arquivos
   preenchidos com zeros e não pesquisáveis.

   Alterado na versão 3.3: O método "io.BufferedIOBase.read1()" agora
   está implementado.

   Alterado na versão 3.4: Adicionado suporte para os modos "'x'" e
   "'xb'".

   Alterado na versão 3.5: Adicionado suporte para escrever *objetos
   bytes ou similares* arbitrários. O método "read()" agora aceita o
   argumento "None".

   Alterado na versão 3.6: Aceita um *objeto caminho ou similar*.

   Obsoleto desde a versão 3.9: Abrir "GzipFile" para escrita sem
   especificar o argumento *mode* está descontinuado.

gzip.compress(data, compresslevel=9, *, mtime=None)

   Compress the *data*, returning a "bytes" object containing the
   compressed data.  *compresslevel* and *mtime* have the same meaning
   as in the "GzipFile" constructor above. When *mtime* is set to "0",
   this function is equivalent to "zlib.compress()" with *wbits* set
   to "31". The zlib function is faster.

   Novo na versão 3.2.

   Alterado na versão 3.8: Adicionado o parâmetro *mtime* para saída
   reproduzível.

   Alterado na versão 3.11: A velocidade é melhorada pela compactação
   de todos os dados de uma só vez, em vez de em fluxo contínuo.
   Chamadas com *mtime* definido como "0" são delegadas a
   "zlib.compress()" para maior velocidade. Nessa situação, a saída
   pode conter um valor de byte "OS" no cabeçalho gzip diferente de
   255 "unknown", conforme fornecido pela implementação subjacente do
   zlib.

gzip.decompress(data)

   Descompacta *data*, retornando um objeto "bytes" contendo os dados
   descompactados. Esta função é capaz de descompactar dados de gzip
   de vários membros (vários blocos gzip concatenados). Quando é certo
   que os dados contêm apenas um membro, a função "zlib.decompress()"
   com *wbits* definido como 31 é mais rápida.

   Novo na versão 3.2.

   Alterado na versão 3.11: A velocidade é melhorada ao descompactar
   os membros de uma só vez na memória, em vez de fazê-lo de forma
   contínua.


Exemplos de uso
===============

Exemplo de como ler um arquivo comprimido:

   import gzip
   with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
       file_content = f.read()

Exemplo de como criar um arquivo comprimido com GZIP:

   import gzip
   content = b"Lots of content here"
   with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
       f.write(content)

Exemplo de como comprimir um arquivo existente com GZIP:

   import gzip
   import shutil
   with open('/home/joe/file.txt', 'rb') as f_in:
       with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:
           shutil.copyfileobj(f_in, f_out)

Exemplo de como comprimir uma string binária com compressão GZIP:

   import gzip
   s_in = b"Lots of content here"
   s_out = gzip.compress(s_in)

Ver também:

  Módulo "zlib"
     O módulo básico de compactação de dados necessário para dar
     suporte ao formato de arquivo do **gzip**.


Interface de linha de comando
=============================

O módulo "gzip" fornece uma interface de linha de comando simples para
compactar ou descompactar arquivos.

Uma vez executado, o módulo "gzip" mantém o(s) arquivo(s) de entrada.

Alterado na versão 3.8: Adiciona uma nova interface de linha de
comando com um mensagem de uso. Por padrão, ao executar a CLI, o nível
de compactação padrão é 6.


Opções da linha de comando
--------------------------

file

   Se o *arquivo* não for especificado, ler de "sys.stdin"

--fast

   Indica o método mais rápido de compressão (menor compressão)

--best

   Indica o método mais lento de compressão (melhor compressão).

-d, --decompress

   Descompacta o arquivo dado.

-h, --help

   Exibe a mensagem de ajuda.
