"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 possible. 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)

   Retourne "True" si *name* est un fichier d'archive *tar*, que le
   module "tarfile" peut lire.

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.

exception tarfile.FilterError

   Base class for members refused by filters.

   tarinfo

      Information about the member that the filter refused to extract,
      as TarInfo.

exception tarfile.AbsolutePathError

   Raised to refuse extracting a member with an absolute path.

exception tarfile.OutsideDestinationError

   Raised to refuse extracting a member outside the destination
   directory.

exception tarfile.SpecialFileError

   Raised to refuse extracting a special file (e.g. a device or pipe).

exception tarfile.AbsoluteLinkError

   Raised to refuse extracting a symbolic link with an absolute path.

exception tarfile.LinkOutsideDestinationError

   Raised to refuse extracting a symbolic link pointing outside the
   destination directory.

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=1)

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

   *errorlevel* controls how extraction errors are handled, see "the
   corresponding attribute".

   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, filter=None)

   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.

   The *filter* argument, which was added in Python 3.8.17, specifies
   how "members" are modified or rejected before extraction. See
   Extraction filters for details. It is recommended to set this
   explicitly depending on which *tar* features you need to support.

   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 ex: les membres qui ont des noms
     de fichiers absolus commençant par ""/"" ou des noms de fichiers
     avec deux points "".."".Set "filter='data'" to prevent the most
     dangerous security issues, and read the Extraction filters
     section for details.

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

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

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

   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.

   The *numeric_owner* and *filter* arguments are the same as for
   "extractall()".

   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()".Set "filter='data'" to
     prevent the most dangerous security issues, and read the
     Extraction filters section for details.

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

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

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

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

TarFile.errorlevel: int

   If *errorlevel* is "0", errors are ignored when using
   "TarFile.extract()" and "TarFile.extractall()". Nevertheless, they
   appear as error messages in the debug output when *debug* is
   greater than 0. If "1" (the default), all *fatal* errors are raised
   as "OSError" or "FilterError" exceptions. If "2", all *non-fatal*
   errors are raised as "TarError" exceptions as well.

   Some exceptions, e.g. ones caused by wrong argument types or data
   corruption, are always raised.

   Custom extraction filters should raise "FilterError" for *fatal*
   errors and "ExtractError" for *non-fatal* ones.

   Note that when an exception is raised, the archive may be partially
   extracted. It is the user’s responsibility to clean up.

TarFile.extraction_filter

   Nouveau dans la version 3.8.17.

   The extraction filter used as a default for the *filter* argument
   of "extract()" and "extractall()".

   The attribute may be "None" or a callable. String names are not
   allowed for this attribute, unlike the *filter* argument to
   "extract()".

   If "extraction_filter" is "None" (the default), calling an
   extraction method without a *filter* argument will use the
   "fully_trusted" filter for compatibility with previous Python
   versions.

   In Python 3.12+, leaving "extraction_filter=None" will emit a
   "DeprecationWarning".

   In Python 3.14+, leaving "extraction_filter=None" will cause
   extraction methods to use the "data" filter by default.

   The attribute may be set on instances or overridden in subclasses.
   It also is possible to set it on the "TarFile" class itself to set
   a global default, although, since it affects all uses of *tarfile*,
   it is best practice to only do so in top-level applications or
   "site configuration". To set a global default this way, a filter
   function needs to be wrapped in "staticmethod()" to prevent
   injection of a "self" argument.

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 *récursive* 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.

"TarInfo" objects are returned by "TarFile"'s methods "getmember()",
"getmembers()" and "gettarinfo()".

Modifying the objects returned by "getmember()" or "getmembers()" will
affect all subsequent operations on the archive. For cases where this
is unwanted, you can use "copy.copy()" or call the "replace()" method
to create a modified copy in one step.

Several attributes can be set to "None" to indicate that a piece of
metadata is unused or unknown. Different "TarInfo" methods handle
"None" differently:

* The "extract()" or "extractall()" methods will ignore the
  corresponding metadata, leaving it set to a default.

* "addfile()" will fail.

* "list()" will print a placeholder string.

Modifié dans la version 3.8.17: Added "replace()" and handling of
"None".

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: str

   Nom du membre de l'archive.

TarInfo.size: int

   La taille en octets.

TarInfo.mtime: int | float

   Time of last modification in seconds since the epoch, as in
   "os.stat_result.st_mtime".

   Modifié dans la version 3.8.17: Can be set to "None" for
   "extract()" and "extractall()", causing extraction to skip applying
   this attribute.

TarInfo.mode: int

   Permission bits, as for "os.chmod()".

   Modifié dans la version 3.8.17: Can be set to "None" for
   "extract()" and "extractall()", causing extraction to skip applying
   this attribute.

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: str

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

   For symbolic links ("SYMTYPE"), the *linkname* is relative to the
   directory that contains the link. For hard links ("LNKTYPE"), the
   *linkname* is relative to the root of the archive.

TarInfo.uid: int

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

   Modifié dans la version 3.8.17: Can be set to "None" for
   "extract()" and "extractall()", causing extraction to skip applying
   this attribute.

TarInfo.gid: int

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

   Modifié dans la version 3.8.17: Can be set to "None" for
   "extract()" and "extractall()", causing extraction to skip applying
   this attribute.

TarInfo.uname: str

   Nom d'utilisateur.

   Modifié dans la version 3.8.17: Can be set to "None" for
   "extract()" and "extractall()", causing extraction to skip applying
   this attribute.

TarInfo.gname: str

   Nom de groupe.

   Modifié dans la version 3.8.17: Can be set to "None" for
   "extract()" and "extractall()", causing extraction to skip applying
   this attribute.

TarInfo.pax_headers: dict

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

TarInfo.replace(name=..., mtime=..., mode=..., linkname=...,
uid=..., gid=..., uname=..., gname=...,
deep=True)

   Nouveau dans la version 3.8.17.

   Return a *new* copy of the "TarInfo" object with the given
   attributes changed. For example, to return a "TarInfo" with the
   group name set to "'staff'", use:

      new_tarinfo = old_tarinfo.replace(gname='staff')

   By default, a deep copy is made. If *deep* is false, the copy is
   shallow, i.e. "pax_headers" and any custom attributes are shared
   with the original "TarInfo" object.

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


Extraction filters
==================

Nouveau dans la version 3.8.17.

The *tar* format is designed to capture all details of a UNIX-like
filesystem, which makes it very powerful. Unfortunately, the features
make it easy to create tar files that have unintended -- and possibly
malicious -- effects when extracted. For example, extracting a tar
file can overwrite arbitrary files in various ways (e.g.  by using
absolute paths, ".." path components, or symlinks that affect later
members).

In most cases, the full functionality is not needed. Therefore,
*tarfile* supports extraction filters: a mechanism to limit
functionality, and thus mitigate some of the security issues.

Voir aussi:

  **PEP 706**
     Contains further motivation and rationale behind the design.

The *filter* argument to "TarFile.extract()" or "extractall()" can be:

* the string "'fully_trusted'": Honor all metadata as specified in the
  archive. Should be used if the user trusts the archive completely,
  or implements their own complex verification.

* the string "'tar'": Honor most *tar*-specific features (i.e.
  features of UNIX-like filesystems), but block features that are very
  likely to be surprising or malicious. See "tar_filter()" for
  details.

* the string "'data'": Ignore or block most features specific to UNIX-
  like filesystems. Intended for extracting cross-platform data
  archives. See "data_filter()" for details.

* "None" (default): Use "TarFile.extraction_filter".

  If that is also "None" (the default), the "'fully_trusted'" filter
  will be used (for compatibility with earlier versions of Python).

  In Python 3.12, the default will emit a "DeprecationWarning".

  In Python 3.14, the "'data'" filter will become the default instead.
  It's possible to switch earlier; see "TarFile.extraction_filter".

* A callable which will be called for each extracted member with a
  TarInfo describing the member and the destination path to where the
  archive is extracted (i.e. the same path is used for all members):

     filter(/, member: TarInfo, path: str) -> TarInfo | None

  The callable is called just before each member is extracted, so it
  can take the current state of the disk into account. It can:

  * return a "TarInfo" object which will be used instead of the
    metadata in the archive, or

  * return "None", in which case the member will be skipped, or

  * raise an exception to abort the operation or skip the member,
    depending on "errorlevel". Note that when extraction is aborted,
    "extractall()" may leave the archive partially extracted. It does
    not attempt to clean up.


Default named filters
---------------------

The pre-defined, named filters are available as functions, so they can
be reused in custom filters:

tarfile.fully_trusted_filter(/, member, path)

   Return *member* unchanged.

   This implements the "'fully_trusted'" filter.

tarfile.tar_filter(/, member, path)

   Implements the "'tar'" filter.

   * Strip leading slashes ("/" and "os.sep") from filenames.

   * Refuse to extract files with absolute paths (in case the name is
     absolute even after stripping slashes, e.g. "C:/foo" on Windows).
     This raises "AbsolutePathError".

   * Refuse to extract files whose absolute path (after following
     symlinks) would end up outside the destination. This raises
     "OutsideDestinationError".

   * Clear high mode bits (setuid, setgid, sticky) and group/other
     write bits ("S_IWOTH").

   Return the modified "TarInfo" member.

tarfile.data_filter(/, member, path)

   Implements the "'data'" filter. In addition to what "tar_filter"
   does:

   * Refuse to extract links (hard or soft) that link to absolute
     paths, or ones that link outside the destination.

     This raises "AbsoluteLinkError" or "LinkOutsideDestinationError".

     Note that such files are refused even on platforms that do not
     support symbolic links.

   * Refuse to extract device files (including pipes). This raises
     "SpecialFileError".

   * For regular files, including hard links:

     * Set the owner read and write permissions ("S_IWUSR").

     * Remove the group & other executable permission ("S_IXOTH") if
       the owner doesn’t have it ("S_IXUSR").

   * For other files (directories), set "mode" to "None", so that
     extraction methods skip applying permission bits.

   * Set user and group info ("uid", "gid", "uname", "gname") to
     "None", so that extraction methods skip setting it.

   Return the modified "TarInfo" member.


Filter errors
-------------

When a filter refuses to extract a file, it will raise an appropriate
exception, a subclass of "FilterError". This will abort the extraction
if "TarFile.errorlevel" is 1 or more. With "errorlevel=0" the error
will be logged and the member will be skipped, but extraction will
continue.


Hints for further verification
------------------------------

Even with "filter='data'", *tarfile* is not suited for extracting
untrusted files without prior inspection. Among other issues, the pre-
defined filters do not prevent denial-of-service attacks. Users should
do additional checks.

Here is an incomplete list of things to consider:

* Extract to a "new temporary directory" to prevent e.g. exploiting
  pre-existing links, and to make it easier to clean up after a failed
  extraction.

* When working with untrusted data, use external (e.g. OS-level)
  limits on disk, memory and CPU usage.

* Check filenames against an allow-list of characters (to filter out
  control characters, confusables, foreign path separators, etc.).

* Check that filenames have expected extensions (discouraging files
  that execute when you “click on them”, or extension-less files like
  Windows special device names).

* Limit the number of extracted files, total size of extracted data,
  filename length (including symlink length), and size of individual
  files.

* Check for files that would be shadowed on case-insensitive
  filesystems.

Also note that:

* Tar files may contain multiple versions of the same file. Later ones
  are expected to overwrite any earlier ones. This feature is crucial
  to allow updating tape archives, but can be abused maliciously.

* *tarfile* does not protect against issues with “live” data, e.g. an
  attacker tinkering with the destination (or source) directory while
  extraction (or archiving) is in progress.


Supporting older Python versions
--------------------------------

Extraction filters were added to Python 3.12, and are backported to
older versions as security updates. To check whether the feature is
available, use e.g. "hasattr(tarfile, 'data_filter')" rather than
checking the Python version.

The following examples show how to support Python versions with and
without the feature. Note that setting "extraction_filter" will affect
any subsequent operations.

* Fully trusted archive:

     my_tarfile.extraction_filter = (lambda member, path: member)
     my_tarfile.extractall()

* Use the "'data'" filter if available, but revert to Python 3.11
  behavior ("'fully_trusted'") if this feature is not available:

     my_tarfile.extraction_filter = getattr(tarfile, 'data_filter',
                                            (lambda member, path: member))
     my_tarfile.extractall()

* Use the "'data'" filter; *fail* if it is not available:

     my_tarfile.extractall(filter=tarfile.data_filter)

  or:

     my_tarfile.extraction_filter = tarfile.data_filter
     my_tarfile.extractall()

* Use the "'data'" filter; *warn* if it is not available:

     if hasattr(tarfile, 'data_filter'):
         my_tarfile.extractall(filter='data')
     else:
         # remove this when no longer needed
         warn_the_user('Extracting may be unsafe; consider updating Python')
         my_tarfile.extractall()


Stateful extraction filter example
----------------------------------

While *tarfile*'s extraction methods take a simple *filter* callable,
custom filters may be more complex objects with an internal state. It
may be useful to write these as context managers, to be used like
this:

   with StatefulFilter() as filter_func:
       tar.extractall(path, filter=filter_func)

Such a filter can be written as, for example:

   class StatefulFilter:
       def __init__(self):
           self.file_count = 0

       def __enter__(self):
           return self

       def __call__(self, member, path):
           self.file_count += 1
           return member

       def __exit__(self, *exc_info):
           print(f'{self.file_count} files extracted')


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.

--filter <filtername>

   Specifies the *filter* for "--extract". See Extraction filters for
   details. Only string names are accepted (that is, "fully_trusted",
   "tar", and "data").

   Nouveau dans la version 3.8.17.


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 de mot-clé *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.
