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ée, 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-miettes). Sous Unix, soit l'entrée du répertoire n'est pas du tout créée, soit elle est supprimée immédiatement après la création du fichier. 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 fichiers.

L'objet résultat peut être utilisé comme un gestionnaire de contexte (voir Exemples). Au moment de la destruction de l'objet fichier (comme à la fin du contexte), le fichier temporaire est 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 les mêmes valeurs par défaut que dans mkstemp().

L'objet renvoyé est un véritable fichier sur les plateformes POSIX. Sur les autres plateformes, c'est un objet fichier-compatible, dont l'attribut file donne le véritable fichier.

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

Sur les plateformes qui ne sont pas POSIX ni Cygwin, TemporaryFile est un alias de NamedTemporaryFile.

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ée 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 classe fonctionne exactement comme TemporaryFile(), à la différence qu'il est garanti que le fichier soit visible dans le système de fichiers (sous Unix, l'entrée du répertoire n'est pas supprimée). Le nom peut être récupéré depuis l'attribut name de l'objet fichier-compatible renvoyé, et le vrai fichier depuis l'attribut file. 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). Si delete est vrai (valeur par défaut), le fichier est supprimé dès qu'il est fermé. L'objet fichier-compatible peut être utilisé dans un gestionnaire de contexte (instruction with), exactement 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é.

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

Cette classe 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 quelle que 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é.

class tempfile.TemporaryDirectory(suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False)

Cette classe crée un répertoire temporaire de manière sécurisée en 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 vidé explicitement avec la méthode cleanup(). Si ignore_cleanup_errors est mis à vrai, les exceptions levées lors de la vidange (explicite ou implicite) et non gérées sont ignorées, et l'opération se poursuit dans la mesure du possible. Un exemple où cela peut se produire est la suppression d'un fichier ouvert par ailleurs, qui lève PermissionError sous Windows. Si ignore_cleanup_errors est faux (comme par défaut), les exceptions se propagent dans le contexte de la vidange (que ce soit un appel à cleanup(), la sortie du gestionnaire de contexte, la suppression de l'objet par le ramasse-miettes ou l'arrêt de l'interpréteur).

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

Nouveau dans la version 3.2.

Modifié dans la version 3.10: ajout du paramètre ignore_cleanup_errors.

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 de problème d'accès concurrent (race condition en anglais) 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é est 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 une paire 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 de problème d'accès concurrent (race condition en anglais) 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 de 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.

Modifié dans la version 3.10: Cette fonction renvoie désormais systématiquement une chaîne de caractères. Auparavant, elle pouvait renvoyer la valeur de tempdir quel que soit son type tant que ce n'était pas None.

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 car elle n'interfère pas avec le code extérieur en modifiant le comportement global du module.

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, et en particulier son type (bytes ou str). Les objets fichier-compatibles ne sont pas acceptés.

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

Note

Attention, le fait de mettre tempdir à une valeur de type bytes a l'effet pervers de changer globalement en bytes le type de retour de mkstemp() et mkdtemp() lorsqu'elles sont appelées sans qu'aucun des paramètres prefix, suffix et dir ne soit de type str. Ce comportement par défaut surprenant est préservé par souci de compatibilité avec l'implémentation historique du module. Il est fortement recommandé de ne pas s'y fier.

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