tzst/README.pt.md at d82f82bd5d2deaf65a24bf41e697b86a1a2d8659

xixu-me/tzst

0 Fork 0

Files

T

xixu-me d82f82bd5d Update install instructions and remove CLI notes

Added uv as a recommended installation method alongside pip in all README translations. Removed the note about downloading standalone binaries and using uvx for command line usage for brevity and consistency.

2025-11-05 12:24:19 +08:00

16 KiB

Raw Blame History

tzst é uma biblioteca Python de próxima geração projetada para gerenciamento moderno de arquivos, aproveitando a compressão Zstandard de ponta para oferecer desempenho, segurança e confiabilidade superiores. Construída exclusivamente para Python 3.12+, esta solução corporativa combina operações atômicas, eficiência de streaming e uma API meticulosamente elaborada para redefinir como os desenvolvedores lidam com arquivos .tzst/.tar.zst em ambientes de produção. 🚀

✨ 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