gzip no Python: comprima arquivos .gz

O módulo gzip no Python permite ler e gravar arquivos no formato GZIP usando uma interface semelhante à de arquivos comuns. Ele usa o algoritmo DEFLATE fornecido pelo módulo zlib e oferece funções para dados em memória, a classe GzipFile e suporte a texto com codificação explícita.

GZIP é amplamente aceito por servidores web, ferramentas Unix, pipelines de dados e formatos de distribuição. Ele comprime um fluxo por vez, ao contrário de ZIP, que também funciona como contêiner de vários caminhos. Para diretórios completos, normalmente você combina TAR e GZIP.

Quando usar gzip

Use GZIP para logs, JSON Lines, CSV, respostas HTTP, backups de um único fluxo e interoperabilidade com gzip e gunzip. Se precisar manipular o DEFLATE diretamente, veja zlib no Python. Para maior taxa de compressão e maior custo, compare com lzma no Python.

Comprima bytes de uma vez

import gzip

dados = ("registro de acesso\n" * 2000).encode("utf-8")
compactado = gzip.compress(dados, compresslevel=6)
restaurado = gzip.decompress(compactado)

assert restaurado == dados
print(len(dados), len(compactado))

gzip.compress() mantém tudo em memória. No Python 3.14, mtime é zero por padrão, produzindo saída reproduzível. Para incluir o horário atual no cabeçalho, passe mtime=None.

Saída reproduzível

Dois builds com o mesmo conteúdo devem produzir os mesmos bytes quando artefatos são comparados por hash. O timestamp do cabeçalho quebrava essa propriedade. Agora, a função de conveniência favorece reprodutibilidade:

import gzip
import hashlib

resultado = gzip.compress(b"versao=1\n", mtime=0)
print(hashlib.sha256(resultado).hexdigest())

Ao usar GzipFile, informe mtime=0 manualmente quando esse requisito existir.

Grave texto compactado

import gzip

with gzip.open("eventos.log.gz", "wt", encoding="utf-8", compresslevel=6) as arquivo:
    arquivo.write("serviço iniciado\n")
    arquivo.write("tarefa concluída\n")

Os modos wt, at e xt criam um wrapper de texto. Use xt para impedir sobrescrita. Defina a codificação; não dependa do padrão da máquina.

Leia linha por linha

import gzip

with gzip.open("eventos.log.gz", "rt", encoding="utf-8") as arquivo:
    for numero, linha in enumerate(arquivo, 1):
        processar(numero, linha.rstrip())

A iteração evita materializar o texto inteiro. Ela combina com as práticas de leitura de arquivos gigantes. Ainda assim, estabeleça limites para quantidade de linhas e tamanho descompactado.

Compacte um arquivo existente

shutil.copyfileobj() transfere em blocos entre os objetos:

import gzip
import shutil

with open("dados.csv", "rb") as origem:
    with gzip.open("dados.csv.gz", "wb", compresslevel=6) as destino:
        shutil.copyfileobj(origem, destino, length=1024 * 1024)

O argumento length controla o tamanho dos blocos. Grave primeiro em um arquivo temporário e renomeie ao final quando leitores não puderem encontrar um resultado parcial.

Use GzipFile com BytesIO

GzipFile aceita um fileobj, útil para buffers, sockets e camadas de armazenamento:

import gzip
import io

buffer = io.BytesIO()
with gzip.GzipFile(fileobj=buffer, mode="wb", compresslevel=6, mtime=0) as gz:
    gz.write(b"conteudo" * 1000)

payload = buffer.getvalue()

Fechar GzipFile não fecha o fileobj. Isso permite chamar getvalue() ou acrescentar outros dados ao buffer.

Cabeçalho e nome original

O cabeçalho pode carregar timestamp e nome original. Quando fileobj é fornecido, o argumento filename serve apenas para o cabeçalho. Evite inserir caminhos sensíveis, nomes de usuário ou estrutura interna da aplicação.

Vários membros concatenados

gzip.decompress() consegue descomprimir vários membros GZIP concatenados. O modo append cria um novo membro ao final do arquivo. Isso é válido, mas nem todo consumidor externo apresenta os membros da mesma forma. Teste interoperabilidade antes de depender desse comportamento.

Erros possíveis

Um arquivo inválido pode gerar gzip.BadGzipFile, EOFError ou zlib.error. Capture apenas as exceções que você consegue tratar e registre contexto seguro.

import gzip
import zlib

try:
    with gzip.open("entrada.gz", "rb") as arquivo:
        dados = arquivo.read()
except (gzip.BadGzipFile, EOFError, zlib.error) as erro:
    raise ValueError("arquivo GZIP inválido") from erro

Evite expansão sem limite

gzip.decompress() devolve a saída inteira e não oferece um limite total. Não use a função diretamente em uploads grandes ou não confiáveis. Prefira GzipFile.read(tamanho) em loop e conte os bytes produzidos:

import gzip

limite = 100 * 1024 * 1024
total = 0

with gzip.open("upload.gz", "rb") as arquivo:
    while bloco := arquivo.read(64 * 1024):
        total += len(bloco)
        if total > limite:
            raise ValueError("conteúdo expandido excedeu o limite")
        consumir(bloco)

Também limite o tamanho comprimido, tempo de CPU e quantidade de membros. Compressão não valida semântica nem autentica origem.

Níveis de compressão

• 0: armazena sem compressão.
• 1: mais rápido, arquivo maior.
• 6: equilíbrio comum e padrão da CLI.
• 9: mais lento, melhor tentativa de reduzir tamanho.

Arquivos já compactados, como vídeos e JPEG, quase não melhoram. Meça tempo e tamanho em dados reais.

GZIP não é um arquivo de diretório

GZIP representa um fluxo. Para juntar vários arquivos com permissões, nomes e diretórios, use TAR e depois comprima o resultado. ZIP reúne contêiner e compressão; veja como criar ZIP com Python.

Interface de linha de comando

O módulo pode ser executado com python -m gzip. Ele mantém o arquivo de entrada e aceita --fast, --best e --decompress. Para automações complexas, a API fornece melhor controle de caminhos, erros e escrita atômica.

Testes recomendados

Teste ida e volta, arquivo vazio, Unicode, entrada truncada, membros concatenados, níveis 0, 1, 6 e 9, cabeçalho reproduzível e limite de expansão.

import gzip

def test_gzip_reproduzivel():
    a = gzip.compress(b"abc", mtime=0)
    b = gzip.compress(b"abc", mtime=0)
    assert a == b
    assert gzip.decompress(a) == b"abc"

Boas práticas

• Use with.
• Especifique modo e codificação.
• Use mtime=0 para builds reproduzíveis.
• Grave de forma atômica.
• Limite entrada, saída, membros e CPU.
• Não exponha nomes internos no cabeçalho.
• Teste interoperabilidade.
• Não trate CRC como autenticação.

Conclusão

O gzip no Python é uma opção prática para fluxos compactados amplamente compatíveis. Ele atende dados em memória, arquivos, texto e buffers, e o padrão reproduzível do Python 3.14 facilita pipelines de build.

Consulte a documentação oficial do gzip e a especificação RFC 1952. Para configurar níveis por ambiente, veja configparser no Python.