xixu-me/tzst
1
0 Fork 0
Code Issues Pull Requests Actions 7 Packages Projects Releases Wiki Activity
Files
81ac67bf862417b2164f7831d6f2c533bded5be9
tzst/README.de.md
T

527 lines
16 KiB
Markdown
Raw Blame History

<h1 align="center">
<img src="https://raw.githubusercontent.com/xixu-me/tzst/refs/heads/main/docs/_static/tzst-logo.png" width="300">
</h1><br>
[![codecov](https://codecov.io/gh/xixu-me/tzst/graph/badge.svg?token=2AIN1559WU)](https://codecov.io/gh/xixu-me/tzst)
[![CodeQL](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql)
[![CI/CD](https://github.com/xixu-me/tzst/actions/workflows/ci.yml/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/ci.yml)
[![PyPI - Version](https://img.shields.io/pypi/v/tzst)](https://pypi.org/project/tzst/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/tzst)](https://pypistats.org/packages/tzst)
[![GitHub License](https://img.shields.io/github/license/xixu-me/tzst)](LICENSE)
[![Sponsor](https://img.shields.io/badge/Sponsor-violet)](https://xi-xu.me/#sponsorships)
[![Documentation](https://img.shields.io/badge/Documentation-blue)](https://tzst.xi-xu.me)
[🇺🇸 English](./README.md) | [🇨🇳 汉语](./README.zh.md) | [🇪🇸 español](./README.es.md) | [🇯🇵 日本語](./README.ja.md) | [🇦🇪 العربية](./README.ar.md) | [🇷🇺 русский](./README.ru.md) | **🇩🇪 Deutsch** | [🇫🇷 français](./README.fr.md) | [🇰🇷 한국어](./README.ko.md) | [🇧🇷 português](./README.pt.md)
**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](https://blog.xi-xu.me/2025/11/01/deep-dive-into-tzst-en.html)**.
## 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
1. **Lade** das entsprechende Archiv für deine Plattform von der [Seite der neuesten Releases](https://github.com/xixu-me/tzst/releases/latest) herunter
2. **Extrahiere** das Archiv, um die ausführbare Datei `tzst` (oder `tzst.exe` unter Windows) zu erhalten
3. **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
4. **Ü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:
```bash
pip install tzst
```
Oder mit uv (empfohlen):
```bash
uv tool install tzst
```
### Aus dem Quellcode
```bash
git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install .
```
### Entwicklungsinstallation
Dieses Projekt verwendet moderne Python-Packaging-Standards:
```bash
git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install -e .[dev]
```
## Schnellstart
### Kommandozeilennutzung
```bash
# 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
```python
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```python
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()
```python
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()
```python
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()
```python
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()
```python
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
```python
# 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
```python
# 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
```python
# 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
```python
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
1. **Komprimierungsstufen**: Stufe 3 ist optimal für die meisten Anwendungsfälle
2. **Streaming**: Verwende für Archive größer als 100MB
3. **Batch-Operationen**: Füge mehrere Dateien in einer Sitzung hinzu
4. **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
Dieses Projekt verwendet moderne Python-Packaging-Standards:
```bash
git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install -e .[dev]
```
### Tests ausführen
```bash
# Tests mit Coverage ausführen
pytest --cov=tzst --cov-report=html
# Oder den einfacheren Befehl verwenden (Coverage-Einstellungen sind in pyproject.toml)
pytest
```
### Code-Qualität
```bash
# Code-Qualität prüfen
ruff check src tests
# Code formatieren
ruff format src tests
```
## Beitragen
Wir begrüßen Beiträge! Bitte lies unseren [Beitragsleitfaden](CONTRIBUTING.md) für:
- Entwicklungssetup und Projektstruktur
- Code-Stil-Richtlinien und bewährte Praktiken
- Testanforderungen und Schreibtests
- Pull-Request-Prozess und Review-Workflow
### Schnellstart für Mitwirkende
```bash
git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install -e .[dev]
python -m pytest tests/
```
### Arten willkommener Beiträge
- **Fehlerbehebungen** - Probleme in vorhandener Funktionalität beheben
- **Funktionen** - Neue Fähigkeiten zur Bibliothek hinzufügen
- **Dokumentation** - Dokumentation verbessern oder hinzufügen
- **Tests** - Testabdeckung hinzufügen oder verbessern
- **Leistung** - Vorhandenen Code optimieren
- **Sicherheit** - Sicherheitsschwachstellen beheben
## Danksagungen
- [Meta Zstandard](https://github.com/facebook/zstd) für den exzellenten Komprimierungsalgorithmus
- [python-zstandard](https://github.com/indygreg/python-zstandard) für Python-Bindings
- Der Python-Community für Inspiration und Feedback
## Lizenz
Urheberrecht &copy; [Xi Xu](https://xi-xu.me). Alle Rechte vorbehalten.
Lizenziert unter der [BSD 3-Clause](LICENSE) Lizenz.
Reference in new issue View Git Blame Copy Permalink