"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

   An exception raised for invalid gzip files.  It inherits "OSError".
   "EOFError" and "zlib.error" can also be raised for invalid gzip
   files.

   Novo na versão 3.8.

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

   Constructor for the "GzipFile" class, which simulates most of the
   methods of a *file object*, with the exception of the "truncate()"
   method.  At least one of *fileobj* and *filename* must be given a
   non-trivial value.

   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.

   Calling a "GzipFile" object's "close()" method does not close
   *fileobj*, since you might wish to append more material after the
   compressed data.  This also allows you to pass an "io.BytesIO"
   object opened for writing as *fileobj*, and retrieve the resulting
   memory buffer using the "io.BytesIO" object's "getvalue()" method.

   "GzipFile" supports the "io.BufferedIOBase" interface, including
   iteration and the "with" statement.  Only the "truncate()" method
   isn't implemented.

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

   Compacta *data*, retornando um objeto "bytes" contendo os dados
   compactados. *compresslevel* e *mtime* têm o mesmo significado que
   no construtor de "GzipFile" acima.

   Novo na versão 3.2.

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

gzip.decompress(data)

   Decompress the *data*, returning a "bytes" object containing the
   uncompressed data.

   Novo na versão 3.2.


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

   If *file* is not specified, read from "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.
