# `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)

  Compress the data, returning a `bytes` object containing the compressed data. compresslevel and mtime have the same meaning as in the `GzipFile` constructor above.

  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.