# `gzip` — Suporte para arquivos gzip

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.

Este é um módulo opcional. Se ele estiver faltando na sua cópia do CPython, procure a documentação do seu distribuidor (ou seja, quem lhe forneceu o Python). Se você for o distribuidor, consulte Requisitos para módulos opcionais.

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.

  Adicionado 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`.

  O argumento opcional mtime é o registro de data e hora solicitado pelo gzip. O horário está no formato Unix, ou seja, segundos desde 00:00:00 UTC, 1º de janeiro de 1970. Se mtime for omitido ou definido como `None`, o horário atual será usado. Use mtime = 0 para gerar um fluxo compactado que não depende do horário de criação.

  Veja abaixo o atributo `mtime` que é definido durante a descompactação.

  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)

    Lê n bytes não compactados sem avançar a posição do arquivo. O número de bytes retornados pode ser maior ou menor que o solicitado.

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

    Adicionado na versão 3.2.

  mode

    `'rb'` para leitura e `'wb'` para escrita.

    Alterado na versão 3.13: Em versões anteriores era um inteiro `1` ou `2`.

  mtime

    Ao descompactar, este atributo é definido como o último registro de data e hora no cabeçalho lido mais recentemente. É um inteiro que contém o número de segundos desde a era Unix (00:00:00 UTC, 1º de janeiro de 1970). O valor inicial antes da leitura de qualquer cabeçalho é `None`.

  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.

  Descontinuado desde a versão 3.9: Abrir `GzipFile` para escrita sem especificar o argumento mode está descontinuado.

  Alterado na versão 3.12: Remove o atributo `filename` e usa o atributo `name`.

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

  Compacta data, retornando um objeto `bytes` contendo os dados compactados. compresslevel e mtime têm o mesmo significado que no construtor de `GzipFile` acima, mas mtime assume o valor padrão 0 para uma saída reprodutível.

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

  Alterado na versão 3.13: O byte do cabeçalho gzip do sistema operacional tem a garantia de ser definido como 255 quando esta função é usada, como era o caso na versão 3.10 e anteriores.

  Alterado na versão 3.14: O parâmetro mtime agora assume o valor padrão 0 para uma saída reprodutível. Para o comportamento anterior de usar a hora atual, passe `None` para mtime.

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.

  Adicionado 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/arquivo.txt.gz', 'rb') as f:
        file_content = f.read()

Exemplo de como criar um arquivo comprimido com GZIP:

    import gzip
    content = b"Muito conteúdo aqui"
    with gzip.open('/home/joe/arquivo.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/arquivo.txt', 'rb') as f_in:
        with gzip.open('/home/joe/arquivo.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"Muito conteúdo aqui"
    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.

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.

## 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 de 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.