"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) a
   été ajouté.

   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)

   Renvoie "True" si *name* est un fichier d'archive *tar*, que le
   module "tarfile" peut lire. *name* peut être une "str", un ficher
   ou un objet fichier-compatible.

   Modifié dans la version 3.9: Prise en charge des fichiers et des
   objets fichier-compatibles.

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

   Format par défaut pour la création d'archives. C'est actuellement
   "PAX_FORMAT".

   Modifié dans la version 3.8: Le format par défaut des nouvelles
   archives a été changé de "GNU_FORMAT" en "PAX_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.


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é.

   Le *format* contrôle le format d'archive en écriture. Il doit
   s'agir de l'une des constantes "USTAR_FORMAT", "GNU_FORMAT" ou
   "PAX_FORMAT" définies au niveau du module. Lors de la lecture, le
   format sera automatiquement détecté, même si différents formats
   sont présents dans une même archive.

   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) a
   été ajouté.

   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 *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 *path-
   like object*.

TarFile.extractfile(member)

   Extrait un membre de l'archive en tant qu'objet fichier. *member*
   peut être un nom de fichier ou un objet "TarInfo". Si *member* est
   un fichier normal ou un lien, un objet "io.BufferedReader" est
   renvoyé. Sinon, "None" est renvoyé. Lève une exception "KeyError"
   si *member* n'est pas présent dans l'archive.

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

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

   Ajoute le fichier *name* à l'archive. *name* peut être n'importe
   quel type de fichier (répertoire, *fifo*, lien symbolique, etc.).
   S'il est donné, *arcname* spécifie un autre nom pour le fichier
   dans l'archive. Les répertoires sont ajoutés récursivement par
   défaut. Cela peut être évité en définissant *recursive* sur
   "False". La récursivité ajoute des entrées dans l'ordre trié. Si
   *filter* est donné, il convient que ce soit une fonction qui prend
   un argument d'objet "TarInfo" et renvoie l'objet changé "TarInfo".
   S'il renvoie à la place "None", l'objet "TarInfo" sera exclu de
   l'archive. Voir Exemples pour un exemple.

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

   Modifié dans la version 3.7: La récursivité ajoute les entrées dans
   un ordre trié.

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*.


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é.


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


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.


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()


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.

* Le format *POSIX.1-2001* *pax* ("PAX_FORMAT"). Il est le format le
  plus flexible avec pratiquement aucune limite. Il prend en charge
  les noms de fichiers et de liens longs, les fichiers volumineux et
  stocke les chemins d'accès de manière portable. Les implémentations
  *tar* modernes, y compris GNU *tar*, *bsdtar* / *libarchive* et
  *star*, prennent entièrement en charge les fonctionnalités *pax*
  étendues ; certaines bibliothèques anciennes ou non entretenues ne
  le gèrent peut-être pas, mais devraient traiter les archives *pax*
  comme si elles étaient au format **ustar** universellement pris en
  charge. Il s'agit du format par défaut actuel pour les nouvelles
  archives.

  Il étend le format *ustar* existant avec des en-têtes
  supplémentaires pour les informations qui ne peuvent pas être
  stockées autrement. Il existe deux types d'en-têtes *pax* : les en-
  têtes étendus n'affectent que l'en-tête de fichier suivant, les en-
  têtes globaux sont valides pour l'archive complète et affectent tous
  les fichiers suivants. Toutes les données d'un en-tête *pax* sont
  encodées en *UTF-8* pour des raisons de portabilité.

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.


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.

Pour les archives "PAX_FORMAT" (par défaut), l'encodage n'est
généralement pas nécessaire car toutes les métadonnées sont stockées à
l'aide de *UTF-8*. L'encodage n'est utilisé que dans les rares cas où
les en-têtes *pax* binaires sont décodés ou lorsque les chaînes avec
des caractères de substitution sont stockées.
