"shutil" --- Operaciones de archivos de alto nivel
**************************************************

Código fuente: Lib/shutil.py

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

El módulo "shutil" ofrece varias operaciones de alto nivel en archivos
y colecciones de archivos. En particular, provee funciones que dan
soporte a la copia y remoción de archivos. Para operaciones en
archivos individuales, véase también el módulo "os".

Advertencia:

  Incluso las funciones de copia de archivos de nivel superior
  ("shutil.copy()", "shutil.copy2()") no pueden copiar todos los
  metadatos del archivo.En las plataformas POSIX, esto significa que
  tanto el propietario como el grupo del archivo se pierden, al igual
  que las ACLs (*access control lists* o lista de control de acceso).
  En Mac OS, la bifurcación (*fork*) de recursos y de otros metadatos
  no se utilizan. Esto quiere decir que los recursos se perderán y que
  el tipo de archivo y los códigos de creador no serán correctos. En
  Windows, los propietarios de archivos, las ACLs y secuencias de
  datos alternativas no se copian.


Operaciones de directorios y archivos
=====================================

shutil.copyfileobj(fsrc, fdst[, length])

   Copy the contents of the *file-like object* *fsrc* to the file-like
   object *fdst*. The integer *length*, if given, is the buffer size.
   In particular, a negative *length* value means to copy the data
   without looping over the source data in chunks; by default the data
   is read in chunks to avoid uncontrolled memory consumption. Note
   that if the current file position of the *fsrc* object is not 0,
   only the contents from the current file position to the end of the
   file will be copied.

shutil.copyfile(src, dst, *, follow_symlinks=True)

   Copy the contents (no metadata) of the file named *src* to a file
   named *dst* and return *dst* in the most efficient way possible.
   *src* and *dst* are *path-like objects* or path names given as
   strings.

   *dst* debe ser el nombre completo del archivo destino; véase
   "shutil.copy()" para una copia que acepta una ruta de directorio
   destino. Si *src* y *dst* refieren al mismo archivo, se lanza
   "SameFileError".

   El local de destino debe tener permisos de escritura; de lo
   contrario, se genera una excepción "OSError". Si *dst* ya existe,
   se reemplazará. Los archivos especiales, como los dispositivos de
   caracteres o de bloques y *pipes*, no se pueden copiar con esta
   función.

   Si *follow_symlinks* es falso y *src* es un enlace simbólico, un
   enlace simbólico nuevo se creará en lugar de copiar el archivo al
   que *src* apunta.

   Se genera un evento de auditoría "shutil.copyfile" con argumentos
   "src", "dst".

   Distinto en la versión 3.3: Solía generarse "IOError" en lugar de
   "OSError". Se añadió el argumento *follow_symlinks*. Ahora retorna
   *dst*.

   Distinto en la versión 3.4: Genera "SameFileError" en lugar de
   "Error". Dado que la primera es una subclase de la segunda, el
   cambio es compatible con versiones anteriores.

   Distinto en la versión 3.8: Las llamadas a sistema de copia rápida
   específicas de la plataforma se pueden usar internamente para
   copiar el archivo de manera más eficiente. Véase la sección
   Operaciones de copia eficientes dependientes de la plataforma.

exception shutil.SameFileError

   Esta excepción se genera si el origen y destino en "copyfile()" son
   el mismo archivo.

   Nuevo en la versión 3.4.

shutil.copymode(src, dst, *, follow_symlinks=True)

   Copy the permission bits from *src* to *dst*.  The file contents,
   owner, and group are unaffected.  *src* and *dst* are *path-like
   objects* or path names given as strings. If *follow_symlinks* is
   false, and both *src* and *dst* are symbolic links, "copymode()"
   will attempt to modify the mode of *dst* itself (rather than the
   file it points to).  This functionality is not available on every
   platform; please see "copystat()" for more information.  If
   "copymode()" cannot modify symbolic links on the local platform,
   and it is asked to do so, it will do nothing and return.

   Genera un evento de auditoría "shutil.copymode" con argumentos
   "src", "dst".

   Distinto en la versión 3.3: Se añadió el argumento
   *follow_symlinks*.

shutil.copystat(src, dst, *, follow_symlinks=True)

   Copy the permission bits, last access time, last modification time,
   and flags from *src* to *dst*.  On Linux, "copystat()" also copies
   the "extended attributes" where possible.  The file contents,
   owner, and group are unaffected.  *src* and *dst* are *path-like
   objects* or path names given as strings.

   Si *follow_symlinks* es falso, y *src* y *dst* hacen referencia los
   enlaces simbólicos, "copystat()" funcionará con los enlaces
   simbólicos en lugar de en los archivos a los que estos se refieren:
   leer la información del enlace simbólico *src* y escribirla en el
   enlace simbólico *dst*.

   Nota:

     No todas las plataformas proporcionan la capacidad de examinar y
     modificar enlaces simbólicos. Python puede indicarte qué
     funcionalidad está disponible localmente.

     * Si "os.chmod in os.supports_follow_symlinks" es "True",
       "copystat()" puede modificar los bits de permiso de un enlace
       simbólico.

     * Si "os.utime in os.supports_follow_symlinks" es "True",
       "copystat()" puede modificar el último acceso y las veces que
       un enlace simbólico fue modificado.

     * Si "os.chflags in os.supports_follow_symlinks" es "True",
       "copystat()" puede modificar las flags de un enlace simbólico.
       ("os.chflags" no está disponible en todas las plataformas.)

     En plataformas donde parte o toda esta funcionalidad no está
     disponible, cuando se le pida modificar un enlace simbólico,
     "copystat()" copiará todo lo que pueda. "copystat()" nunca
     retorna un error.Véase "os.supports_follow_symlinks" para más
     información.

   Genera un evento de auditoría "shutil.copystat" con argumentos
   "src", "dst".

   Distinto en la versión 3.3: Se ha añadido el argumento
   *follow_symlinks* y el soporte para atributos extendidos de Linux.

shutil.copy(src, dst, *, follow_symlinks=True)

   Copia el archivo *src* al archivo o directorio *dst*. *src* y *dst*
   deberían ser *objetos tipo ruta* o cadenas de caracteres
   (*strings*). Si *dst* especifica un directorio, el archivo será
   copiado en *dst* usando el nombre de archivo base de *src*. Si
   *dst* especifica un archivo que existe, será reemplazado. Retorna
   la ruta del archivo recién creado.

   Si *follow_symlinks* es falso, y *src* es un enlace simbólico,
   *dst* se creará como enlace simbólico. Si *follow_symlinks* es
   verdadero y *src* es un enlace simbólico, *dst* será una copia del
   archivo al que *src* hace referencia.

   "copy()" copia los datos del archivo y el modo de permiso del
   archivo (véase "os.chmod()"). Otros metadatos, como los tiempos de
   creación y modificación de archivos, no se preservan. Para
   preservar todos los metadatos del archivo, usa "copy2()" en su
   lugar.

   Se genera un evento de auditoría "shutil.copyfile" con argumentos
   "src", "dst".

   Genera un evento de auditoría "shutil.copymode" con argumentos
   "src", "dst".

   Distinto en la versión 3.3: Se ha añadido el argumento
   *follow_symlinks*. Ahora retorna la ruta de acceso al archivo
   recién creado.

   Distinto en la versión 3.8: Las llamadas a sistema de copia rápida
   específicas de la plataforma se pueden usar internamente para
   copiar el archivo de manera más eficiente. Véase la sección
   Operaciones de copia eficientes dependientes de la plataforma.

shutil.copy2(src, dst, *, follow_symlinks=True)

   Idéntico a "copy()" , excepto que "copy2()" también intenta
   conservar los metadatos del archivo.

   Cuando *follow_symlinks* es falso, y *src* es un enlace simbólico,
   "copy2()" intenta copiar todos los metadatos del enlace simbólico
   *src* en el enlace simbólico *dst* recién creado. Sin embargo, esta
   funcionalidad no está disponible en todas las plataformas. En las
   plataformas donde parte o toda esta funcionalidad no está
   disponible, "copy2()" conservará todos los metadatos que pueda;
   "copy2()" nunca genera una excepción porque no puede conservar los
   metadatos del archivo.

   "copy2()" usa "copystat()" para copiar todos los metadatos del
   archivo. Véase "copystat()" para más información sobre la
   compatibilidad con la plataforma para modificar los metadatos del
   enlace simbólico.

   Se genera un evento de auditoría "shutil.copyfile" con argumentos
   "src", "dst".

   Genera un evento de auditoría "shutil.copystat" con argumentos
   "src", "dst".

   Distinto en la versión 3.3: Añadido el argumento *follow_symlinks*,
   intenta copiar también los atributos del sistema de archivos
   extendidos (actualmente solo en Linux). Ahora retorna la ruta de
   acceso al archivo recién creado.

   Distinto en la versión 3.8: Las llamadas a sistema de copia rápida
   específicas de la plataforma se pueden usar internamente para
   copiar el archivo de manera más eficiente. Véase la sección
   Operaciones de copia eficientes dependientes de la plataforma.

shutil.ignore_patterns(*patterns)

   Esta función de fábrica crea una función que puede ser usada como
   un invocable para el argumento *ignore* de "copytree()", ignorando
   los archivos y directorios que coinciden con uno de los patrones
   *patterns* de estilo glob provistos. Véase el ejemplo siguiente.

shutil.copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False)

   Copia recursivamente un directorio completo que inicia en *src*
   hasta un directorio llamado *dst* y devuelve el directorio destino.
   Todos los directorios intermedios necesarios para contener *dst*
   serán creados por default.

   Los permisos y los tiempos de directorios son copiados con
   "copystat()"; los archivos individuales son copiados usando
   "copy2()".

   Si *symlinks* es verdadero, los enlaces simbólicos en el árbol de
   origen son representados como enlaces simbólicos en el árbol nuevo
   y los metadatos de los enlaces originales serán copiados mientras
   la plataforma lo permita; si es falso o se omite, los contenidos y
   los metadatos de los archivos vinculados se copiarán en el árbol
   nuevo.

   Cuando *symlinks* es falso y el archivo al que apunta no exista, se
   agrega una excepción a la lista de errores generados en una
   excepción "Error" al final del proceso de copia. Puedes establecer
   la marca opcional *ignore_dangling_symlinks* en verdadero si deseas
   silenciar esa excepción. Ten en cuenta que esta opción no tiene
   efecto en plataformas que no admiten "os.symlink()".

   Si se proporciona *ignore*, debe ser un invocable que recibirá como
   argumentos el directorio visitado por "copytree()" y una lista de
   sus contenidos, tal como los retorna "os.listdir()". Ya que
   "copytree()" se invoca recursivamente, el invocable *ignore* se
   llamará una vez por cada directorio que se copia. El invocable debe
   retornar una secuencia de directorio y de nombres de archivo en
   relación con el directorio actual (es decir, un subconjunto de los
   elementos en su segundo argumento); estos nombres serán ignorados
   en el proceso de copia. "ignore_patterns()" se pueden usar para
   crear un invocable que ignora los nombres basados en patrones de
   estilo gob.

   Si ocurren excepciones, se genera, un "Error" con una lista de
   razones.

   Si *copy_function* está dado, debe ser un invocable que se usará
   para copiar cada archivo. Se le invocará con la ruta de origen y la
   ruta de destino como argumentos. Por defecto, se usa "copy2()",
   pero se puede usar cualquier función que admita la misma (como
   "copy()").

   Si *dirs_exist_ok* es falso (el default) y *dst* existe, la
   excepción "FileExistsError" es lanzada. Si *dirs_exist_ok* es
   verdadero, la operación de copiado continuara si encuentra
   directorios existentes, los archivos dentro del árbol de *dst*
   serán sobreescritos por los archivos correspondientes del árbol
   *src*.

   Se genera un evento de auditoría "shutil.copytree" con argumentos
   "src", "dst".

   Distinto en la versión 3.2: Se añadió el argumento *copy_function*
   para poder proporcionar una función de copia personalizada. Se
   añadió el argumento *ignore_dangling_symlinks* para silenciar los
   errores de enlaces colgantes cuando *symlinks* es falso.

   Distinto en la versión 3.3: Copia los metadatos cuando *symlinks*
   es falso. Ahora retorna *dst*.

   Distinto en la versión 3.8: Las llamadas a sistema de copia rápida
   específicas de la plataforma se pueden usar internamente para
   copiar el archivo de manera más eficiente. Véase la sección
   Operaciones de copia eficientes dependientes de la plataforma.

   Distinto en la versión 3.8: Added the *dirs_exist_ok* parameter.

shutil.rmtree(path, ignore_errors=False, onerror=None, *, dir_fd=None)

   Elimina un árbol de directorios entero; *path* debe apuntar a un
   directorio (pero no a un enlace simbólico a un directorio). Si
   *ignore_errors* es verdadero, se eliminarán los errores que
   resulten de eliminaciones fallidas; si es falso u omitido, estos
   errores se controlan invocando un controlador especificado por
   *onerror* o, si este es omitido, se genera una excepción.

   Esta función puede soportar rutas relativas a descriptores de
   directorio.

   Nota:

     En plataformas que admiten las funciones basadas en descriptores
     de archivo necesarias, una versión resistente de "rmtree()" al
     ataque de enlace simbólico se usa por defecto. En otras
     plataformas, la implementación "rmtree()" es susceptible a un
     ataque de enlace simbólico; dados el tiempo y las circunstancias
     adecuados, los atacantes pueden manipular los enlaces simbólicos
     en el sistema de archivos para eliminar archivos a los que no
     podrían acceder de otra manera. Las aplicaciones pueden usar el
     atributo de función "rmtree.avoids_symlink_attacks" para
     determinar qué caso aplica.

   Si se *onerror* está dado, debe ser un invocable que acepte tres
   parámetros: *function*, *path*, y *excinfo*.

   El primer parámetro, *function*, es la función que generó la
   excepción; depende de la plataforma y de la implementación. El
   segundo parámetro, *path*, será el nombre de ruta pasado a
   *function*. El tercer parámetro, *excinfo*, será la información de
   la excepción retornada por "sys.exc_info()". Las excepciones
   generadas por *onerror* no serán tomadas.

   Genera un evento de auditoría "shutil.rmtree" con argumentos
   "path", "dir_fd".

   Distinto en la versión 3.3: Se añadió una versión resistente a los
   ataques de enlaces simbólicos que se usan automáticamente si la
   plataforma admite funciones pasadas en descriptores de archivo.

   Distinto en la versión 3.8: En Windows, ya no eliminará los
   contenidos de un cruce de directorios antes de quitar el cruce.

   Distinto en la versión 3.11: El parámetro *dir_fd*.

   rmtree.avoids_symlink_attacks

      Indica si la plataforma actual y la implementación proporciona
      una versión de "rmtree()" resistente al ataque de enlace
      simbólico. Actualmente, esto solo sucede para plataformas que
      admitan funciones de acceso a directorios basadas en
      descriptores de archivo.

      Nuevo en la versión 3.3.

shutil.move(src, dst, copy_function=copy2)

   Recursively move a file or directory (*src*) to another location
   and return the destination.

   If *dst* is an existing directory or a symlink to a directory, then
   *src* is moved inside that directory. The destination path in that
   directory must not already exist.

   If *dst* already exists but is not a directory, it may be
   overwritten depending on "os.rename()" semantics.

   If the destination is on the current filesystem, then "os.rename()"
   is used. Otherwise, *src* is copied to the destination using
   *copy_function* and then removed.  In case of symlinks, a new
   symlink pointing to the target of *src* will be created as the
   destination and *src* will be removed.

   If *copy_function* is given, it must be a callable that takes two
   arguments, *src* and the destination, and will be used to copy
   *src* to the destination if "os.rename()" cannot be used.  If the
   source is a directory, "copytree()" is called, passing it the
   *copy_function*. The default *copy_function* is "copy2()".  Using
   "copy()" as the *copy_function* allows the move to succeed when it
   is not possible to also copy the metadata, at the expense of not
   copying any of the metadata.

   Genera un evento de auditoría "shutil.move" con argumentos "src",
   "dst".

   Distinto en la versión 3.3: Se añadió el manejo explícito de
   enlaces simbólicos para sistemas de archivos extranjeros, de manera
   que se adapta al comportamiento del **mv** del GNU. Ahora retorna
   *dst*.

   Distinto en la versión 3.5: Se agregó el argumento de keyword
   *copy_function*.

   Distinto en la versión 3.8: Las llamadas a sistema de copia rápida
   específicas de la plataforma se pueden usar internamente para
   copiar el archivo de manera más eficiente. Véase la sección
   Operaciones de copia eficientes dependientes de la plataforma.

   Distinto en la versión 3.9: Acepta un *objeto tipo ruta* como *src*
   y *dst*.

shutil.disk_usage(path)

   Retorna las estadísticas de uso de disco sobre la ruta de acceso
   dada como un *named tuple* con los atributos *total*, *used* y
   *free*, que son las cantidades del espacio total, el usado y el
   libre, en bytes. *path* puede ser un archivo o un directorio.

   Nota:

     On Unix filesystems, *path* must point to a path within a
     **mounted** filesystem partition. On those platforms, CPython
     doesn't attempt to retrieve disk usage information from non-
     mounted filesystems.

   Nuevo en la versión 3.3.

   Distinto en la versión 3.8: En Windows, *path* ahora puede ser un
   archivo o un directorio.

   Disponibilidad: Unix, Windows.

shutil.chown(path, user=None, group=None)

   Cambia el propietario *user* y/o *group* de la *ruta* dada.

   *user* puede ser un nombre usuario de sistema o un UID
   (identificador de usuario); lo mismo aplica a *group*. Se requiere
   al menos un argumento.

   Véase también "os.chown()", la función subyacente.

   Genera un evento de auditoría "shutil.chown" con argumentos "path",
   "user", "group".

   Disponibilidad: Unix.

   Nuevo en la versión 3.3.

shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)

   Retorna la ruta de acceso a un ejecutable que se ejecutaría si el
   *cmd* dado se invoca. Si no se invoca a *cmd*, retorna "None".

   *mode* es una máscara de permiso que se pasa a "os.access()", que
   determinar por defecto si el archivo existe y es ejecutable.

   When no *path* is specified, the results of "os.environ()" are
   used, returning either the "PATH" value or a fallback of
   "os.defpath".

   En Windows, el directorio actual siempre se antepone a *path*,
   independientemente de si usa el valor predeterminado o si tú
   provees el tuyo propio, que es el comportamiento que el comando
   *shell* usa cuando encuentra ejecutables. Además, al encontrar el
   *cmd* en el *path*, se comprueba la variable de entorno "PATHEXT".
   Por ejemplo, si invocas "shutil.which("python")", "which()" buscará
   "PATHEXT" para saber si debe buscar "python.exe" dentro de los
   directorios *path*. Por ejemplo, en Windows:

      >>> shutil.which("python")
      'C:\\Python33\\python.EXE'

   Nuevo en la versión 3.3.

   Distinto en la versión 3.8: Ahora se acepta el tipo "bytes". Si el
   tipo *cmd* es "bytes", el tipo resultante también es "bytes".

exception shutil.Error

   Esta excepción recopila las excepciones que se generan durante una
   operación de varios archivos. Para "copytree()", el argumento de
   excepción es una lista de 3 tuplas (*scrname*, *dstname*,
   *exception*).


Operaciones de copia eficientes dependientes de la plataforma
-------------------------------------------------------------

A partir de Python 3.8, todas las funciones que incluyen una copia de
archivo ("copyfile()", "copy()", "copy2()", "copytree()", y "move()")
puede usar llamadas a sistema de "copia rápida" específicas a cada
plataforma para poder copiar el archivo de forma más eficiente (véase
bpo-33671). "copia rápida" significa que la operación de copia ocurre
dentro del núcleo, evitando el uso de búferes en espacio de usuario en
Python como en ""outfd.write(infd.read())"".

En macOS, se usa fcopyfile para copiar el contenido del archivo (pero
no los metadatos).

En Linux, se usa "os.sendfile()".

En Windows, "shutil.copyfile()" usa un tamaño de búfer predeterminado
más grande (1 MiB en lugar de 64 KiB) y se usa una variante de
"shutil.copyfileobj()" basada en "memoryview()".

Si ocurre un error en la operación de copia rápida y no se ha escrito
ningún dato en el archivo de destino, entonces shutil recurrirá
silenciosamente a usar la función "copyfileobj()" menos eficiente
internamente.

Distinto en la versión 3.8.


ejemplo de *copytree*
---------------------

Un ejemplo que usa el auxiliar "ignore_patterns()":

   from shutil import copytree, ignore_patterns

   copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))

Esto copiará todo excepto archivos ".pyc" y archivos o directorios
cuyo nombre comience con "tmp".

Otro ejemplo que usa el argumento *ignore* para agregar una llamada a
iniciar sesión:

   from shutil import copytree
   import logging

   def _logpath(path, names):
       logging.info('Working in %s', path)
       return []   # nothing will be ignored

   copytree(source, destination, ignore=_logpath)


ejemplo de rmtree
-----------------

Este ejemplo muestra como eliminar un árbol de directorio en Windows
donde algunos de los archivos tienen configurado su *bit* de sólo
lectura. Usa la *onerror callback* para limpiar el *bit* de sólo
lectura y reintentar eliminarlo. Cualquier fallo que le siga, se
propagará.

   import os, stat
   import shutil

   def remove_readonly(func, path, _):
       "Clear the readonly bit and reattempt the removal"
       os.chmod(path, stat.S_IWRITE)
       func(path)

   shutil.rmtree(directory, onerror=remove_readonly)


Operaciones de archivado
========================

Nuevo en la versión 3.2.

Distinto en la versión 3.5: Se agregó soporte para el formato *xztar*.

Se proveen también las utilidades de alto nivel para crear y leer
archivos comprimidos y archivados. Utilizan para esto los módulos
"zipfile" y "tarfile".

shutil.make_archive(base_name, format[, root_dir[, base_dir[, verbose[, dry_run[, owner[, group[, logger]]]]]]])

   Crea un documento de archivado (como zip o tar) y retorna su
   nombre.

   *base_name* is the name of the file to create, including the path,
   minus any format-specific extension.

   *format* is the archive format: one of "zip" (if the "zlib" module
   is available), "tar", "gztar" (if the "zlib" module is available),
   "bztar" (if the "bz2" module is available), or "xztar" (if the
   "lzma" module is available).

   *root_dir* es un directorio que será el directorio raíz del
   archivo, todas las rutas en el archivo serán relativas a él; por
   ejemplo, típicamente nos cambiaremos de directorio (*chdir*) a
   *root_dir* antes de crear el archivo.

   *base_dir* es el directorio desde donde iniciamos el archivado;
   i.e, *base_dir* será el prefijo común para todos los archivos y
   directorios en el archivo. *base_dir* debe ser dado de forma
   relativa a *root_dir*. En Ejemplo de archivado con base_dir se ve
   un ejemplo de cómo usar *base_dir* y *root_dir* juntos.

   *root_dir* y *base_dir* irán por defecto al directorio actual.

   If *dry_run* es verdadero, no se crea un archivo, pero las
   operaciones que se ejecutarán están registradas en *logger*.

   *owner* y *group* se usan al crear un archivador tar. Por defecto,
   usa el propietario y el grupo actual.

   *logger* debe ser un objeto compatible con  **PEP 282**, usualmente
   una instancia de "logging.Logger".

   El argumento *verbose* está fuera de uso y es obsoleto.

   Genera un evento de auditoría "shutil.make_archive" con argumentos
   "base_name", "format", "root_dir", "base_dir".

   Nota:

     Esta función no es segura para hilos cuando son usados archivos
     personalizados registrados con "register_archive_format()". En
     este caso temporalmente cambia el directorio de trabajo actual
     del proceso para realizar el archivado.

   Distinto en la versión 3.8: El formato de *pax* moderno
   (POSIX.1-2001) se usa ahora en lugar del formato de legado GNU para
   archivadores creados con "format="tar"".

   Distinto en la versión 3.10.6: Esta función ahora es segura para
   hilos durante la creación de archivos estándar ".zip" y tar.

shutil.get_archive_formats()

   Retorna una lista de formatos admitidos para archivado. Cada
   elemento de una secuencia retornada es una tupla "(name,
   description)".

   Por defecto, "shutil" provee los siguientes formatos:

   * *zip*: archivo ZIP (si el módulo "zlib" está disponible).

   * *tar*: archivo tar sin comprimir. Utiliza el formato pax
     POSIX.1-2001 para archivos nuevos.

   * *gztar*: archivo tar comprimido con gzip (si el módulo "zlib"
     está disponible).

   * *bztar*: archivo tar comprimido con bzip2 (si el módulo "bz2"
     está disponible).

   * *xztar*: archivo tar comprimido con xz (si el módulo "lzma" está
     disponible).

   Puedes registrar formatos nuevos o proporcionar tu propio
   archivador para cualquier formato existente, usando
   "register_archive_format()".

shutil.register_archive_format(name, function[, extra_args[, description]])

   Registra un archivador para el formato *name*.

   *function* es el invocable que se usará para desempacar archivos.
   El invocable recibirá el *base_name* del archivo para crearlo,
   seguido por *base_dir* (que cae por defecto en "os.curdir") para
   comenzar a archivar desde allí. Otros argumentos se pasan como
   argumentos de palabras clave: *owner*, *group*, *dry_run* y
   *logger* (como se pasa en "make_archive()").

   Si está dado, *extra_args* es una secuencia de pares "(name,
   value)"  que se usarán como argumentos de palabras clave extra
   cuando se usa el archivador invocable.

   *description* se usa por "get_archive_formats()" que retorna la
   lista de archivadores. Cae por defecto en una cadena de caracteres
   vacía.

shutil.unregister_archive_format(name)

   Elimina el formato de archivo *name* de la lista de formatos
   admitidos.

shutil.unpack_archive(filename[, extract_dir[, format[, filter]]])

   Desempaqueta un archivo. *filename* es la ruta completa del
   archivo.

   *extract_dir* es el nombre del directorio donde se desempaca el
   archivo. Si no está provisto, se usa el nombre del directorio
   actual.

   *format* es el formato de archivo: uno de "zip", "tar", "gztar",
   "bztar", or "xztar". O cualquier otra formato registrado con
   "register_unpack_format()". Si no está provisto, "unpack_archive()"
   usará la extensión de archivo del archivador y verá si se registró
   un desempacador para esa extensión. En caso de que no se encuentre
   ninguno, se genera un "ValueError".

   The keyword-only *filter* argument, which was added in Python
   3.11.4, is passed to the underlying unpacking function. For zip
   files, *filter* is not accepted. For tar files, it is recommended
   to set it to "'data'", unless using features specific to tar and
   UNIX-like filesystems. (See Extraction filters for details.) The
   "'data'" filter will become the default for tar files in Python
   3.14.

   Se genera un evento de auditoría "shutil.unpack_archive" con
   argumentos "filename", "extract_dir", "format".

   Advertencia:

     Nunca extraiga archivos de fuentes no confiables sin una
     inspección previa. Es posible que los archivos sean creados fuera
     de la ruta especificada en el argumento *extract_dir*, p.e.
     miembros que tienen nombres de archivo absolutos comenzando con
     "/" or nombres de archivos con dos puntos "..".

   Distinto en la versión 3.7: Acepta un *path-like object* como
   *filename* y *extract_dir*.

   Distinto en la versión 3.11.4: Added the *filter* argument.

shutil.register_unpack_format(name, extensions, function[, extra_args[, description]])

   Registra un formato de desempaque. *name* es el nombre del formato
   y *extensions* es una lista de extensiones que corresponden al
   formato, como ".zip" para archivos zip.

   *function* is the callable that will be used to unpack archives.
   The callable will receive:

   * the path of the archive, as a positional argument;

   * the directory the archive must be extracted to, as a positional
     argument;

   * possibly a *filter* keyword argument, if it was given to
     "unpack_archive()";

   * additional keyword arguments, specified by *extra_args* as a
     sequence of "(name, value)" tuples.

   *description* se puede proporcionar para describir el formato y
   será retornado por la función "get_unpack_formats()".

shutil.unregister_unpack_format(name)

   Anula el registro del formato de desempaque. *name* es el nombre
   del formato.

shutil.get_unpack_formats()

   Retorna una lista de todos los formatos registrados para
   desempaquetar. Cada elemento de la secuencia es una tupla "(name,
   extensions, description)".

   Por defecto, "shutil" provee los siguientes formatos:

   * *zip*: archivo zip (desempaquetar archivos comprimidos funciona
     solo si el módulo correspondiente está disponible).

   * *tar*: archivo tar sin comprimir.

   * *gztar*: archivo tar comprimido con gzip (si el módulo "zlib"
     está disponible).

   * *bztar*: archivo tar comprimido con bzip2 (si el módulo "bz2"
     está disponible).

   * *xztar*: archivo tar comprimido con xz (si el módulo "lzma" está
     disponible).

   Puedes registrar formatos nuevos o proporcionar tu propio
   desempaquetado para cualquier formato existente, usando
   "register_unpack_format()".


Ejemplo de archivado
--------------------

En este ejemplo, creamos un archivo tar de tipo gzip que contiene
todos los archivos que se encuentran en el directorio ".ssh" del
usuario:

   >>> from shutil import make_archive
   >>> import os
   >>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
   >>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))
   >>> make_archive(archive_name, 'gztar', root_dir)
   '/Users/tarek/myarchive.tar.gz'

El archivo resultante contiene:

   $ tar -tzvf /Users/tarek/myarchive.tar.gz
   drwx------ tarek/staff       0 2010-02-01 16:23:40 ./
   -rw-r--r-- tarek/staff     609 2008-06-09 13:26:54 ./authorized_keys
   -rwxr-xr-x tarek/staff      65 2008-06-09 13:26:54 ./config
   -rwx------ tarek/staff     668 2008-06-09 13:26:54 ./id_dsa
   -rwxr-xr-x tarek/staff     609 2008-06-09 13:26:54 ./id_dsa.pub
   -rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa
   -rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub
   -rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts


Ejemplo de archivado con *base_dir*
-----------------------------------

En este ejemplo, similar al de arriba, mostramos cómo usar
"make_archive()", pero esta vez utilizando *base_dir*.  Ahora tenemos
la siguiente estructura de directorios:

   $ tree tmp
   tmp
   └── root
       └── structure
           ├── content
               └── please_add.txt
           └── do_not_add.txt

En el archivo final, "please_add.txt" debería estar incluido, pero
"do_not_add.txt" no.  Por lo tanto usamos lo siguiente:

   >>> from shutil import make_archive
   >>> import os
   >>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
   >>> make_archive(
   ...     archive_name,
   ...     'tar',
   ...     root_dir='tmp/root',
   ...     base_dir='structure/content',
   ... )
   '/Users/tarek/my_archive.tar'

Listando los archivos en el archivo resultante nos da:

   $ python -m tarfile -l /Users/tarek/myarchive.tar
   structure/content/
   structure/content/please_add.txt


Consulta el tamaño de la terminal de salida
===========================================

shutil.get_terminal_size(fallback=(columns, lines))

   Obtén el tamaño de la ventana de la terminal.

   Para cada una de las dos dimensiones, se comprueba la variable de
   entorno "COLUMNS" y "LINES" respectivamente. Si la variable está
   definida y el valor es un entero positivo, se utiliza.

   Cuando "COLUMNS" o "LINES" no está definido, como suele ocurrir, la
   terminal conectada a "sys.__stdout__" se consulta invocando
   "os.get_terminal_size()".

   Si el tamaño de la terminal no se puede consultar correctamente, ya
   sea porque el sistema no admite consultas o porque no estamos
   conectados a una terminal, se usa el valor dado en el parámetro
   "fallback". "fallback" tiene por defecto "(80, 24)", que es el
   tamaño por defecto que se usa en muchos emuladores de terminal.

   El valor retornado es una tupla con su respectivo nombre, de tipo
   "os.terminal_size".

   Ver también: *The Single UNIX Specification*, Versión 2, Other
   Environment Variables.

   Nuevo en la versión 3.3.

   Distinto en la versión 3.11: Los valores "fallback" son usados
   también si "os.get_terminal_size()" devuelve zeros.
