"tempfile" — Génération de fichiers et répertoires temporaires
**************************************************************

**Code source :** Lib/tempfile.py

======================================================================

Ce module crée des fichiers et répertoires temporaires. Il fonctionne
sur toutes les plateformes supportées. "TemporaryFile",
"NamedTemporaryFile", "TemporaryDirectory", et "SpooledTemporaryFile"
sont des interfaces haut-niveau qui fournissent un nettoyage
automatique et peuvent être utilisées comme gestionnaire de contexte.
"mkstemp()" et "mkdtemp()" sont des fonctions bas-niveau qui
nécessitent un nettoyage manuel.

Toutes les fonctions et constructeurs appelables par l'utilisateur ont
des arguments additionnels qui permettent de contrôler directement le
chemin et le nom des répertoires et fichiers. Les noms de fichiers
utilisés par ce module incluent une chaîne de caractères aléatoires
qui leur permet d'être créés de manière sécurisée dans des répertoires
temporaires partagés. Afin de maintenir la compatibilité descendante,
l'ordre des arguments est quelque peu étrange ; pour des questions de
clarté, il est recommandé d'utiliser les arguments nommés.

Le module définit les éléments suivants pouvant être appelés par
l'utilisateur :

tempfile.TemporaryFile(mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

   Renvoie un *objet fichier* qui peut être utilisé comme une zone de
   stockage temporaire. Le fichier est créé de manière sécurisé,
   utilisant les mêmes règles que "mkstemp()". Il sera détruit dès
   qu'il sera fermé (y compris lorsque le fichier est implicitement
   fermé quand il est collecté par le ramasse-miette). Sous Unix,
   l'entrée du répertoire n'est soit pas du tout créée, ou est
   supprimée immédiatement après sa création. Les autres plateformes
   ne gèrent pas cela, votre code ne doit pas compter sur un fichier
   temporaire créé en utilisant cette fonction ayant ou non un nom
   visible sur le système de fichier.

   L'objet résultat peut être utilisé comme un gestionnaire de
   contexte (voir Exemples). Une fois le contexte ou la destruction de
   l'objet fichier terminé, le fichier temporaire sera supprimé du
   système de fichiers.

   Le paramètre *mode* vaut par défaut "'w+b'" afin que le fichier
   créé puisse être lu et écrit sans être fermé. Le mode binaire est
   utilisé afin que le comportement soit le même sur toutes les
   plateformes quelle que soit la donnée qui est stockée. *buffering*,
   *encoding*, *errors* et *newline* sont interprétés de la même façon
   que pour "open()".

   Les paramètres *dir*, *prefix* et *suffix* ont la même
   signification et même valeur par défaut que "mkstemp()".

   L'objet renvoyé est un véritable fichier sur les plateformes POSIX.
   Sur les autres plateformes, un objet fichier-compatible est
   retourné où l'attribut "file" est le véritable fichier.

   L'option "os.O_TMPFILE" est utilisé s'il est disponible et
   fonctionne (Linux exclusivement, nécessite un noyau Linux 3.11 ou
   plus).

   Lève un évènement d'audit "tempfile.mkstemp" avec comme argument
   "fullpath".

   Modifié dans la version 3.5: L'option "os.O_TMPFILE" est maintenant
   utilisé si disponible.

   Modifié dans la version 3.8: Le paramètre *errors* a été ajouté.

tempfile.NamedTemporaryFile(mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True, *, errors=None)

   Cette fonction fonctionne exactement comme "TemporaryFile()", à la
   différence qu'il est garanti que le fichier soit visible dans le
   système de fichier (sur Unix, l'entrée du répertoire est
   supprimée). Le nom peut être récupéré depuis l'attribut "name" de
   l'objet fichier-compatible retourné. Le fait que le nom puisse être
   utilisé pour ouvrir le fichier une seconde fois, tant que le
   fichier temporaire nommé est toujours ouvert, varie entre les
   plateformes (cela peut l'être sur Unix, mais c'est impossible sur
   Windows NT et plus). Si *delete* est vrai (valeur par défaut), le
   fichier est supprimé dès qu'il est fermé. L'objet retourné est
   toujours un objet fichier-compatible où l'attribut "file" est le
   véritable fichier. L'objet fichier-compatible peut être utilisé
   dans un gestionnaire de contexte (instruction "with"), juste comme
   un fichier normal.

   Lève un évènement d'audit "tempfile.mkstemp" avec comme argument
   "fullpath".

   Modifié dans la version 3.8: Le paramètre *errors* a été ajouté.

tempfile.SpooledTemporaryFile(max_size=0, mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

   Cette fonction se comporte exactement comme "TemporaryFile()", à
   l'exception que les données sont stockées en mémoire jusqu'à ce que
   leur taille dépasse *max_size*, ou que la méthode "fileno()" soit
   appelée. À ce moment, le contenu est écrit sur disque et le
   fonctionnement redevient similaire à celui de "TemporaryFile()".

   Le fichier renvoyé a une méthode supplémentaire, "rollover()", qui
   provoque la mise en écriture sur disque quelque soit la taille du
   fichier.

   L'objet renvoyé est un objet fichier-compatible où l'attribut
   "_file" est soit un objet "io.BytesIO" soit un objet
   "io.TextIOWrapper" (en fonction du *mode*) soit un véritable
   fichier, si la fonction "rollover()" a été appelée. Cet objet
   fichier-compatible peut être utilisé dans un gestionnaire de
   contexte (instruction "with"), comme un fichier normal.

   Modifié dans la version 3.3: la méthode de troncature accepte
   maintenant un argument "size".

   Modifié dans la version 3.8: Le paramètre *errors* a été ajouté.

tempfile.TemporaryDirectory(suffix=None, prefix=None, dir=None)

   Cette fonction crée un répertoire temporaire de manière sécurisée
   utilisant les mêmes règles que "mkdtemp()". L'objet renvoyé peut
   être utilisé comme un gestionnaire de contexte (voir Exemples). À
   la sortie du contexte d’exécution ou à la destruction de l'objet,
   le répertoire temporaire et tout son contenu sont supprimés du
   système de fichiers.

   Le nom du répertoire peut être récupéré via l'attribut "name" de
   l'objet renvoyé. Quand l'objet renvoyé est utilisé comme
   gestionnaire de contexte, l'attribut "name" sera lié au nom donné à
   la clause "as" de l'instruction "with", si elle est spécifiée.

   Le répertoire peut être explicitement nettoyé en appelant la
   méthode "cleanup()".

   Lève un évènement d'audit "tempfile.mkdtemp" avec comme argument
   "fullpath".

   Nouveau dans la version 3.2.

tempfile.mkstemp(suffix=None, prefix=None, dir=None, text=False)

   Crée un fichier temporaire de la manière la plus sécurisée qui
   soit. Il n'y a pas d'accès concurrent ("race condition") au moment
   de la création du fichier, en supposant que la plateforme
   implémente correctement l'option "os.O_EXCL" pour "os.open()". Le
   fichier est seulement accessible en lecture et écriture par l'ID de
   l'utilisateur créateur. Si la plateforme utilise des bits de
   permissions pour indiquer si le fichier est exécutable, alors le
   fichier n'est exécutable par personne. Le descripteur de fichier
   n'est pas hérité par les processus fils.

   À la différence de "TemporaryFile()", l'utilisateur de "mkstemp()"
   est responsable de la suppression du fichier temporaire quand il
   n'en a plus besoin.

   Si *suffix* ne vaut pas "None", le nom de fichier se terminera avec
   ce suffixe, sinon il n'y aura pas de suffixe. "mkstemp()" ne met
   pas de point entre le nom du fichier et le suffixe. Si vous en avez
   besoin, mettez le point au début de *suffix*.

   Si *prefix* ne vaut pas "None", le nom de fichier commencera avec
   ce préfixe, sinon un préfixe par défaut est utilisé. La valeur par
   défaut est la valeur retournée par "gettempprefix()" ou
   "gettempprefixb()".

   Si *dir* ne vaut pas "None", le fichier sera créé dans ce
   répertoire, autrement, un répertoire par défaut sera utilisé. Le
   répertoire par défaut est choisi depuis une liste dépendante de la
   plateforme, mais l'utilisateur de l'application peut contrôler
   l'emplacement du répertoire en spécifiant les variables
   d'environnement *TMPDIR*, *TEMP* ou *TMP*. Il n'y a pas de garantie
   que le nom de fichier généré aura de bonnes propriétés telles que
   ne pas avoir besoin de le mettre entre guillemets lorsque celui-ci
   est passé à des commandes externes via "os.popen()".

   Si l'un des paramètres *suffix*, *prefix* et *dir* n'est pas
   "None", ils doivent être du même type. S'ils sont de type "bytes",
   le nom renvoyée sera de type "bytes" plutôt que de type "str". Si
   vous voulez forcer la valeur renvoyée en "bytes", passez
   "suffix=b''".

   Le fichier est ouvert en mode binaire, sauf si *text* est mis à
   vrai, auquel cas il est ouvert en mode textuel.

   "mkstemp()" renvoie un n-uplet contenant un descripteur (*handle*
   en anglais) au niveau du système d'exploitation vers un fichier
   ouvert (le même que renvoie "os.open()") et le chemin d'accès
   absolu de ce fichier, dans cet ordre.

   Lève un évènement d'audit "tempfile.mkstemp" avec comme argument
   "fullpath".

   Modifié dans la version 3.5: *suffix*, *prefix*, et *dir* peuvent
   maintenant être spécifiés en "bytes" pour obtenir un résultat en
   "bytes". Avant cela, le type "str" était le seul autorisé. *suffix*
   et *prefix* acceptent maintenant la valeur par défaut "None" pour
   que la valeur par défaut appropriée soit utilisée.

   Modifié dans la version 3.6: Le paramètre *dir* accepte un *objet
   fichier-compatible*.

tempfile.mkdtemp(suffix=None, prefix=None, dir=None)

   Crée un répertoire temporaire de la manière la plus sécurisée qu'il
   soit. Il n'y a pas d'accès concurrent ("race condition") au moment
   de la création du répertoire. Le répertoire est accessible en
   lecture, en écriture, et son contenu lisible uniquement pour l'ID
   de l'utilisateur créateur.

   L'utilisateur de "mkdtemp()" est responsable de la suppression du
   répertoire temporaire et de son contenu lorsqu'il n'en a plus
   besoin.

   Les arguments *prefix*, *suffix*, et *dir* sont les mêmes que pour
   "mkstemp()".

   "mkdtemp()" renvoie le chemin absolu du nouveau répertoire.

   Lève un évènement d'audit "tempfile.mkdtemp" avec comme argument
   "fullpath".

   Modifié dans la version 3.5: *suffix*, *prefix*, et *dir* peuvent
   maintenant être spécifiés en "bytes" pour obtenir un résultat en
   "bytes". Avant cela, le type "str" était le seul autorisé. *suffix*
   et *prefix* acceptent maintenant la valeur par défaut "None" pour
   que la valeur par défaut appropriée soit utilisée.

   Modifié dans la version 3.6: Le paramètre *dir* accepte un *objet
   fichier-compatible*.

tempfile.gettempdir()

   Renvoie le nom du répertoire utilisé pour les fichiers temporaires.
   C'est la valeur par défaut pour l'argument *dir* de toutes les
   fonctions de ce module.

   Python cherche un répertoire parmi une liste standard de
   répertoires dans lequel l'utilisateur final peut créer des
   fichiers. La liste est :

   1. Le répertoire correspondant à la variable d'environnement
      "TMPDIR".

   2. Le répertoire correspondant à la variable d'environnement
      "TEMP".

   3. Le répertoire correspondant à la variable d'environnement "TMP".

   4. Un emplacement dépendant à la plateforme :

      * Sur Windows, les répertoires "C:\TEMP", "C:\TMP", "\TEMP", et
        "\TMP", dans cet ordre.

      * Sur toutes les autres plate-formes, les répertoires "/tmp",
        "/var/tmp", et "/usr/tmp", dans cet ordre.

   5. En dernier ressort, le répertoire de travail courant.

   Le résultat de cette recherche est mis en cache, voir la
   description de "tempdir" dessous.

tempfile.gettempdirb()

   Similaire à "gettempdir()" mais la valeur retournée est en *bytes*.

   Nouveau dans la version 3.5.

tempfile.gettempprefix()

   Renvoie le préfixe de nom de fichier utilisé pour créer les
   fichiers temporaires. Cela ne contient pas le nom du répertoire.

tempfile.gettempprefixb()

   Similaire à "gettempprefix()" mais la valeur retournée est en
   *bytes*.

   Nouveau dans la version 3.5.

Le module utilise une variable globale pour stocker le nom du
répertoire utilisé pour les fichiers temporaires renvoyés par
"gettempdir()". Vous pouvez directement utiliser la variable globale
pour surcharger le processus de sélection, mais ceci est déconseillé.
Toutes les fonctions de ce module prennent un argument *dir* qui peut
être utilisé pour spécifier le répertoire. Il s'agit de la méthode
recommandée.

tempfile.tempdir

   Quand une valeur autre que "None" est spécifiée, cette variable
   définit la valeur par défaut pour l'argument *dir* des fonctions
   définies dans ce module.

   Si "tempdir" vaut "None" (par défaut) pour n'importe quelle des
   fonctions ci-dessus, sauf "gettempprefix()", la variable est
   initialisée suivant l'algorithme décrit dans "gettempdir()".


Exemples
========

Voici quelques exemples classiques d'utilisation du module "tempfile"
:

   >>> import tempfile

   # create a temporary file and write some data to it
   >>> fp = tempfile.TemporaryFile()
   >>> fp.write(b'Hello world!')
   # read data from file
   >>> fp.seek(0)
   >>> fp.read()
   b'Hello world!'
   # close the file, it will be removed
   >>> fp.close()

   # create a temporary file using a context manager
   >>> with tempfile.TemporaryFile() as fp:
   ...     fp.write(b'Hello world!')
   ...     fp.seek(0)
   ...     fp.read()
   b'Hello world!'
   >>>
   # file is now closed and removed

   # create a temporary directory using the context manager
   >>> with tempfile.TemporaryDirectory() as tmpdirname:
   ...     print('created temporary directory', tmpdirname)
   >>>
   # directory and contents have been removed


Fonctions et variables obsolètes
================================

Historiquement, la méthode pour créer des fichiers temporaires
consistait à générer un nom de fichier avec la fonction "mktemp()"
puis créer un fichier en utilisant ce nom. Malheureusement, cette
méthode n'est pas fiable car un autre processus peut créer un fichier
avec ce nom entre l'appel à la fonction "mktemp()" et la tentative de
création de fichier par le premier processus en cours. La solution est
de combiner les deux étapes et de créer le fichier immédiatement.
Cette approche est utilisée par "mkstemp()" et les autres fonctions
décrites plus haut.

tempfile.mktemp(suffix='', prefix='tmp', dir=None)

   Obsolète depuis la version 2.3: Utilisez "mkstemp()" à la place.

   Renvoie le chemin absolu d'un fichier qui n'existe pas lorsque
   l'appel est fait. Les arguments *prefix*, *suffix*, et *dir* sont
   similaires à ceux de "mkstemp()" mais les noms de fichiers en
   *bytes*, "sufix=None" et "prefix=None" ne sont pas implémentées.

   Avertissement:

     Utiliser cette fonction peut introduire une faille de sécurité
     dans votre programme. Avant que vous n'ayez le temps de faire
     quoi que ce soit avec le nom de fichier renvoyé, quelqu'un peut
     l'utiliser. L'utilisation de "mktemp()" peut être remplacée
     facilement avec "NamedTemporaryFile()" en y passant le paramètre
     "delete=False" :

        >>> f = NamedTemporaryFile(delete=False)
        >>> f.name
        '/tmp/tmptjujjt'
        >>> f.write(b"Hello World!\n")
        13
        >>> f.close()
        >>> os.unlink(f.name)
        >>> os.path.exists(f.name)
        False
