# 13.6. `tarfile` — Lecture et écriture de fichiers d’archives tar

Code source : Lib/tarfile.py

Le module `tarfile` rend possible la lecture et l’écriture des archives tar, incluant celles utilisant la compression gzip, bz2 et lzma. Utilisez le module `zipfile` pour lire ou écrire des fichiers `zip`, ou les fonctions de niveau supérieur dans shutil.

Quelques faits et chiffres :

- lit et écrit des archives compressées avec `gzip`, `bz2` ou `lzma` si les modules respectifs sont disponibles.

- prise en charge de la lecture/écriture pour le format POSIX.1-1988 (ustar).

- prise en charge de la lecture/écriture pour le format GNU tar incluant les extensions longname et longlink, prise en charge de la lecture seule de toutes les variantes de l’extension sparse incluant la restauration des fichiers discontinus.

- prise en charge de la lecture/écriture pour le format POSIX.1-2001 (pax).

- gère les répertoires, les fichiers normaux, les liens directs (hard links en anglais), les liens symboliques, les tubes nommés (FIFO en anglais), les périphériques de caractère et les périphériques de bloc et est en mesure d’acquérir et de restaurer les informations du fichier comme l’horodatage, les autorisations d’accès et le propriétaire.

Modifié dans la version 3.3: prise en charge de la compression `lzma`.

`tarfile.``open`(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

  Renvoie un objet `TarFile` pour le nom de chemin name. Pour plus d’informations sur les objets `TarFile` et les mot-clefs arguments permis, voir Les objets TarFile.

  Le mode doit être une chaîne de caractères de la forme `'filemode[:compression]'`, par défaut à `'r'`. Voici une liste complète des combinaisons de mode :

  mode | action
  --- | ---
  `'r' ou 'r:*'` | Ouvre en lecture avec compression transparente (recommandé).
  `'r:'` | Ouvre en lecture, sans compression.
  `'r:gz'` | Ouvre en lecture avec la compression gzip.
  `'r:bz2'` | Ouvre en lecture avec la compression bzip2.
  `'r:xz'` | Ouvre en lecture avec la compression lzma.
  `'x'` ou `'x:'` | Crée un fichier tar sans compression. Lève une exception `FileExistsError` s’il existe déjà.
  `'x:gz'` | Crée un fichier tar avec la compression gzip. Lève une exception `FileExistsError` s’il existe déjà.
  `'x:bz2'` | Crée un fichier tar avec la compression bzip2. Lève une exception `FileExistsError` s’il existe déjà.
  `'x:xz'` | Crée un fichier tar avec la compression lzma. Lève une exception `FileExistsError` s’il existe déjà.
  `'a' ou 'a:'` | Ouvre pour ajouter à la fin, sans compression. Le fichier est créé s’il n’existe pas.
  `'w' ou 'w:'` | Ouvre en écriture, sans compression.
  `'w:gz'` | Ouvre en écriture avec compression gzip.
  `'w:bz2'` | Ouvre en écriture avec compression bzip2.
  `'w:xz'` | Ouvre en écriture avec la compression lzma.

  Notez que les combinaisons `'a:gz'`, `'a:bz2'` ou `'a:xz'` ne sont pas possibles. Si le mode n’est pas adapté pour ouvrir un certain fichier (compressé) pour la lecture, une exception `ReadError` est levée. Utilisez le mode `'r'` pour éviter cela. Si une méthode de compression n’est pas prise en charge, `CompressionError` est levée.

  Si fileobj est spécifié, il est utilisé comme une alternative au file object ouvert en mode binaire pour name. Il est censé être à la position 0.

  Pour les modes `'w:gz'`, `'r:gz'`, `'w:bz2'`, `'r:bz2'`, `'x:gz'`, `'x:bz2'`, `tarfile.open()` accepte l’argument nommé compresslevel (par défaut à `9`) pour spécifier le niveau de compression du fichier.

  Pour des cas particuliers, il existe un deuxième format pour le mode : `'filemode[compression]'`. `tarfile.open()` renvoie un objet `TarFile` qui traite ses données comme un flux de blocs. Aucun retour en arrière ne sera effectué lors de la lecture du fichier. S’il est donné, fileobj peut être n’importe quel objet qui a une méthode `read()` ou `write()` (selon le mode). Le paramètre bufsize spécifie la taille du bloc et vaut par défaut `20 * 512` octets. Utilisez cette variante en combinaison avec par exemple `sys.stdin`, une connexion (socket en anglais) file object ou un dispositif de bande. Cependant, un tel objet `TarFile` est limité en ce qu’il ne permet pas l’accès aléatoire, voir Exemples. Les modes actuellement possibles :

  Mode | Action
  --- | ---
  `'r|*'` | Ouvre un flux des blocs de tar en lecture avec une compression transparente.
  `'r|'` | Ouvre un flux de blocs tar non compressés en lecture.
  `'r|gz'` | Ouvre un flux compressé avec gzip en lecture.
  `'r|bz2'` | Ouvre un flux compressé avec bzip2 en lecture.
  `'r|xz'` | Ouvre un flux compressé avec lzma en lecture.
  `'w|'` | Ouvre un flux non compressé en écriture.
  `'w|gz'` | Ouvre un flux compressé avec gzip en écriture.
  `'w|bz2'` | Ouvre un flux compressé avec bzip2 en écriture.
  `'w|xz'` | Ouvre un flux compressé avec lzma en écriture.

  Modifié dans la version 3.5: Le mode `'x'` (création exclusive) est créé.

  Modifié dans la version 3.6: le paramètre name accepte un path-like object.

class `tarfile.``TarFile`

  Classe pour la lecture et l’écriture d’archives tar. N’utilisez pas cette classe directement, préférez `tarfile.open()`. Voir Les objets TarFile.

`tarfile.``is_tarfile`(name)

  Return `True` if name is a tar archive file, that the `tarfile` module can read.

Le module `tarfile` définit les exceptions suivantes :

exception `tarfile.``TarError`

  Classe de base pour toutes les exceptions du module `tarfile`.

exception `tarfile.``ReadError`

  Est levée lors de l’ouverture d’une archive tar, qui ne peut pas être gérée par le module `tarfile` ou est invalide.

exception `tarfile.``CompressionError`

  Est levée lorsqu’une méthode de compression n’est pas prise en charge ou lorsque les données ne peuvent pas être décodées correctement.

exception `tarfile.``StreamError`

  Est levée pour les limitations typiques des objets de type flux `TarFile`.

exception `tarfile.``ExtractError`

  Est levée pour des erreurs non-fatales lors de l’utilisation de `TarFile.extract()`, mais uniquement si `TarFile.errorlevel``` == 2``.

exception `tarfile.``HeaderError`

  Est levée par `TarInfo.frombuf()` si le tampon qu’il obtient n’est pas valide.

Les constantes suivantes sont disponibles au niveau du module :

`tarfile.``ENCODING`

  L’encodage des caractères par défaut est `'utf-8'` sous Windows, sinon la valeur renvoyée par `sys.getfilesystemencoding()`.

Chacune des constantes suivantes définit un format d’archive tar que le module `tarfile` est capable de créer. Voir la section Formats tar pris en charge pour plus de détails.

`tarfile.``USTAR_FORMAT`

  Le format POSIX.1-1988 (ustar).

`tarfile.``GNU_FORMAT`

  Le format GNU tar.

`tarfile.``PAX_FORMAT`

  Le format POSIX.1-2001 (pax).

`tarfile.``DEFAULT_FORMAT`

  The default format for creating archives. This is currently `GNU_FORMAT`.

Voir aussi

Module `zipfile`

  Documentation du module standard `zipfile`.

Archiving operations

  Documentation des outils d’archivage de haut niveau fournis par le module standard `shutil`.

Manuel GNU *tar*, format *tar* basique (en anglais)

  Documentation pour les fichiers d’archive tar, y compris les extensions tar GNU.

## 13.6.1. Les objets TarFile

L’objet `TarFile` fournit une interface vers une archive tar. Une archive tar est une séquence de blocs. Un membre d’archive (un fichier stocké) est composé d’un bloc d’en-tête suivi des blocs de données. Il est possible de stocker plusieurs fois un fichier dans une archive tar. Chaque membre d’archive est représenté par un objet `TarInfo`, voir Les objets TarInfo pour plus de détails.

Un objet `TarFile` peut être utilisé comme gestionnaire de contexte dans une instruction `with`. Il sera automatiquement fermé une fois le bloc terminé. Veuillez noter qu’en cas d’exception, une archive ouverte en écriture ne sera pas finalisée ; seul l’objet fichier utilisé en interne sera fermé. Voir la section Exemples pour un cas d’utilisation.

Nouveau dans la version 3.2: Ajout de la prise en charge du protocole de gestion de contexte.

class `tarfile.``TarFile`(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors='surrogateescape', pax_headers=None, debug=0, errorlevel=0)

  Tous les arguments suivants sont facultatifs et sont également accessibles en tant qu’instance d’attributs.

  Le name est le chemin d’accès de l’archive. name peut être un path-like object. Il peut être omis si fileobj est donné. Dans ce cas, l’attribut `name` de l’objet fichier est utilisé s’il existe.

  Le mode est soit `'r'` pour lire à partir d’une archive existante, `'a'` pour ajouter des données à un fichier existant, `'w'` pour créer un nouveau fichier en écrasant un existant, ou `'x'` pour créer un nouveau fichier uniquement s’il n’existe pas déjà.

  Si fileobj est fourni, il est utilisé pour lire ou écrire des données. S’il peut être déterminé, le mode est remplacé par le mode de fileobj. fileobj sera utilisé à partir de la position 0.

  Note

  fileobj n’est pas fermé, lorsque `TarFile` est fermé.

  format controls the archive format. It must be one of the constants `USTAR_FORMAT`, `GNU_FORMAT` or `PAX_FORMAT` that are defined at module level.

  L’argument tarinfo peut être utilisé pour remplacer la classe par défaut `TarInfo` par une autre.

  Si dereference est `False`, ajoute des liens symboliques et physiques à l’archive. Si c’est `True`, ajoute le contenu des fichiers cibles à l’archive. Cela n’a aucun effet sur les systèmes qui ne prennent pas en charge les liens symboliques.

  Si ignore_zeros est `False`, traite un bloc vide comme la fin de l’archive. Si c’est le cas `True`, saute les blocs vides (et invalides) et essaye d’obtenir autant de membres que possible. Ceci n’est utile que pour lire des archives concaténées ou endommagées.

  debug peut être défini de `0` (aucun message de débogage) à `3` (tous les messages de débogage). Les messages sont écrits dans `sys.stderr`.

  Si errorlevel est `0`, toutes les erreurs sont ignorées lors de l’utilisation de `TarFile.extract()`. Néanmoins, ils apparaissent comme des messages d’erreur dans la sortie de débogage, lorsque le débogage est activé. Si `1`, toutes les erreurs fatales sont déclenchées comme des exceptions `OSError`. Si `2`, toutes les erreurs non-fatales sont déclenchées comme des exceptions `TarError` également.

  Les arguments encoding et errors définissent l’encodage de caractères à utiliser pour lire ou écrire l’archive et comment les erreurs de conversion vont être traitées. Les paramètres par défaut fonctionneront pour la plupart des utilisateurs. Voir la section Problèmes unicode pour des informations détaillées.

  L’argument pax_headers est un dictionnaire facultatif de chaînes de caractères qui sera ajouté en tant qu’en-tête global pax si le format est `PAX_FORMAT`.

  Modifié dans la version 3.2: Utilise `'surrogateescape'` comme valeur par défaut pour l’argument errors.

  Modifié dans la version 3.5: Le mode `'x'` (création exclusive) est créé.

  Modifié dans la version 3.6: le paramètre name accepte un path-like object.

classmethod `TarFile.``open`(...)

  Constructeur alternatif. La fonction `tarfile.open()` est en fait un raccourci vers cette méthode de classe.

`TarFile.``getmember`(name)

  Renvoie un objet `TarInfo` pour le membre name. Si name est introuvable dans l’archive, `KeyError` est levée.

  Note

  Si un membre apparaît plus d’une fois dans l’archive, sa dernière occurrence est supposée être la version la plus récente.

`TarFile.``getmembers`()

  Renvoie les membres de l’archive sous la forme d’une liste d’objets `TarInfo`. La liste a le même ordre que les membres de l’archive.

`TarFile.``getnames`()

  Renvoie les membres comme une liste de leurs noms. Il a le même ordre que la liste renvoyée par `getmembers()`.

`TarFile.``list`(verbose=True, *, members=None)

  Imprime une table des matières dans `sys.stdout`. Si verbose est `False`, seuls les noms des membres sont imprimés. Si c’est `True`, une sortie similaire à celle de ls -l est produite. Si des membres facultatifs sont fournis, il doit s’agir d’un sous-ensemble de la liste renvoyée par `getmembers()`.

  Modifié dans la version 3.5: Ajout du paramètre members.

`TarFile.``next`()

  Renvoie le membre suivant de l’archive en tant qu’objet `TarInfo`, lorsque la classe `TarFile` est ouverte en lecture. Renvoie `None` s’il n’y a pas.

`TarFile.``extractall`(path=".", members=None, *, numeric_owner=False)

  Extrait tous les membres de l’archive vers le répertoire de travail actuel ou le répertoire chemin. Si des membres facultatifs sont fournis, il doit s’agir d’un sous-ensemble de la liste renvoyée par `getmembers()`. Les informations d’annuaire telles que le propriétaire, l’heure de modification et les autorisations sont définies une fois tous les membres extraits. Cela est fait pour contourner deux problèmes : l’heure de modification d’un répertoire est réinitialisée chaque fois qu’un fichier y est créé. Et, si les autorisations d’un répertoire ne permettent pas l’écriture, l’extraction de fichiers échoue.

  Si numeric_owner est `True`, les numéros uid et gid du fichier tar sont utilisés pour définir le propriétaire et le groupe des fichiers extraits. Sinon, les valeurs nommées du fichier tar sont utilisées.

  Avertissement

  Ne jamais extraire des archives de sources non fiables sans inspection préalable. Il est possible que des fichiers soient créés en dehors de chemin, par exemple : les membres qui ont des noms de fichiers absolus commençant par `"/"` ou des noms de fichiers avec deux points `".."`.

  Modifié dans la version 3.5: Ajout du paramètre numeric_owner.

  Modifié dans la version 3.6: Le paramètre path accepte un objet chemin-compatible path-like object.

`TarFile.``extract`(member, path="", set_attrs=True, *, numeric_owner=False)

  Extrait un membre de l’archive vers le répertoire de travail actuel, en utilisant son nom complet. Les informations de son fichier sont extraites aussi précisément que possible. Le membre peut être un nom de fichier ou un objet `TarInfo`. Vous pouvez spécifier un répertoire différent en utilisant path. path peut être un path-like object. Les attributs de fichier (propriétaire, mtime, mode) sont définis sauf si set_attrs est faux.

  Si numeric_owner est `True`, les numéros uid et gid du fichier tar sont utilisés pour définir le propriétaire et le groupe des fichiers extraits. Sinon, les valeurs nommées du fichier tar sont utilisées.

  Note

  La méthode `extract()` ne prend pas en charge plusieurs problèmes d’extraction. Dans la plupart des cas, vous devriez envisager d’utiliser la méthode `extractall()`.

  Avertissement

  Voir l’avertissement pour `extractall()`.

  Modifié dans la version 3.2: Ajout du paramètre set_attrs.

  Modifié dans la version 3.5: Ajout du paramètre numeric_owner.

  Modifié dans la version 3.6: Le paramètre path accepte un objet chemin-compatible path-like object.

`TarFile.``extractfile`(member)

  Extract a member from the archive as a file object. member may be a filename or a `TarInfo` object. If member is a regular file or a link, an `io.BufferedReader` object is returned. Otherwise, `None` is returned.

  Modifié dans la version 3.3: Renvoie un objet `io.BufferedReader`.

`TarFile.``add`(name, arcname=None, recursive=True, exclude=None, *, filter=None)

  Add the file name to the archive. name may be any type of file (directory, fifo, symbolic link, etc.). If given, arcname specifies an alternative name for the file in the archive. Directories are added recursively by default. This can be avoided by setting recursive to `False`. If exclude is given, it must be a function that takes one filename argument and returns a boolean value. Depending on this value the respective file is either excluded (`True`) or added (`False`). If filter is specified it must be a keyword argument. It should be a function that takes a `TarInfo` object argument and returns the changed `TarInfo` object. If it instead returns `None` the `TarInfo` object will be excluded from the archive. See Exemples for an example.

  Modifié dans la version 3.2: Ajout du paramètre filter.

  Obsolète depuis la version 3.2: The exclude parameter is deprecated, please use the filter parameter instead.

`TarFile.``addfile`(tarinfo, fileobj=None)

  Ajoute l’objet `TarInfo` tarinfo à l’archive. Si fileobj est donné, il convient que ce soit un fichier binaire, et les octets `tarinfo.size` sont lus à partir de celui-ci et ajoutés à l’archive. Vous pouvez créer des objets `TarInfo` directement, ou en utilisant `gettarinfo()`.

`TarFile.``gettarinfo`(name=None, arcname=None, fileobj=None)

  Crée un objet `TarInfo` à partir du résultat de `os.stat()` ou équivalent sur un fichier existant. Le fichier est soit nommé par name, soit spécifié comme file object fileobj avec un descripteur de fichier. name peut être un objet semblable à un chemin. S’il est donné, arcname spécifie un autre nom pour le fichier dans l’archive, sinon, le nom est tiré de l’attribut fileobj `name`, ou de l’argument name. Le nom doit être une chaîne de texte.

  Vous pouvez modifier certains des attributs de `TarInfo` avant de les ajouter en utilisant `addfile()`. Si l’objet fichier n’est pas un objet fichier ordinaire positionné au début du fichier, des attributs tels que `size` peuvent nécessiter une modification. C’est le cas pour des objets tels que `GzipFile`. Le `name` peut également être modifié, auquel cas arcname pourrait être une chaîne factice.

  Modifié dans la version 3.6: le paramètre name accepte un path-like object.

`TarFile.``close`()

  Ferme le `TarFile`. En mode écriture, deux blocs de finition à zéro sont ajoutés à l’archive.

`TarFile.``pax_headers`

  Un dictionnaire contenant des paires clé-valeur d’en-têtes globaux pax.

## 13.6.2. Les objets TarInfo

Un objet `TarInfo` représente un membre dans un `TarFile`. En plus de stocker tous les attributs requis d’un fichier (comme le type de fichier, la taille, l’heure, les autorisations, le propriétaire, etc.), il fournit quelques méthodes utiles pour déterminer son type. Il ne contient pas les données du fichier lui-même.

Les objets `TarInfo` sont renvoyés par les méthodes de `TarFile` `getmember()`, `getmembers()` et `gettarinfo()`.

class `tarfile.``TarInfo`(name="")

  Crée un objet `TarInfo`.

classmethod `TarInfo.``frombuf`(buf, encoding, errors)

  Crée et renvoie un objet `TarInfo` à partir de la chaîne tampon buf.

  Lève `HeaderError` si le tampon n’est pas valide.

classmethod `TarInfo.``fromtarfile`(tarfile)

  Lit le membre suivant dans l’objet `TarFile` tarfile et le renvoie comme un objet `TarInfo`.

`TarInfo.``tobuf`(format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')

  Crée un tampon de chaîne de caractères à partir d’un objet `TarInfo`. Pour plus d’informations sur les arguments, voir le constructeur de la classe `TarFile`.

  Modifié dans la version 3.2: Utilise `'surrogateescape'` comme valeur par défaut pour l’argument errors.

Un objet `TarInfo` a les attributs de données publics suivants :

`TarInfo.``name`

  Nom du membre de l’archive.

`TarInfo.``size`

  La taille en octets.

`TarInfo.``mtime`

  L’heure de la dernière modification.

`TarInfo.``mode`

  Bits d’autorisation.

`TarInfo.``type`

  Type de fichier. type est généralement l’une des constantes suivantes : `REGTYPE`, `AREGTYPE`, `LNKTYPE`, `SYMTYPE`, `DIRTYPE`, `FIFOTYPE`, `CONTTYPE`, `CHRTYPE`, `BLKTYPE`, `GNUTYPE_SPARSE`. Pour déterminer plus facilement le type d’un objet `TarInfo`, utilisez les méthodes `is*()` ci-dessous.

`TarInfo.``linkname`

  Nom du fichier cible, qui n’est présent que dans les objets `TarInfo` de type `LNKTYPE` et `SYMTYPE`.

`TarInfo.``uid`

  ID de l’utilisateur qui a initialement stocké ce membre.

`TarInfo.``gid`

  ID de groupe de l’utilisateur qui a initialement stocké ce membre.

`TarInfo.``uname`

  Nom d’utilisateur.

`TarInfo.``gname`

  Nom de groupe.

`TarInfo.``pax_headers`

  Un dictionnaire contenant des paires clé-valeur d’un en-tête étendu pax associé.

Un objet `TarInfo` fournit également des méthodes de requête pratiques :

`TarInfo.``isfile`()

  Renvoie `True` si l’objet `Tarinfo` est un fichier normal.

`TarInfo.``isreg`()

  Identique à `isfile()`.

`TarInfo.``isdir`()

  Renvoie `True` si c’est un dossier.

`TarInfo.``issym`()

  Renvoie `True` s’il s’agit d’un lien symbolique.

`TarInfo.``islnk`()

  Renvoie `True` s’il s’agit d’un lien physique.

`TarInfo.``ischr`()

  Renvoie `True` s’il s’agit d’un périphérique de caractères.

`TarInfo.``isblk`()

  Renvoie `True` s’il s’agit d’un périphérique de bloc.

`TarInfo.``isfifo`()

  Renvoie `True` s’il s’agit d’un tube nommé (FIFO).

`TarInfo.``isdev`()

  Renvoie `True` s’il s’agit d’un périphérique de caractères, d’un périphérique de bloc ou d’un tube nommé.

## 13.6.3. Interface en ligne de commande

Nouveau dans la version 3.4.

Le module `tarfile` fournit une interface de ligne de commande simple pour interagir avec les archives tar.

Si vous souhaitez créer une nouvelle archive tar, spécifiez son nom après l’option `-c`, puis répertorie-le ou les noms de fichiers à inclure :

    $ python -m tarfile -c monty.tar  spam.txt eggs.txt

Passer un répertoire est aussi possible :

    $ python -m tarfile -c monty.tar life-of-brian_1979/

Si vous souhaitez extraire une archive tar dans le répertoire courant, utilisez l’option `-e` :

    $ python -m tarfile -e monty.tar

Vous pouvez également extraire une archive tar dans un autre répertoire en passant le nom du répertoire :

    $ python -m tarfile -e monty.tar  other-dir/

Pour une liste des fichiers dans une archive tar, utilisez l’option `-l` :

    $ python -m tarfile -l monty.tar

### 13.6.3.1. Options de la ligne de commande

`-l``<tarfile>`
`--list``<tarfile>`

  Liste les fichiers dans une archive tar.

`-c``<tarfile> <source1> ... <sourceN>`
`--create``<tarfile> <source1> ... <sourceN>`

  Crée une archive tar à partir des fichiers sources.

`-e``<tarfile> [<output_dir>]`
`--extract``<tarfile> [<output_dir>]`

  Extrait l’archive tar dans le répertoire courant si output_dir n’est pas spécifié.

`-t``<tarfile>`
`--test``<tarfile>`

  Teste si l’archive tar est valide ou non.

`-v````,` `--verbose```

  Sortie verbeuse.

## 13.6.4. Exemples

Comment extraire une archive tar dans le dossier de travail courant :

    import tarfile
    tar = tarfile.open("sample.tar.gz")
    tar.extractall()
    tar.close()

Comment extraire un sous-ensemble d’une archive tar avec `TarFile.extractall()` en utilisant une fonction de générateur au lieu d’une liste :

    import os
    import tarfile

    def py_files(members):
        for tarinfo in members:
            if os.path.splitext(tarinfo.name)[1] == ".py":
                yield tarinfo

    tar = tarfile.open("sample.tar.gz")
    tar.extractall(members=py_files(tar))
    tar.close()

Comment créer une archive tar non compressée à partir d’une liste de noms de fichiers :

    import tarfile
    tar = tarfile.open("sample.tar", "w")
    for name in ["foo", "bar", "quux"]:
        tar.add(name)
    tar.close()

Le même exemple en utilisant l’instruction `with` :

    import tarfile
    with tarfile.open("sample.tar", "w") as tar:
        for name in ["foo", "bar", "quux"]:
            tar.add(name)

Comment lire une archive tar compressée avec gzip et afficher des informations des membres :

    import tarfile
    tar = tarfile.open("sample.tar.gz", "r:gz")
    for tarinfo in tar:
        print(tarinfo.name, "is", tarinfo.size, "bytes in size and is", end="")
        if tarinfo.isreg():
            print("a regular file.")
        elif tarinfo.isdir():
            print("a directory.")
        else:
            print("something else.")
    tar.close()

Comment créer une archive et réinitialiser les informations de l’utilisateur en utilisant le paramètre filter dans `TarFile.add()` :

    import tarfile
    def reset(tarinfo):
        tarinfo.uid = tarinfo.gid = 0
        tarinfo.uname = tarinfo.gname = "root"
        return tarinfo
    tar = tarfile.open("sample.tar.gz", "w:gz")
    tar.add("foo", filter=reset)
    tar.close()

## 13.6.5. Formats tar pris en charge

Il existe trois formats tar qui peuvent être créés avec le module `tarfile` :

- Le format POSIX.1-1988 ustar (`ustar_FORMAT`). Il prend en charge les noms de fichiers jusqu’à une longueur maximale de 256 caractères et les noms de liens jusqu’à 100 caractères. La taille maximale du fichier est de 8 Go. Il s’agit d’un format ancien et limité mais largement pris en charge.

- Le format GNU tar (`GNU_FORMAT`). Il prend en charge les noms de fichiers longs et les noms de liens, les fichiers supérieurs à 8 Go et les fichiers discontinus. C’est la norme de facto des systèmes GNU / Linux. `tarfile` prend entièrement en charge les extensions GNU tar pour les noms longs, la prise en charge des fichiers discontinus est en lecture seule.

- The POSIX.1-2001 pax format (`PAX_FORMAT`). It is the most flexible format with virtually no limits. It supports long filenames and linknames, large files and stores pathnames in a portable way. However, not all tar implementations today are able to handle pax archives properly.

  The pax format is an extension to the existing ustar format. It uses extra headers for information that cannot be stored otherwise. There are two flavours of pax headers: Extended headers only affect the subsequent file header, global headers are valid for the complete archive and affect all following files. All the data in a pax header is encoded in UTF-8 for portability reasons.

Il existe d’autres variantes du format tar qui peuvent être lues, mais pas créées

- L’ancien format V7. Il s’agit du premier format tar d”Unix Seventh Edition, ne stockant que des fichiers et répertoires normaux. Les noms ne doivent pas dépasser 100 caractères, il n’y a aucune information de nom d’utilisateur / groupe. Certaines archives ont des sommes de contrôle d’en-tête mal calculées dans le cas de champs avec des caractères non ASCII.

- Format étendu SunOS tar. Ce format est une variante du format POSIX.1-2001 pax, mais n’est pas compatible.

## 13.6.6. Problèmes unicode

Le format tar a été initialement conçu pour effectuer des sauvegardes sur des lecteurs de bande en mettant principalement l’accent sur la préservation des informations du système de fichiers. De nos jours, les archives tar sont couramment utilisées pour la distribution de fichiers et l’échange d’archives sur des réseaux. Un problème du format d’origine (qui est la base de tous les autres formats) est qu’il n’existe aucun concept de prise en charge d’encodages de caractères différents. Par exemple, une archive tar ordinaire créée sur un système UTF-8 ne peut pas être lue correctement sur un système Latin-1 si elle contient des caractères non ASCII. Les métadonnées textuelles (comme les noms de fichiers, les noms de liens, les noms d’utilisateurs / de groupes) sembleront endommagées. Malheureusement, il n’y a aucun moyen de détecter automatiquement l’encodage d’une archive. Le format pax a été conçu pour résoudre ce problème. Il stocke les métadonnées non ASCII en utilisant l’encodage universel des caractères UTF-8.

Les détails de la conversion des caractères dans `tarfile` sont contrôlés par les arguments nommés encoding et errors de la classe `TarFile`.

encoding définit l’encodage de caractères à utiliser pour les métadonnées de l’archive. La valeur par défaut est `sys.getfilesystemencoding()` ou `'ascii'` comme solution de rechange. Selon que l’archive est lue ou écrite, les métadonnées doivent être décodées ou encodées. Si l’encodage n’est pas défini correctement, cette conversion peut échouer.

L’argument errors définit le traitement des caractères qui ne peuvent pas être convertis. Les valeurs possibles sont répertoriées dans la section Gestionnaires d’erreurs. Le schéma par défaut est `'surrogateescape'` que Python utilise également pour ses appels de système de fichiers, voir Noms de fichiers, arguments en ligne de commande, et variables d’environnement.

In case of `PAX_FORMAT` archives, encoding is generally not needed because all the metadata is stored using UTF-8. encoding is only used in the rare cases when binary pax headers are decoded or when strings with surrogate characters are stored.