tzst/README.de.md at 2e8e99a200854bdd2e938d0c6fb10ad771cdf786

xixu-me/tzst

0 Fork 0

Files

T

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

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

16 KiB

Raw Blame History

tzst ist eine Python-3.12+-Bibliothek mit CLI zum Erstellen, Extrahieren, Auflisten und Prüfen von .tzst- und .tar.zst-Archiven. Sie bündelt tar-Kompatibilität, Zstandard-Komprimierung, Streaming, atomare Schreibvorgänge und standardmäßig sicheres Extrahieren in einer kompakten, produktionsreifen Oberfläche.

Note

Ausführlicher technischer Artikel: Deep Dive into tzst: A Modern Python Archiving Library Based on Zstandard.

Funktionen

Hohe Komprimierung: Zstandard-Komprimierung für ausgezeichnete Komprimierungsraten und Geschwindigkeit
Tar-Kompatibilität: Erstellt Standard-Tar-Archive, komprimiert mit Zstandard
Kommandozeilenschnittstelle: Intuitive CLI mit Streaming-Unterstützung und umfassenden Optionen
Python API: Saubere, pythonische API für programmatische Nutzung
Plattformübergreifend: Funktioniert auf Windows, macOS und Linux
Mehrere Erweiterungen: Unterstützt sowohl .tzst als auch .tar.zst Erweiterungen
Speichereffizient: Streaming-Modus für die Behandlung großer Archive mit minimalem Speicherverbrauch
Atomare Operationen: Sichere Dateioperationen mit automatischer Bereinigung bei Unterbrechung
Standardmäßig sicher: Verwendet den 'data' Filter für maximale Sicherheit beim Extrahieren
Verbesserte Fehlerbehandlung: Klare Fehlermeldungen mit hilfreichen Alternativen

Installation

Von GitHub Releases

Lade eigenständige ausführbare Dateien herunter, die keine Python-Installation erfordern:

Unterstützte Plattformen

Plattform	Architektur	Datei
Linux	x86_64	`tzst-{version}-linux-amd64.zip`
Linux	ARM64	`tzst-{version}-linux-arm64.zip`
Windows	x64	`tzst-{version}-windows-amd64.zip`
Windows	ARM64	`tzst-{version}-windows-arm64.zip`
macOS	Intel	`tzst-{version}-darwin-amd64.zip`
macOS	Apple Silicon	`tzst-{version}-darwin-arm64.zip`

Installationsschritte

Lade das entsprechende Archiv für deine Plattform von der Seite der neuesten Releases herunter
Extrahiere das Archiv, um die ausführbare Datei tzst (oder tzst.exe unter Windows) zu erhalten
Verschiebe die ausführbare Datei in ein Verzeichnis in deinem PATH:
- Linux/macOS: sudo mv tzst /usr/local/bin/
- Windows: Füge das Verzeichnis mit tzst.exe zu deiner PATH-Umgebungsvariable hinzu
Überprüfe die Installation: tzst --help

Vorteile der Binärinstallation

Kein Python erforderlich - Eigenständige ausführbare Datei
Schnellerer Start - Kein Python-Interpreter-Overhead
Einfache Bereitstellung - Einzeldatei-Distribution
Konsistentes Verhalten - Gebündelte Abhängigkeiten

Von PyPI

Mit pip:

pip install tzst

Oder mit uv (empfohlen):

uv tool install tzst

Aus dem Quellcode

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

Entwicklungsinstallation

Dieses Projekt verwendet moderne Python-Packaging-Standards:

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

Schnellstart

Kommandozeilennutzung

# Archiv erstellen
tzst a archive.tzst file1.txt file2.txt directory/

# Archiv extrahieren
tzst x archive.tzst

# Archivinhalt auflisten
tzst l archive.tzst

# Archivintegrität testen
tzst t archive.tzst

Python API Nutzung

from tzst import create_archive, extract_archive, list_archive

# Archiv erstellen
create_archive("archive.tzst", ["file1.txt", "file2.txt", "directory/"])

# Archiv extrahieren
extract_archive("archive.tzst", "output_directory/")

# Archivinhalt auflisten
contents = list_archive("archive.tzst", verbose=True)
for item in contents:
    print(f"{item['name']}: {item['size']} bytes")

Kommandozeilenschnittstelle

Archivoperationen

Archiv erstellen

# Grundlegende Nutzung
tzst a archive.tzst file1.txt file2.txt

# Mit Komprimierungsstufe (1-22, Standard: 3)
tzst a archive.tzst files/ -l 15

# Alternative Befehle
tzst add archive.tzst files/
tzst create archive.tzst files/

Archiv extrahieren

# Mit vollständiger Verzeichnisstruktur extrahieren
tzst x archive.tzst

# In spezifisches Verzeichnis extrahieren
tzst x archive.tzst -o output/

# Spezifische Dateien extrahieren
tzst x archive.tzst file1.txt dir/file2.txt

# Ohne Verzeichnisstruktur extrahieren (flach)
tzst e archive.tzst -o output/

# Streaming-Modus für große Archive verwenden
tzst x archive.tzst --streaming -o output/

Inhalt auflisten

# Einfache Auflistung
tzst l archive.tzst

# Ausführliche Auflistung mit Details
tzst l archive.tzst -v

# Streaming-Modus für große Archive verwenden
tzst l archive.tzst --streaming -v

Integrität testen

# Archivintegrität testen
tzst t archive.tzst

# Mit Streaming-Modus testen
tzst t archive.tzst --streaming

Befehlsreferenz

Befehl	Aliase	Beschreibung	Streaming-Unterstützung
`a`	`add`, `create`	Archiv erstellen oder hinzufügen	N/A
`x`	`extract`	Mit vollständigen Pfaden extrahieren	✓ `--streaming`
`e`	`extract-flat`	Ohne Verzeichnisstruktur extrahieren	✓ `--streaming`
`l`	`list`	Archivinhalt auflisten	✓ `--streaming`
`t`	`test`	Archivintegrität testen	✓ `--streaming`

CLI-Optionen

-v, --verbose: Ausführliche Ausgabe aktivieren
-o, --output DIR: Ausgabeverzeichnis spezifizieren (Extraktionsbefehle)
-l, --level LEVEL: Komprimierungsstufe 1-22 setzen (Erstellungsbefehl)
--streaming: Streaming-Modus für speichereffiziente Verarbeitung aktivieren
--filter FILTER: Sicherheitsfilter für Extraktion (data/tar/fully_trusted)
--no-atomic: Atomare Dateioperationen deaktivieren (nicht empfohlen)

Sicherheitsfilter

# Mit maximaler Sicherheit extrahieren (Standard)
tzst x archive.tzst --filter data

# Mit Standard-Tar-Kompatibilität extrahieren
tzst x archive.tzst --filter tar

# Mit vollem Vertrauen extrahieren (gefährlich - nur für vertrauenswürdige Archive)
tzst x archive.tzst --filter fully_trusted

Sicherheitsfilter-Optionen:

data (Standard): Am sichersten. Blockiert gefährliche Dateien, absolute Pfade und Pfade außerhalb des Extraktionsverzeichnisses
tar: Standard-Tar-Kompatibilität. Blockiert absolute Pfade und Verzeichnisdurchquerung
fully_trusted: Keine Sicherheitsbeschränkungen. Nur bei vollständig vertrauenswürdigen Archiven verwenden

Python API

TzstArchive Klasse

from tzst import TzstArchive

# Neues Archiv erstellen
with TzstArchive("archive.tzst", "w", compression_level=5) as archive:
    archive.add("file.txt")
    archive.add("directory/", recursive=True)

# Vorhandenes Archiv lesen
with TzstArchive("archive.tzst", "r") as archive:
    # Inhalt auflisten
    contents = archive.list(verbose=True)
    
    # Mit Sicherheitsfilter extrahieren
    archive.extract("file.txt", "output/", filter="data")
    
    # Integrität testen
    is_valid = archive.test()

# Für große Archive, Streaming-Modus verwenden
with TzstArchive("large_archive.tzst", "r", streaming=True) as archive:
    archive.extract(path="output/")

Wichtige Einschränkungen:

Anhängemodus nicht unterstützt: Erstelle mehrere Archive oder erstelle das gesamte Archiv neu

Convenience-Funktionen

create_archive()

from tzst import create_archive

# Mit atomaren Operationen erstellen (Standard)
create_archive(
    archive_path="backup.tzst",
    files=["documents/", "photos/", "config.txt"],
    compression_level=10
)

extract_archive()

from tzst import extract_archive

# Mit Sicherheit extrahieren (Standard: 'data' Filter)
extract_archive("backup.tzst", "restore/")

# Spezifische Dateien extrahieren
extract_archive("backup.tzst", "restore/", members=["config.txt"])

# Verzeichnisstruktur abflachen
extract_archive("backup.tzst", "restore/", flatten=True)

# Streaming für große Archive verwenden
extract_archive("large_backup.tzst", "restore/", streaming=True)

list_archive()

from tzst import list_archive

# Einfache Auflistung
files = list_archive("backup.tzst")

# Detaillierte Auflistung
files = list_archive("backup.tzst", verbose=True)

# Streaming für große Archive
files = list_archive("large_backup.tzst", streaming=True)

test_archive()

from tzst import test_archive

# Grundlegende Integritätsprüfung
if test_archive("backup.tzst"):
    print("Archiv ist gültig")

# Mit Streaming testen
if test_archive("large_backup.tzst", streaming=True):
    print("Großes Archiv ist gültig")

Erweiterte Funktionen

Dateierweiterungen

Die Bibliothek behandelt Dateierweiterungen automatisch mit intelligenter Normalisierung:

.tzst - Primäre Erweiterung für tar+zstandard Archive
.tar.zst - Alternative Standarderweiterung
Automatische Erkennung beim Öffnen vorhandener Archive
Automatisches Hinzufügen von Erweiterungen beim Erstellen von Archiven

# Diese erstellen alle gültige Archive
create_archive("backup.tzst", files)      # Erstellt backup.tzst
create_archive("backup.tar.zst", files)  # Erstellt backup.tar.zst  
create_archive("backup", files)          # Erstellt backup.tzst
create_archive("backup.txt", files)      # Erstellt backup.tzst (normalisiert)

Komprimierungsstufen

Zstandard-Komprimierungsstufen reichen von 1 (schnellste) bis 22 (beste Komprimierung):

Stufe 1-3: Schnelle Komprimierung, größere Dateien
Stufe 3 (Standard): Guter Kompromiss zwischen Geschwindigkeit und Komprimierung
Stufe 10-15: Bessere Komprimierung, langsamer
Stufe 20-22: Maximale Komprimierung, viel langsamer

Streaming-Modus

Verwende den Streaming-Modus für speichereffiziente Verarbeitung großer Archive:

Vorteile:

Deutlich reduzierter Speicherverbrauch
Bessere Leistung für Archive, die nicht in den Speicher passen
Automatische Bereinigung von Ressourcen

Wann verwenden:

Archive größer als 100MB
Umgebungen mit begrenztem Speicher
Verarbeitung von Archiven mit vielen großen Dateien

# Beispiel: Verarbeitung eines großen Backup-Archivs
from tzst import extract_archive, list_archive, test_archive

large_archive = "backup_500gb.tzst"

# Speichereffiziente Operationen
is_valid = test_archive(large_archive, streaming=True)
contents = list_archive(large_archive, streaming=True, verbose=True)
extract_archive(large_archive, "restore/", streaming=True)

Atomare Operationen

Alle Dateierstellungsoperationen verwenden standardmäßig atomare Dateioperationen:

Archive werden zuerst in temporären Dateien erstellt, dann atomisch verschoben
Automatische Bereinigung bei Prozessunterbrechung
Kein Risiko von beschädigten oder unvollständigen Archiven
Plattformübergreifende Kompatibilität

# Atomare Operationen standardmäßig aktiviert
create_archive("important.tzst", files)  # Sicher vor Unterbrechung

# Kann bei Bedarf deaktiviert werden (nicht empfohlen)
create_archive("test.tzst", files, use_temp_file=False)

Fehlerbehandlung

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("Fehler beim Dekomprimieren des Archivs")
except TzstFileNotFoundError:
    print("Archivdatei nicht gefunden")
except KeyboardInterrupt:
    print("Operation vom Benutzer unterbrochen")
    # Bereinigung wird automatisch durchgeführt

Leistung und Vergleich

Leistungstipps

Komprimierungsstufen: Stufe 3 ist optimal für die meisten Anwendungsfälle
Streaming: Verwende für Archive größer als 100MB
Batch-Operationen: Füge mehrere Dateien in einer Sitzung hinzu
Dateitypen: Bereits komprimierte Dateien werden nicht viel weiter komprimiert

vs Andere Tools

vs tar + gzip:

Bessere Komprimierungsraten
Schnellere Dekomprimierung
Moderner Algorithmus

vs tar + xz:

Deutlich schnellere Komprimierung
Ähnliche Komprimierungsraten
Besserer Geschwindigkeit/Komprimierung-Kompromiss

vs zip:

Bessere Komprimierung
Bewahrt Unix-Berechtigungen und Metadaten
Bessere Streaming-Unterstützung

Anforderungen

Python 3.12 oder höher
zstandard >= 0.19.0

Entwicklung

Entwicklungsumgebung einrichten