tzst/README.fr.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

16 KiB

Raw Blame History

tzst est une bibliothèque et une CLI pour Python 3.12+ destinées à créer, extraire, lister et vérifier des archives .tzst et .tar.zst. Elle réunit la compatibilité tar, la compression Zstandard, le mode streaming, les écritures atomiques et une extraction sécurisée par défaut dans une interface compacte prête pour la production.

Note

Article technique détaillé : Deep Dive into tzst: A Modern Python Archiving Library Based on Zstandard.

Fonctionnalités

Compression élevée : Compression Zstandard pour d'excellents taux de compression et une vitesse remarquable
Compatibilité Tar : Crée des archives tar standard compressées avec Zstandard
Interface en ligne de commande : CLI intuitive avec support de streaming et options complètes
API Python : API propre et pythonique pour un usage programmatique
Multi-plateforme : Fonctionne sur Windows, macOS et Linux
Extensions multiples : Supporte les extensions .tzst et .tar.zst
Efficace en mémoire : Mode streaming pour gérer de grandes archives avec une utilisation mémoire minimale
Opérations atomiques : Opérations de fichiers sécurisées avec nettoyage automatique en cas d'interruption
Sécurisé par défaut : Utilise le filtre 'data' pour une sécurité maximale lors de l'extraction
Gestion d'erreurs améliorée : Messages d'erreur clairs avec des alternatives utiles

Installation

Depuis les Releases GitHub

Téléchargez des exécutables autonomes qui ne nécessitent pas d'installation Python :

Plateformes supportées

Plateforme	Architecture	Fichier
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`

Étapes d'installation

Téléchargez l'archive appropriée pour votre plateforme depuis la page des dernières versions
Extrayez l'archive pour obtenir l'exécutable tzst (ou tzst.exe sous Windows)
Déplacez l'exécutable vers un répertoire dans votre PATH :
- Linux/macOS : sudo mv tzst /usr/local/bin/
- Windows : Ajoutez le répertoire contenant tzst.exe à votre variable d'environnement PATH
Vérifiez l'installation : tzst --help

Avantages de l'installation binaire

Aucun Python requis - Exécutable autonome
Démarrage plus rapide - Aucune surcharge d'interpréteur Python
Déploiement facile - Distribution en fichier unique
Comportement cohérent - Dépendances intégrées

Depuis PyPI

Avec pip :

pip install tzst

Ou avec uv (recommandé) :

uv tool install tzst

Depuis le code source

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

Installation de développement

Ce projet utilise les standards modernes d'empaquetage Python :

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

Démarrage rapide

Utilisation en ligne de commande

# Créer une archive
tzst a archive.tzst file1.txt file2.txt directory/

# Extraire une archive
tzst x archive.tzst

# Lister le contenu d'une archive
tzst l archive.tzst

# Tester l'intégrité d'une archive
tzst t archive.tzst

Utilisation de l'API Python

from tzst import create_archive, extract_archive, list_archive

# Créer une archive
create_archive("archive.tzst", ["file1.txt", "file2.txt", "directory/"])

# Extraire une archive
extract_archive("archive.tzst", "output_directory/")

# Lister le contenu d'une archive
contents = list_archive("archive.tzst", verbose=True)
for item in contents:
    print(f"{item['name']}: {item['size']} bytes")

Interface en ligne de commande

Opérations d'archives

Créer une archive

# Utilisation de base
tzst a archive.tzst file1.txt file2.txt

# Avec niveau de compression (1-22, défaut : 3)
tzst a archive.tzst files/ -l 15

# Commandes alternatives
tzst add archive.tzst files/
tzst create archive.tzst files/

Extraire une archive

# Extraire avec structure complète des répertoires
tzst x archive.tzst

# Extraire vers un répertoire spécifique
tzst x archive.tzst -o output/

# Extraire des fichiers spécifiques
tzst x archive.tzst file1.txt dir/file2.txt

# Extraire sans structure de répertoires (à plat)
tzst e archive.tzst -o output/

# Utiliser le mode streaming pour de grandes archives
tzst x archive.tzst --streaming -o output/

Lister le contenu

# Liste simple
tzst l archive.tzst

# Liste détaillée avec informations
tzst l archive.tzst -v

# Utiliser le mode streaming pour de grandes archives
tzst l archive.tzst --streaming -v

Tester l'intégrité

# Tester l'intégrité de l'archive
tzst t archive.tzst

# Tester avec le mode streaming
tzst t archive.tzst --streaming

Référence des commandes

Commande	Alias	Description	Support streaming
`a`	`add`, `create`	Créer ou ajouter à une archive	N/A
`x`	`extract`	Extraire avec chemins complets	✓ `--streaming`
`e`	`extract-flat`	Extraire sans structure de répertoires	✓ `--streaming`
`l`	`list`	Lister le contenu de l'archive	✓ `--streaming`
`t`	`test`	Tester l'intégrité de l'archive	✓ `--streaming`

Options CLI

-v, --verbose : Activer la sortie détaillée
-o, --output DIR : Spécifier le répertoire de sortie (commandes d'extraction)
-l, --level LEVEL : Définir le niveau de compression 1-22 (commande de création)
--streaming : Activer le mode streaming pour un traitement efficace en mémoire
--filter FILTER : Filtre de sécurité pour l'extraction (data/tar/fully_trusted)
--no-atomic : Désactiver les opérations de fichiers atomiques (non recommandé)

Filtres de sécurité

# Extraire avec sécurité maximale (défaut)
tzst x archive.tzst --filter data

# Extraire avec compatibilité tar standard
tzst x archive.tzst --filter tar

# Extraire avec confiance totale (dangereux - uniquement pour les archives de confiance)
tzst x archive.tzst --filter fully_trusted

Options de filtre de sécurité :

data (défaut) : Le plus sécurisé. Bloque les fichiers dangereux, les chemins absolus et les chemins en dehors du répertoire d'extraction
tar : Compatibilité tar standard. Bloque les chemins absolus et la traversée de répertoires
fully_trusted : Aucune restriction de sécurité. À utiliser uniquement avec des archives entièrement fiables

API Python

Classe TzstArchive

from tzst import TzstArchive

# Créer une nouvelle archive
with TzstArchive("archive.tzst", "w", compression_level=5) as archive:
    archive.add("file.txt")
    archive.add("directory/", recursive=True)

# Lire une archive existante
with TzstArchive("archive.tzst", "r") as archive:
    # Lister le contenu
    contents = archive.list(verbose=True)
    
    # Extraire avec filtre de sécurité
    archive.extract("file.txt", "output/", filter="data")
    
    # Tester l'intégrité
    is_valid = archive.test()

# Pour de grandes archives, utiliser le mode streaming
with TzstArchive("large_archive.tzst", "r", streaming=True) as archive:
    archive.extract(path="output/")

Limitations importantes :

Mode d'ajout non supporté : Créez plusieurs archives ou recréez l'archive entière à la place

Fonctions de convenance

create_archive()

from tzst import create_archive

# Créer avec opérations atomiques (défaut)
create_archive(
    archive_path="backup.tzst",
    files=["documents/", "photos/", "config.txt"],
    compression_level=10
)

extract_archive()

from tzst import extract_archive

# Extraire avec sécurité (défaut : filtre 'data')
extract_archive("backup.tzst", "restore/")

# Extraire des fichiers spécifiques
extract_archive("backup.tzst", "restore/", members=["config.txt"])

# Aplatir la structure des répertoires
extract_archive("backup.tzst", "restore/", flatten=True)

# Utiliser le streaming pour de grandes archives
extract_archive("large_backup.tzst", "restore/", streaming=True)

list_archive()

from tzst import list_archive

# Liste simple
files = list_archive("backup.tzst")

# Liste détaillée
files = list_archive("backup.tzst", verbose=True)

# Streaming pour de grandes archives
files = list_archive("large_backup.tzst", streaming=True)

test_archive()

from tzst import test_archive

# Test d'intégrité de base
if test_archive("backup.tzst"):
    print("L'archive est valide")

# Tester avec streaming
if test_archive("large_backup.tzst", streaming=True):
    print("La grande archive est valide")

Fonctionnalités avancées

Extensions de fichiers

La bibliothèque gère automatiquement les extensions de fichiers avec normalisation intelligente :

.tzst - Extension principale pour les archives tar+zstandard
.tar.zst - Extension standard alternative
Détection automatique lors de l'ouverture d'archives existantes
Ajout automatique d'extension lors de la création d'archives

# Toutes ces créent des archives valides
create_archive("backup.tzst", files)      # Crée backup.tzst
create_archive("backup.tar.zst", files)  # Crée backup.tar.zst  
create_archive("backup", files)          # Crée backup.tzst
create_archive("backup.txt", files)      # Crée backup.tzst (normalisé)

Niveaux de compression

Les niveaux de compression Zstandard vont de 1 (le plus rapide) à 22 (meilleure compression) :

Niveau 1-3 : Compression rapide, fichiers plus volumineux
Niveau 3 (défaut) : Bon équilibre entre vitesse et compression
Niveau 10-15 : Meilleure compression, plus lent
Niveau 20-22 : Compression maximale, beaucoup plus lent

Mode streaming

Utilisez le mode streaming pour un traitement efficace en mémoire de grandes archives :

Avantages :

Utilisation mémoire considérablement réduite
Meilleures performances pour les archives qui ne tiennent pas en mémoire
Nettoyage automatique des ressources

Quand utiliser :

Archives supérieures à 100MB
Environnements à mémoire limitée
Traitement d'archives avec de nombreux gros fichiers

# Exemple : Traitement d'une grande archive de sauvegarde
from tzst import extract_archive, list_archive, test_archive

large_archive = "backup_500gb.tzst"

# Opérations efficaces en mémoire
is_valid = test_archive(large_archive, streaming=True)
contents = list_archive(large_archive, streaming=True, verbose=True)
extract_archive(large_archive, "restore/", streaming=True)

Opérations atomiques

Toutes les opérations de création de fichiers utilisent des opérations de fichiers atomiques par défaut :

Archives créées dans des fichiers temporaires d'abord, puis déplacées atomiquement
Nettoyage automatique si le processus est interrompu
Aucun risque d'archives corrompues ou incomplètes
Compatibilité multi-plateforme

# Opérations atomiques activées par défaut
create_archive("important.tzst", files)  # Sûr contre les interruptions

# Peut être désactivé si nécessaire (non recommandé)
create_archive("test.tzst", files, use_temp_file=False)

Gestion des erreurs

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("Échec de la décompression de l'archive")
except TzstFileNotFoundError:
    print("Fichier d'archive non trouvé")
except KeyboardInterrupt:
    print("Opération interrompue par l'utilisateur")
    # Le nettoyage est géré automatiquement

Performance et comparaison

Conseils de performance

Niveaux de compression : Le niveau 3 est optimal pour la plupart des cas d'usage
Streaming : Utilisez pour les archives supérieures à 100MB
Opérations par lots : Ajoutez plusieurs fichiers en une seule session
Types de fichiers : Les fichiers déjà compressés ne se compresseront pas beaucoup plus

vs Autres outils

vs tar + gzip :

Meilleurs taux de compression
Décompression plus rapide
Algorithme moderne

vs tar + xz :

Compression significativement plus rapide
Taux de compression similaires
Meilleur compromis vitesse/compression

vs zip :

Meilleure compression
Préserve les permissions Unix et métadonnées
Meilleur support de streaming

Exigences

Python 3.12 ou supérieur
zstandard >= 0.19.0

Développement

Configuration de l'environnement de développement