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ées 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=None, encoding=None, newline=None, suffix=None, prefix=None, dir=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 est soit non-créé du tout, ou est supprimé 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 quelque soit la donnée qui est stockée. buffering, encoding 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).

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

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

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

tempfile.SpooledTemporaryFile(max_size=0, mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=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, or 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 ou io.StringIO (cela dépend du mode binaire ou texte spécifié) 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), juste comme un fichier normal.

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

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

Cette fonction crée de manière sécurisée un répertoire temporaire 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 du répertoire temporaire, le nouvellement crée répertoire temporaire et tout son contenu sont supprimés du système de fichier.

Le nom du répertoire peut être récupéré depuis l'attribut name de l'objet renvoyé. Quand l'objet retourné est utilisé en comme gestionnaire de contexte, le name aura pour valeur la cible spécifiée par 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().

Nouveau dans la version 3.2.

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

Creates a temporary file in the most secure manner possible. There are no race conditions in the file's creation, assuming that the platform properly implements the os.O_EXCL flag for os.open(). The file is readable and writable only by the creating user ID. If the platform uses permission bits to indicate whether a file is executable, the file is executable by no one. The file descriptor is not inherited by child processes.

Unlike TemporaryFile(), the user of mkstemp() is responsible for deleting the temporary file when done with it.

If suffix is not None, the file name will end with that suffix, otherwise there will be no suffix. mkstemp() does not put a dot between the file name and the suffix; if you need one, put it at the beginning of suffix.

If prefix is not None, the file name will begin with that prefix; otherwise, a default prefix is used. The default is the return value of gettempprefix() or gettempprefixb(), as appropriate.

If dir is not None, the file will be created in that directory; otherwise, a default directory is used. The default directory is chosen from a platform-dependent list, but the user of the application can control the directory location by setting the TMPDIR, TEMP or TMP environment variables. There is thus no guarantee that the generated filename will have any nice properties, such as not requiring quoting when passed to external commands via os.popen().

If any of suffix, prefix, and dir are not None, they must be the same type. If they are bytes, the returned name will be bytes instead of str. If you want to force a bytes return value with otherwise default behavior, pass suffix=b''.

If text is specified, it indicates whether to open the file in binary mode (the default) or text mode. On some platforms, this makes no difference.

mkstemp() returns a tuple containing an OS-level handle to an open file (as would be returned by os.open()) and the absolute pathname of that file, in that order.

Modifié dans la version 3.5: suffix, prefix, and dir may now be supplied in bytes in order to obtain a bytes return value. Prior to this, only str was allowed. suffix and prefix now accept and default to None to cause an appropriate default value to be used.

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

Creates a temporary directory in the most secure manner possible. There are no race conditions in the directory's creation. The directory is readable, writable, and searchable only by the creating user ID.

The user of mkdtemp() is responsible for deleting the temporary directory and its contents when done with it.

The prefix, suffix, and dir arguments are the same as for mkstemp().

mkdtemp() returns the absolute pathname of the new directory.

Modifié dans la version 3.5: suffix, prefix, and dir may now be supplied in bytes in order to obtain a bytes return value. Prior to this, only str was allowed. suffix and prefix now accept and default to None to cause an appropriate default value to be used.

tempfile.gettempdir()

Renvoie le nom du répertoire utilisé pour les fichiers temporaires. Cela définit 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()

Same as gettempdir() but the return value is in bytes.

Nouveau dans la version 3.5.

tempfile.gettempprefix()

Return the filename prefix used to create temporary files. This does not contain the directory component.

tempfile.gettempprefixb()

Same as gettempprefix() but the return value is in bytes.

Nouveau dans la version 3.5.

The module uses a global variable to store the name of the directory used for temporary files returned by gettempdir(). It can be set directly to override the selection process, but this is discouraged. All functions in this module take a dir argument which can be used to specify the directory and this is the recommended approach.

tempfile.tempdir

When set to a value other than None, this variable defines the default value for the dir argument to the functions defined in this module.

If tempdir is None (the default) at any call to any of the above functions except gettempprefix() it is initialized following the algorithm described in gettempdir().

Exemples

Here are some examples of typical usage of the tempfile module:

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

Deprecated functions and variables

A historical way to create temporary files was to first generate a file name with the mktemp() function and then create a file using this name. Unfortunately this is not secure, because a different process may create a file with this name in the time between the call to mktemp() and the subsequent attempt to create the file by the first process. The solution is to combine the two steps and create the file immediately. This approach is used by mkstemp() and the other functions described above.

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

Obsolète depuis la version 2.3: Use mkstemp() instead.

Return an absolute pathname of a file that did not exist at the time the call is made. The prefix, suffix, and dir arguments are similar to those of mkstemp(), except that bytes file names, suffix=None and prefix=None are not supported.

Avertissement

Use of this function may introduce a security hole in your program. By the time you get around to doing anything with the file name it returns, someone else may have beaten you to the punch. mktemp() usage can be replaced easily with NamedTemporaryFile(), passing it the delete=False parameter:

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