This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

# `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.

  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)

  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.

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

`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.9.17, 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.9.17: 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.