# `tarfile` --- Read and write tar archive files

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 :

- reads and writes `gzip`, `bz2`, `compression.zstd`, and `lzma` compressed archives if the respective modules are available.

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

Modifié dans la version 3.12: Archives are extracted using a filter, which makes it possible to either limit surprising/dangerous features, or to acknowledge that they are expected and the archive is fully trusted.

Modifié dans la version 3.14: Set the default extraction filter to `data`, which disallows some dangerous features such as links to absolute paths or paths outside of the destination. Previously, the filter strategy was equivalent to `fully_trusted`.

Modifié dans la version 3.14: Added support for Zstandard compression using `compression.zstd`.

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'` or `'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.
  `'r:zst'` | Open for reading with Zstandard compression.
  `'x'` ou `'x:'` | Create a tarfile exclusively without compression. Raise a `FileExistsError` exception if it already exists.
  `'x:gz'` | Create a tarfile with gzip compression. Raise a `FileExistsError` exception if it already exists.
  `'x:bz2'` | Create a tarfile with bzip2 compression. Raise a `FileExistsError` exception if it already exists.
  `'x:xz'` | Create a tarfile with lzma compression. Raise a `FileExistsError` exception if it already exists.
  `'x:zst'` | Create a tarfile with Zstandard compression. Raise a `FileExistsError` exception if it already exists.
  `'a'` or `'a:'` | Ouvre pour ajouter à la fin, sans compression. Le fichier est créé s'il n'existe pas.
  `'w'` or `'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.
  `'w:zst'` | Open for Zstandard compressed writing.

  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.

  For modes `'w:gz'`, `'x:gz'`, `'w|gz'`, `'w:bz2'`, `'x:bz2'`, `'w|bz2'`, `tarfile.open()` accepts the keyword argument compresslevel (default `9`) to specify the compression level of the file.

  For modes `'w:xz'`, `'x:xz'` and `'w|xz'`, `tarfile.open()` accepts the keyword argument preset to specify the compression level of the file.

  For modes `'w:zst'`, `'x:zst'` and `'w|zst'`, `tarfile.open()` accepts the keyword argument level to specify the compression level of the file. The keyword argument options may also be passed, providing advanced Zstandard compression parameters described by `CompressionParameter`. The keyword argument zstd_dict can be passed to provide a `ZstdDict`, a Zstandard dictionary used to improve compression of smaller amounts of data.

  For special purposes, there is a second format for mode: `'filemode|[compression]'`. `tarfile.open()` will return a `TarFile` object that processes its data as a stream of blocks. No random seeking will be done on the file. If given, fileobj may be any object that has a `read()` or `write()` method (depending on the mode) that works with bytes. bufsize specifies the blocksize and defaults to `20 * 512` bytes. Use this variant in combination with e.g. `sys.stdin.buffer`, a socket file object or a tape device. However, such a `TarFile` object is limited in that it does not allow random access, see Exemples. The currently possible modes:

  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.
  `'r|zst'` | Open a Zstandard compressed stream for reading.
  `'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.
  `'w|zst'` | Open a Zstandard compressed stream for writing.

  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.

  Modifié dans la version 3.12: The compresslevel keyword argument also works for streams.

  Modifié dans la version 3.14: The preset keyword argument also works for streams.

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.

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.

exception tarfile.LinkFallbackError

  Raised to refuse emulating a link (hard or symbolic) by extracting another archive member, when that member would be rejected by the filter location. The exception that was raised to reject the replacement member is available as `BaseException.__context__`.

  Ajouté dans la version 3.14.

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

tarfile.REGTYPE
tarfile.AREGTYPE

  A regular file `type`.

tarfile.LNKTYPE

  A link (inside tarfile) `type`.

tarfile.SYMTYPE

  A symbolic link `type`.

tarfile.CHRTYPE

  A character special device `type`.

tarfile.BLKTYPE

  A block special device `type`.

tarfile.DIRTYPE

  A directory `type`.

tarfile.FIFOTYPE

  A FIFO special device `type`.

tarfile.CONTTYPE

  A contiguous file `type`.

tarfile.GNUTYPE_LONGNAME

  A GNU tar longname `type`.

tarfile.GNUTYPE_LONGLINK

  A GNU tar longlink `type`.

tarfile.GNUTYPE_SPARSE

  A GNU tar sparse file `type`.

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.

Ajouté 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, stream=False)

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

  name is the pathname of the archive. name may be a path-like object. It can be omitted if fileobj is given. In this case, the file object's `name` attribute is used if it exists.

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

  If stream is set to `True` then while reading the archive info about files in the archive are not cached, saving memory.

  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.

  Modifié dans la version 3.13: Add the stream parameter.

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 specifies how `members` are modified or rejected before extraction. See Extraction filters for details. It is recommended to set this explicitly only if specific tar features are required, or as `filter='data'` to support Python versions with a less secure default (3.13 and lower).

  Avertissement

  Never extract archives from untrusted sources without prior inspection.

  Since Python 3.14, the default (`data`) will prevent the most dangerous security issues. However, it will not prevent all unintended or insecure behavior. 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.12: Ajout du paramètre filter.

  Modifié dans la version 3.14: The filter parameter now defaults to `'data'`.

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

  Never extract archives from untrusted sources without prior inspection. See the warning for `extractall()` 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.12: 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é. 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`.

  Modifié dans la version 3.13: The returned `io.BufferedReader` object has the `mode` attribute which is always equal to `'rb'`.

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

  Ajouté dans la version 3.12.

  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), extraction methods will 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.

  Modifié dans la version 3.14: The default filter is set to `data`, which disallows some dangerous features such as links to absolute paths or paths outside of the destination. Previously, the default was equivalent to `fully_trusted`.

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)

  Add the `TarInfo` object tarinfo to the archive. If tarinfo represents a non zero-size regular file, the fileobj argument should be a binary file, and `tarinfo.size` bytes are read from it and added to the archive. You can create `TarInfo` objects directly, or by using `gettarinfo()`.

  Modifié dans la version 3.13: fileobj must be given for non-zero-sized regular files.

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

  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.

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.12: 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.12: 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.12: 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.12: 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.12: 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.12: Can be set to `None` for `extract()` and `extractall()`, causing extraction to skip applying this attribute.

TarInfo.chksum: int

  Header checksum.

TarInfo.devmajor: int

  Device major number.

TarInfo.devminor: int

  Device minor number.

TarInfo.offset: int

  The tar header starts here.

TarInfo.offset_data: int

  The file's data starts here.

TarInfo.sparse

  Sparse member information.

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)

  Ajouté dans la version 3.12.

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

  Return `True` if the `TarInfo` object is a regular file.

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

Ajouté dans la version 3.12.

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.

Avertissement

None of the available filters blocks all dangerous archive features. Never extract archives from untrusted sources without prior inspection. See also Hints for further verification.

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 `'data'` filter will be used.

  > Modifié dans la version 3.14: The default filter is set to `data`. Previously, the default was equivalent to `fully_trusted`.

- 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_IWGRP` | `S_IWOTH`).

  Return the modified `TarInfo` member.

tarfile.data_filter(member, path)

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

  - Normalize link targets (`TarInfo.linkname`) using `os.path.normpath()`. Note that this removes internal `..` components, which may change the meaning of the link if the path in `TarInfo.linkname` traverses symbolic links.

  - 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_IRUSR` | `S_IWUSR`).

    - Remove the group & other executable permission (`S_IXGRP` | `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.

  Note that this filter does not block all dangerous archive features. See Hints for further verification for details.

  Modifié dans la version 3.14: Link targets are now normalized.

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

- Disallow symbolic links if you do not need the functionality.

- 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, and so on).

- 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, but may be 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)

  ou :

      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

Ajouté 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`).

## Exemples

### Reading examples

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

    import tarfile
    tar = tarfile.open("sample.tar.gz")
    tar.extractall(filter='data')
    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 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()

### Writing examples

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)

How to create and write an archive to stdout using `sys.stdout.buffer` in the fileobj parameter in `TarFile.add()`:

    import sys
    import tarfile
    with tarfile.open("sample.tar.gz", "w|gz", fileobj=sys.stdout.buffer) as tar:
        for name in ["foo", "bar", "quux"]:
            tar.add(name)

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.

- 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. Modern tar implementations, including GNU tar, bsdtar/libarchive and star, fully support extended pax features; some old or unmaintained libraries may not, but should treat pax archives as if they were in the universally supported ustar format. It is the current default format for new 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.