tzst/README.pt.md at 5774eddbbb00706aebe8bcc400aa02c8fbb3d0e2

xixu-me/tzst

0 Fork 0

Files

T

xixu-me 5774eddbbb docs(readme): align multilingual readmes

2026-04-11 21:59:25 +08:00

15 KiB

Raw Blame History

tzst é uma biblioteca e CLI para Python 3.12+ voltada para criar, extrair, listar e validar arquivos .tzst e .tar.zst. Ela combina compatibilidade com tar, compressão Zstandard, modo streaming, gravações atômicas e extração segura por padrão em uma interface compacta pronta para produção.

Note

Artigo técnico detalhado: Deep Dive into tzst: A Modern Python Archiving Library Based on Zstandard.

Recursos

Alta Compressão: Compressão Zstandard para excelentes taxas de compressão e velocidade
Compatibilidade com Tar: Cria arquivos tar padrão comprimidos com Zstandard
Interface de Linha de Comando: CLI intuitiva com suporte a streaming e opções abrangentes
API Python: API limpa e pythônica para uso programático
Multiplataforma: Funciona no Windows, macOS e Linux
Múltiplas Extensões: Suporta tanto extensões .tzst quanto .tar.zst
Eficiente em Memória: Modo streaming para lidar com grandes arquivos com uso mínimo de memória
Operações Atômicas: Operações de arquivo seguras com limpeza automática em caso de interrupção
Seguro por Padrão: Usa o filtro 'data' para máxima segurança durante a extração
Tratamento de Erros Aprimorado: Mensagens de erro claras com alternativas úteis

Instalação

Dos Releases do GitHub

Baixe executáveis independentes que não requerem instalação do Python:

Plataformas Suportadas

Plataforma	Arquitetura	Arquivo
Linux	x86_64	`tzst-{versão}-linux-amd64.zip`
Linux	ARM64	`tzst-{versão}-linux-arm64.zip`
Windows	x64	`tzst-{versão}-windows-amd64.zip`
Windows	ARM64	`tzst-{versão}-windows-arm64.zip`
macOS	Intel	`tzst-{versão}-darwin-amd64.zip`
macOS	Apple Silicon	`tzst-{versão}-darwin-arm64.zip`

Passos de Instalação

Baixe o arquivo apropriado para sua plataforma da página de releases mais recentes
Extraia o arquivo para obter o executável tzst (ou tzst.exe no Windows)
Mova o executável para um diretório em seu PATH:
- Linux/macOS: sudo mv tzst /usr/local/bin/
- Windows: Adicione o diretório contendo tzst.exe à sua variável de ambiente PATH
Verifique a instalação: tzst --help

Benefícios da Instalação Binária

Python não é necessário - Executável independente
Inicialização mais rápida - Sem overhead do interpretador Python
Implantação fácil - Distribuição de arquivo único
Comportamento consistente - Dependências incluídas

Do PyPI

Usando pip:

pip install tzst

Ou usando uv (recomendado):

uv tool install tzst

Do Código Fonte

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install .

Instalação para Desenvolvimento

Este projeto usa padrões modernos de empacotamento Python:

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install -e .[dev]

Início Rápido

Uso da Linha de Comando

# Criar um arquivo
tzst a archive.tzst file1.txt file2.txt directory/

# Extrair um arquivo
tzst x archive.tzst

# Listar conteúdo do arquivo
tzst l archive.tzst

# Testar integridade do arquivo
tzst t archive.tzst

Uso da API Python

from tzst import create_archive, extract_archive, list_archive

# Criar um arquivo
create_archive("archive.tzst", ["file1.txt", "file2.txt", "directory/"])

# Extrair um arquivo
extract_archive("archive.tzst", "output_directory/")

# Listar conteúdo do arquivo
contents = list_archive("archive.tzst", verbose=True)
for item in contents:
    print(f"{item['name']}: {item['size']} bytes")

Interface de Linha de Comando

Operações de Arquivo

Criar Arquivo

# Uso básico
tzst a archive.tzst file1.txt file2.txt

# Com nível de compressão (1-22, padrão: 3)
tzst a archive.tzst files/ -l 15

# Comandos alternativos
tzst add archive.tzst files/
tzst create archive.tzst files/

Extrair Arquivo

# Extrair com estrutura completa de diretórios
tzst x archive.tzst

# Extrair para diretório específico
tzst x archive.tzst -o output/

# Extrair arquivos específicos
tzst x archive.tzst file1.txt dir/file2.txt

# Extrair sem estrutura de diretórios (plano)
tzst e archive.tzst -o output/

# Usar modo streaming para grandes arquivos
tzst x archive.tzst --streaming -o output/

Listar Conteúdo

# Listagem simples
tzst l archive.tzst

# Listagem detalhada com informações
tzst l archive.tzst -v

# Usar modo streaming para grandes arquivos
tzst l archive.tzst --streaming -v

Testar Integridade

# Testar integridade do arquivo
tzst t archive.tzst

# Testar com modo streaming
tzst t archive.tzst --streaming

Referência de Comandos

Comando	Aliases	Descrição	Suporte a Streaming
`a`	`add`, `create`	Criar ou adicionar ao arquivo	N/A
`x`	`extract`	Extrair com caminhos completos	✓ `--streaming`
`e`	`extract-flat`	Extrair sem estrutura de diretórios	✓ `--streaming`
`l`	`list`	Listar conteúdo do arquivo	✓ `--streaming`
`t`	`test`	Testar integridade do arquivo	✓ `--streaming`

Opções da CLI

-v, --verbose: Ativar saída detalhada
-o, --output DIR: Especificar diretório de saída (comandos de extração)
-l, --level LEVEL: Definir nível de compressão 1-22 (comando de criação)
--streaming: Ativar modo streaming para processamento eficiente em memória
--filter FILTER: Filtro de segurança para extração (data/tar/fully_trusted)
--no-atomic: Desativar operações de arquivo atômicas (não recomendado)

Filtros de Segurança

# Extrair com máxima segurança (padrão)
tzst x archive.tzst --filter data

# Extrair com compatibilidade tar padrão
tzst x archive.tzst --filter tar

# Extrair com confiança total (perigoso - apenas para arquivos confiáveis)
tzst x archive.tzst --filter fully_trusted

Opções de Filtro de Segurança:

data (padrão): Mais seguro. Bloqueia arquivos perigosos, caminhos absolutos e caminhos fora do diretório de extração
tar: Compatibilidade tar padrão. Bloqueia caminhos absolutos e travessia de diretórios
fully_trusted: Sem restrições de segurança. Use apenas com arquivos completamente confiáveis

API Python

Classe TzstArchive

from tzst import TzstArchive

# Criar um novo arquivo
with TzstArchive("archive.tzst", "w", compression_level=5) as archive:
    archive.add("file.txt")
    archive.add("directory/", recursive=True)

# Ler um arquivo existente
with TzstArchive("archive.tzst", "r") as archive:
    # Listar conteúdo
    contents = archive.list(verbose=True)
    
    # Extrair com filtro de segurança
    archive.extract("file.txt", "output/", filter="data")
    
    # Testar integridade
    is_valid = archive.test()

# Para grandes arquivos, usar modo streaming
with TzstArchive("large_archive.tzst", "r", streaming=True) as archive:
    archive.extract(path="output/")

Limitações Importantes:

Modo de anexação não suportado: Crie múltiplos arquivos ou recrie o arquivo inteiro em vez disso

Funções de Conveniência

create_archive()

from tzst import create_archive

# Criar com operações atômicas (padrão)
create_archive(
    archive_path="backup.tzst",
    files=["documents/", "photos/", "config.txt"],
    compression_level=10
)

extract_archive()

from tzst import extract_archive

# Extrair com segurança (padrão: filtro 'data')
extract_archive("backup.tzst", "restore/")

# Extrair arquivos específicos
extract_archive("backup.tzst", "restore/", members=["config.txt"])

# Achatar estrutura de diretórios
extract_archive("backup.tzst", "restore/", flatten=True)

# Usar streaming para grandes arquivos
extract_archive("large_backup.tzst", "restore/", streaming=True)

list_archive()

from tzst import list_archive

# Listagem simples
files = list_archive("backup.tzst")

# Listagem detalhada
files = list_archive("backup.tzst", verbose=True)

# Streaming para grandes arquivos
files = list_archive("large_backup.tzst", streaming=True)

test_archive()

from tzst import test_archive

# Teste básico de integridade
if test_archive("backup.tzst"):
    print("Arquivo é válido")

# Testar com streaming
if test_archive("large_backup.tzst", streaming=True):
    print("Grande arquivo é válido")

Recursos Avançados

Extensões de Arquivo

A biblioteca automaticamente lida com extensões de arquivo com normalização inteligente:

.tzst - Extensão primária para arquivos tar+zstandard
.tar.zst - Extensão padrão alternativa
Detecção automática ao abrir arquivos existentes
Adição automática de extensão ao criar arquivos

# Todos estes criam arquivos válidos
create_archive("backup.tzst", files)      # Cria backup.tzst
create_archive("backup.tar.zst", files)  # Cria backup.tar.zst  
create_archive("backup", files)          # Cria backup.tzst
create_archive("backup.txt", files)      # Cria backup.tzst (normalizado)

Níveis de Compressão

Os níveis de compressão Zstandard variam de 1 (mais rápido) a 22 (melhor compressão):

Nível 1-3: Compressão rápida, arquivos maiores
Nível 3 (padrão): Bom equilíbrio entre velocidade e compressão
Nível 10-15: Melhor compressão, mais lento
Nível 20-22: Compressão máxima, muito mais lento

Modo Streaming

Use o modo streaming para processamento eficiente em memória de grandes arquivos:

Benefícios:

Uso de memória significativamente reduzido
Melhor desempenho para arquivos que não cabem na memória
Limpeza automática de recursos

Quando usar:

Arquivos maiores que 100MB
Ambientes com memória limitada
Processamento de arquivos com muitos arquivos grandes

# Exemplo: Processando um grande arquivo de backup
from tzst import extract_archive, list_archive, test_archive

large_archive = "backup_500gb.tzst"

# Operações eficientes em memória
is_valid = test_archive(large_archive, streaming=True)
contents = list_archive(large_archive, streaming=True, verbose=True)
extract_archive(large_archive, "restore/", streaming=True)

Operações Atômicas

Todas as operações de criação de arquivo usam operações de arquivo atômicas por padrão:

Arquivos criados em arquivos temporários primeiro, depois movidos atomicamente
Limpeza automática se o processo for interrompido
Nenhum risco de arquivos corrompidos ou incompletos
Compatibilidade multiplataforma

# Operações atômicas habilitadas por padrão
create_archive("important.tzst", files)  # Seguro contra interrupção

# Pode ser desabilitado se necessário (não recomendado)
create_archive("test.tzst", files, use_temp_file=False)

Tratamento de Erros

from tzst import TzstArchive
from tzst.exceptions import (
    TzstError,
    TzstArchiveError,
    TzstCompressionError,
    TzstDecompressionError,
    TzstFileNotFoundError
)

try:
    with TzstArchive("archive.tzst", "r") as archive:
        archive.extract()
except TzstDecompressionError:
    print("Falha ao descomprimir arquivo")
except TzstFileNotFoundError:
    print("Arquivo de arquivo não encontrado")
except KeyboardInterrupt:
    print("Operação interrompida pelo usuário")
    # Limpeza é tratada automaticamente

Desempenho e Comparação

Dicas de Desempenho

Níveis de compressão: Nível 3 é ótimo para a maioria dos casos de uso
Streaming: Use para arquivos maiores que 100MB
Operações em lote: Adicione múltiplos arquivos em uma única sessão
Tipos de arquivo: Arquivos já comprimidos não comprimirão muito mais

vs Outras Ferramentas

vs tar + gzip:

Melhores taxas de compressão
Descompressão mais rápida
Algoritmo moderno

vs tar + xz:

Compressão significativamente mais rápida
Taxas de compressão similares
Melhor compromisso velocidade/compressão

vs zip:

Melhor compressão
Preserva permissões Unix e metadados
Melhor suporte a streaming

Requisitos

Python 3.12 ou superior
zstandard >= 0.19.0

Desenvolvimento

Configurando Ambiente de Desenvolvimento