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

   On platforms that are neither Posix nor Cygwin, TemporaryFile is an
   alias for 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)

   This function operates exactly as "TemporaryFile()" does, except
   that the file is guaranteed to have a visible name in the file
   system (on Unix, the directory entry is not unlinked).  That name
   can be retrieved from the "name" attribute of the returned file-
   like object.  Whether the name can be used to open the file a
   second time, while the named temporary file is still open, varies
   across platforms (it can be so used on Unix; it cannot on Windows).
   If *delete* is true (the default), the file is deleted as soon as
   it is closed. 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.

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

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

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

   This class operates exactly as "TemporaryFile()" does, except that
   data is spooled in memory until the file size exceeds *max_size*,
   or until the file's "fileno()" method is called, at which point the
   contents are written to disk and operation proceeds as with
   "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 un
   argumento "size".

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

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

   This class securely creates a temporary directory using the same
   rules as "mkdtemp()". The resulting object can be used as a context
   manager (see Ejemplos).  On completion of the context or
   destruction of the temporary directory object, the newly created
   temporary directory and all its contents are removed from the
   filesystem.

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

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

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

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