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

   Copia los contenidos del objeto de tipo archivo *fsrc* en el objeto
   *fdst*. El valor entero *length*, si está indicado, es el tamaño
   del búfer. En particular, un valor *length* negativo significa
   copiar los datos sin recorrer los datos de origen en fragmentos;
   los datos se leen en fragmentos en forma predeterminada para evitar
   el consumo de memoria incontrolado. Nótese que si la posición
   actual del archivo del objeto *fsrc* es distinto de cero, solo se
   copiarán el contenido desde la posición actual del archivo hasta el
   final.

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

   Copia los contenidos (sin metadatos) del archivo *src* en un
   archivo  denominado *dst* y retorna *dst* de la manera más eficaz
   posible. *src* y *dst* son objetos de tipo ruta o nombres de ruta
   dados como cadenas de caracteres.

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

   Copia los bits de permiso de *src* a *dst*. Los contenidos, el
   propietario y el grupo no se ven afectados. *src* y *dst* son
   objetos tipo ruta o nombres de ruta dados como cadenas de
   caracteres. Si *follow_symlinks* es falso, y tanto *src* como *dst*
   son enlaces simbólicos, "copymode()" intentará modificar el modo de
   *dst* (y no el archivo al que apunta). Esta funcionalidad no está
   disponible en todas las plataformas; véase "copystat()" para mayor
   información. Si "copymode()" no puede modificar los enlaces
   simbólicos de la plataforma local y se le solicita hacerlo, no hará
   nada y retornará.

   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)

   Copia los bits de permiso, la última hora de acceso, la última hora
   de modificación y las *flags* desde *src* a *dst*. En Linux,
   "copystat()" también copia los "atributos extendidos" siempre que
   sea posible. Los contenidos, el propietario y el grupo del archivo
   no se ven afectados. *src* y *dst* son objetos de tipo a ruta o
   nombres de ruta dados como cadenas de caracteres.

   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)

   Copies the file *src* to the file or directory *dst*.  *src* and
   *dst* should be *path-like objects* or strings.  If *dst* specifies
   a directory, the file will be copied into *dst* using the base
   filename from *src*. If *dst* specifies a file that already exists,
   it will be replaced. Returns the path to the newly created file.

   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.

   When *follow_symlinks* is false, and *src* is a symbolic link,
   "copy2()" attempts to copy all metadata from the *src* symbolic
   link to the newly created *dst* symbolic link. However, this
   functionality is not available on all platforms. On platforms where
   some or all of this functionality is unavailable, "copy2()" will
   preserve all the metadata it can; "copy2()" never raises an
   exception because it cannot preserve file metadata.

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

   Recursively copy an entire directory tree rooted at *src* to a
   directory named *dst* and return the destination directory.  All
   intermediate directories needed to contain *dst* will also be
   created by 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()").

   If *dirs_exist_ok* is false (the default) and *dst* already exists,
   a "FileExistsError" is raised. If *dirs_exist_ok* is true, the
   copying operation will continue if it encounters existing
   directories, and files within the *dst* tree will be overwritten by
   corresponding files from the *src* tree.

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

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

   Distinto en la versión 3.2: Added the *copy_function* argument to
   be able to provide a custom copy function. Added the
   *ignore_dangling_symlinks* argument to silence dangling symlinks
   errors when *symlinks* is false.

   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.

   Nuevo en la versión 3.8: El parámetro *dirs_exist_ok*.

shutil.rmtree(path, ignore_errors=False, onerror=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.

   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 argumento "path".

   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.

   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)

   Mueve de forma recursiva un archivo o directorio (*src*) a otra
   ubicación (*dst*) y retorna el destino.

   Si el destino es un directorio existente, entonces *src* se mueve
   dentro de ese directorio. Si el destino existe pero no es un
   directorio, puede sobrescribirse dependiendo de la semántica
   "os.rename()".

   Si el destino está en el sistema de archivos actual, entonces se
   usa "os.rename()". De lo contrario, *src* se copia en *dst* usando
   *copy_function y luego se elimina. En el caso de los enlaces
   simbólicos, se creará un enlace simbólico nuevo que apunta al
   destino de *src* en o como *dst* y será eliminado.

   Si *copy_function* se proporciona, debe ser un invocable que toma
   dos argumentos *src* y *dst*, y se usará para copiar *src* a *dest*
   si no se puede usar "os.rename()". Si el origen es un directorio,
   se invoca "copytree()" y se le pasa "copy_function()". El
   *copy_function* por defecto es "copy2()". El uso de "copy()" como
   *copy_function* permite que el movimiento se realice correctamente
   cuando no es posible copiar los metadatos también, a expensas de no
   copiar ninguno de los metadatos.

   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.

   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.

   Cuando no se especifica *path*, se usan los resultados de
   "os.environ()" y se retorna el valor de "PATH" o una reserva de
   "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*
---------------------

An example that uses the "ignore_patterns()" helper:

   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* es el nombre del archivo a crear, incluyendo la ruta,
   menos cualquier extensión que sea específica de formato. *format*
   es el formato de archivo: uno de *zip* (si el módulo "zlib" está
   disponible), "tar", "gztar" (si el módulo "zlib" está disponible),
   "bztar" (si el módulo "bz2" está disponible), o "xztar" (si el
   módulo "lzma").

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

     This function is not thread-safe when custom archivers registered
     with "register_archive_format()" are used.  In this case it
     temporarily changes the current working directory of the process
     to perform archiving.

   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: This function is now made thread-
   safe during creation of standard ".zip" and tar archives.

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.10.12, 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:

     Never extract archives from untrusted sources without prior
     inspection. It is possible that files are created outside of the
     path specified in the *extract_dir* argument, e.g. members that
     have absolute filenames starting with "/" or filenames with two
     dots "..".

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

   Distinto en la versión 3.10.12: 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.
