tempfile — Generar archivos y directorios temporales

Código fuente: Lib/tempfile.py

Este módulo crea archivos y directorios temporales. Funciona en todas las plataformas soportadas. TemporaryFile, NamedTemporaryFile, TemporaryDirectory, y SpooledTemporaryFile son interfaces de alto nivel que proporcionan limpieza automática y se pueden utilizar como administradores de contexto. mkstemp() y mkdtemp() son funciones de nivel inferior que requieren limpieza manual.

Todas las funciones y constructores invocables por el usuario toman argumentos adicionales que permiten el control directo sobre la ubicación y el nombre de los archivos y directorios temporales. Los nombres de archivos utilizados por este módulo incluyen una cadena de caracteres aleatorios que permite que esos archivos se creen de forma segura en directorios temporales compartidos. Para mantener la compatibilidad con versiones anteriores, el orden de argumentos es algo extraño; se recomienda utilizar argumentos nombrados para mayor claridad.

El módulo define los siguientes elementos invocables por el usuario:

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

Retorna un file-like object que se puede usar como área de almacenamiento temporal. El archivo se crea de forma segura, usando las mismas reglas que mkstemp(). Este se destruirá tan pronto como se cierre (incluido un cierre implícito cuando el objeto es recolectado como basura). Bajo Unix, la entrada de directorio para el archivo no se crea en lo absoluto o se elimina inmediatamente después de crear el archivo. Otras plataformas no soportan esto; tu código no debería depender en un archivo temporal creado con esta función teniendo o no un nombre visible en el sistema de archivos.

El objeto resultante puede usarse como un administrador de contexto (ver Ejemplos). Al completar el contexto o la destrucción del objeto de archivo, el archivo temporal se eliminará del sistema de archivos.

El parámetro mode por defecto es 'w+b' para que el archivo creado pueda leerse y escribirse sin cerrarse. El modo binario se utiliza para que se comporte consistentemente en todas las plataformas sin tener en cuenta los datos que se almacenan. buffering, encoding, errors y newline se interpretan como en open().

Los parámetros dir, prefix y suffix tienen el mismo significado y valores predeterminados de mkstemp().

El objeto retornado es un objeto de archivo verdadero en las plataformas POSIX. En otras plataformas, es un objeto similar a un archivo cuyo atributo file es el objeto de archivo verdadero subyacente.

El indicador os.O_TMPFILE se usa si está disponible (específico de Linux, requiere el kernel de Linux 3.11 o posterior).

En plataformas que no son ni Posix ni Cygwin, TemporaryFile es un alias de NamedTemporaryFile.

Lanza un evento de auditoria tempfile.mkstemp con argumento fullpath.

Distinto en la versión 3.5: El indicador os.O_TMPFILE ahora se usa si está disponible.

Distinto en la versión 3.8: Se agregó el parámetro errors.

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

This function operates exactly as TemporaryFile() does, except the following differences:

  • This function returns a file that is guaranteed to have a visible name in the file system.

  • To manage the named file, it extends the parameters of TemporaryFile() with delete and delete_on_close parameters that determine whether and how the named file should be automatically deleted.

The returned object is always a file-like object whose file attribute is the underlying true file object. This file-like object can be used in a with statement, just like a normal file. The name of the temporary file can be retrieved from the name attribute of the returned file-like object. On Unix, unlike with the TemporaryFile(), the directory entry does not get unlinked immediately after the file creation.

If delete is true (the default) and delete_on_close is true (the default), the file is deleted as soon as it is closed. If delete is true and delete_on_close is false, the file is deleted on context manager exit only, or else when the file-like object is finalized. Deletion is not always guaranteed in this case (see object.__del__()). If delete is false, the value of delete_on_close is ignored.

Therefore to use the name of the temporary file to reopen the file after closing it, either make sure not to delete the file upon closure (set the delete parameter to be false) or, in case the temporary file is created in a with statement, set the delete_on_close parameter to be false. The latter approach is recommended as it provides assistance in automatic cleaning of the temporary file upon the context manager exit.

Opening the temporary file again by its name while it is still open works as follows:

  • On POSIX the file can always be opened again.

  • On Windows, make sure that at least one of the following conditions are fulfilled:

    • delete is false

    • additional open shares delete access (e.g. by calling os.open() with the flag O_TEMPORARY)

    • delete is true but delete_on_close is false. Note, that in this case the additional opens that do not share delete access (e.g. created via builtin open()) must be closed before exiting the context manager, else the os.unlink() call on context manager exit will fail with a PermissionError.

On Windows, if delete_on_close is false, and the file is created in a directory for which the user lacks delete access, then the os.unlink() call on exit of the context manager will fail with a PermissionError. This cannot happen when delete_on_close is true because delete access is requested by the open, which fails immediately if the requested access is not granted.

En POSIX (solo), un proceso que finaliza abruptamente con SIGKILL no puede eliminar automáticamente ningún NamedTemporaryFiles que se haya creado.

Lanza un evento de auditoria tempfile.mkstemp con argumento fullpath.

Distinto en la versión 3.8: Se agregó el parámetro errors.

Distinto en la versión 3.12: Added delete_on_close parameter.

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

Esta clase opera exactamente como lo hace TemporaryFile(), excepto que los datos se almacenan en la memoria hasta que el tamaño del archivo excede max_size, o hasta que el método del archivo fileno() se llama, en ese momento los contenidos se escriben en el disco y la operación continúa como con TemporaryFile().

El archivo resultante tiene un método adicional, rollover(), que hace que el archivo se transfiera a un archivo en el disco, independientemente de su tamaño.

El objeto retornado es un objeto tipo archivo cuyo atributo _file es un objeto io.BytesIO o io.TextIOWrapper (dependiendo de si se especificó binario o texto mode) o un objeto de archivo verdadero, dependiendo de si: se ha llamado a rollover(). Este objeto similar a un archivo se puede usar en una sentencia with, al igual que un archivo normal.

Distinto en la versión 3.3: el método truncate ahora acepta el argumento size.

Distinto en la versión 3.8: Se agregó el parámetro errors.

Distinto en la versión 3.11: Implementa completamente las clases base abstractas io.BufferedIOBase y io.TextIOBase (dependiendo de si se especificó modo binario o de texto).

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

Esta clase crea de forma segura un directorio temporal utilizando las mismas reglas que mkdtemp(). El objeto resultante puede usarse como administrador de contexto (ver Ejemplos). Al finalizar el contexto o la destrucción del objeto de directorio temporal, el directorio temporal recién creado y todo su contenido se eliminan del sistema de archivos.

El nombre del directorio se puede obtener del atributo name del objeto retornado. Cuando el objeto retornado se usa como administrador de contexto, el name se asignará al objetivo de la cláusula as en la sentencia with, si hay una.

El directorio se puede limpiar explícitamente llamando al método cleanup(). Si ignore_cleanup_errors es verdadero, se ignorará cualquier excepción no controlada durante la limpieza explícita o implícita (como un PermissionError al eliminar archivos abiertos en Windows) y los elementos extraíbles restantes se eliminarán según el «mejor esfuerzo». De lo contrario, se lanzarán errores en cualquier contexto que se realice la limpieza (la llamada cleanup(), al salir del gestor de contexto, cuando el objeto se recolecta como basura o durante el cierre del intérprete).

The delete parameter can be used to disable cleanup of the directory tree upon exiting the context. While it may seem unusual for a context manager to disable the action taken when exiting the context, it can be useful during debugging or when you need your cleanup behavior to be conditional based on other logic.

Lanza un evento de auditoria tempfile.mkdtemp con argumento fullpath.

Nuevo en la versión 3.2.

Distinto en la versión 3.10: Se agregó el parámetro ignore_cleanup_errors.

Distinto en la versión 3.12: Added the delete parameter.

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

Crea un archivo temporal de la manera más segura posible. No hay condiciones de carrera en la creación del archivo, suponiendo que la plataforma implemente correctamente el indicador os.O_EXCL para os.open(). El archivo se puede leer y escribir solo mediante el ID del usuario que lo crea. Aunque la plataforma utilice bits de permiso para indicar si un archivo es ejecutable, nadie puede ejecutar el archivo. El descriptor de archivo no es heredado por los procesos hijos.

A diferencia de TemporaryFile(), el usuario de mkstemp() es responsable de eliminar el archivo temporal cuando haya terminado con él.

Si suffix no es None, el nombre del archivo terminará con ese sufijo, de lo contrario no habrá sufijo. mkstemp() no pone un punto entre el nombre del archivo y el sufijo; si necesita uno, póngalo al comienzo del suffix.

Si prefix no es None, el nombre del archivo comenzará con ese prefijo; de lo contrario, se usa un prefijo predeterminado. El valor predeterminado es el valor de retorno de gettempprefix() o gettempprefixb(), según corresponda.

Si dir no es None, el archivo se creará en ese directorio; de lo contrario, se usa un directorio predeterminado. El directorio predeterminado se elige de una lista dependiente de la plataforma, pero el usuario de la aplicación puede controlar la ubicación del directorio configurando las variables de entorno TMPDIR, TEMP o TMP . Por lo tanto, no hay garantía de que el nombre de archivo generado tenga buenas propiedades, como no requerir comillas cuando se pasa a comandos externos a través de os.popen().

Si alguno de los argumentos suffix, prefix, y dir no son None, estos deben ser del mismo tipo. Si son bytes, el nombre retornado será bytes en lugar de str. Si desea forzar un valor de retorno de bytes con un comportamiento predeterminado, pase suffix=b’’.

Si se especifica text y es verdadero, el archivo se abre en modo texto. De lo contrario, (por defecto) el archivo se abre en modo binario.

mkstemp() retorna una tupla que contiene un controlador de nivel de sistema operativo a un archivo abierto (como sería retornado por os.open()) y la ruta absoluta de ese archivo, en ese orden.

Lanza un evento de auditoria tempfile.mkstemp con argumento fullpath.

Distinto en la versión 3.5: suffix, prefix, y dir ahora se pueden suministrar en bytes para obtener el valor de retorno en bytes. Antes de esto, solo str se permitía. suffix y prefix ahora aceptan y por defecto None para hacer que se use un valor predeterminado apropiado.

Distinto en la versión 3.6: El parámetro dir ahora acepta un path-like object.

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

Crea un directorio temporal de la manera más segura posible. No hay condiciones de carrera en la creación del directorio. El directorio se puede leer, escribir y buscar solo por el ID del usuario creador.

El usuario de mkdtemp() es responsable de eliminar el directorio temporal y su contenido cuando haya terminado con él.

Los argumentos prefix, suffix, y dir son los mismos que para mkstemp().

mkdtemp() retorna la ruta absoluta del nuevo directorio.

Lanza un evento de auditoria tempfile.mkdtemp con argumento fullpath.

Distinto en la versión 3.5: suffix, prefix, y dir ahora se pueden suministrar en bytes para obtener el valor de retorno en bytes. Antes de esto, solo str se permitía. suffix y prefix ahora aceptan y por defecto None para hacer que se use un valor predeterminado apropiado.

Distinto en la versión 3.6: El parámetro dir ahora acepta un path-like object.

Distinto en la versión 3.12: mkdtemp() now always returns an absolute path, even if dir is relative.

tempfile.gettempdir()

Retorna el nombre del directorio utilizado para archivos temporales. Esto define el valor predeterminado para el argumento dir para todas las funciones en este módulo.

Python busca en una lista estándar de directorios para encontrar uno dentro del cual el usuario pueda crear archivos. La lista es:

  1. El directorio nombrado por la variable de entorno TMPDIR.

  2. El directorio nombrado por la variable de entorno TEMP.

  3. El directorio nombrado por la variable de entorno TMP.

  4. Una ubicación especifica de la plataforma:

    • En Windows, los directorios C:\TEMP, C:\TMP, \TEMP, y \TMP, en ese orden.

    • En todas las otras plataformas, los directorios /tmp, /var/tmp, y /usr/tmp, en ese orden.

  5. Y como última alternativa, el directorio de trabajo actual.

El resultado de la búsqueda es cacheada, vea la descripción de tempdir abajo.

Distinto en la versión 3.10: Siempre retorna str. Anteriormente retornaría cualquier valor tempdir independientemente del tipo siempre que no fuera None.

tempfile.gettempdirb()

Igual a gettempdir() pero el valor retornado es en bytes.

Nuevo en la versión 3.5.

tempfile.gettempprefix()

Retorna el prefijo del nombre de archivo utilizado para crear archivos temporales. Este no contiene el componente de directorio.

tempfile.gettempprefixb()

Igual que gettempprefix() pero el valor retornado es en bytes.

Nuevo en la versión 3.5.

El módulo utiliza una variable global para almacenar el nombre del directorio utilizado para los archivos temporales retornados por gettempdir(). Se puede configurar directamente para sobrescribir el proceso de selección, pero esto no se recomienda. Todas las funciones en este módulo toman un argumento dir que puede usarse para especificar el directorio. Este es el enfoque recomendado que no toma por sorpresa otro código inesperado al cambiar el comportamiento global de la API.

tempfile.tempdir

Cuando se establece en un valor distinto de None, esta variable define el valor predeterminado para el argumento dir para las funciones definidas en este módulo, incluyendo su tipo, bytes o str. No puede ser un path-like object.

Si tempdir es None (por defecto) en cualquier llamada a cualquiera de las funciones anteriores excepto gettempprefix() se inicializa siguiendo el algoritmo descrito en gettempdir().

Nota

Tenga en cuenta que si establece tempdir en un valor de bytes, hay un efecto secundario desagradable: el tipo de retorno global predeterminado de mkstemp() y mkdtemp() cambia a bytes cuando no se proporcionan argumentos explícitos prefix, suffix o dir de tipo str. Por favor, no escriba código esperando o dependiendo de esto. Este comportamiento incómodo se mantiene por compatibilidad con la implementación histórica.

Ejemplos

Estos son algunos ejemplos del uso típico del módulo 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 file using a context manager
# close the file, use the name to open the file again
>>> with tempfile.TemporaryFile(delete_on_close=False) as fp:
...    fp.write(b'Hello world!')
...    fp.close()
# the file is closed, but not removed
# open the file again by using its name
...    with open(fp.name) as f
...        f.read()
b'Hello world!'
>>>
# file is now 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

Funciones y variables deprecadas

Una forma histórica de crear archivos temporales era generar primero un nombre de archivo con la función mktemp() y luego crear un archivo con este nombre. Desafortunadamente, esto no es seguro, porque un proceso diferente puede crear un archivo con este nombre en el tiempo entre la llamada a mktemp() y el intento posterior de crear el archivo mediante el primer proceso. La solución es combinar los dos pasos y crear el archivo de inmediato. Este enfoque es utilizado por mkstemp() y las otras funciones descritas anteriormente.

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

Obsoleto desde la versión 2.3: Utilice mkstemp() en su lugar.

Retorna el nombre de la ruta absoluta de un archivo que no existía en el momento en que se realiza la llamada. Los argumentos prefix, suffix y dir son similares a los de mkstemp(), excepto los nombres de archivo de bytes, suffix=None y prefix=None no son soportados.

Advertencia

El uso de esta función puede introducir un agujero de seguridad en su programa. Para cuando llegues a hacer algo con el nombre de archivo que retorna, alguien más pudo haberse adelantado. El uso de mktemp() se puede reemplazar fácilmente con NamedTemporaryFile(), pasándole el parámetro 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