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: Los llamadas al sistema de copia rápida específicos 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. 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: Los llamadas al sistema de copia rápida específicos 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: Los llamadas al sistema de copia rápida específicos 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 tree entero con raíz en src en un directorio llamado dst y retorna un directorio destino. dirs_exist_ok dicta si debe generar una excepción en caso de que dst o cualquier directorio principal que falte ya exista.

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

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: Se añadió el argumento copy_function para poder proporcionar una función de copia personalizada. Se añadió el argumento ignore_dangling_symlinks a los errores de enlaces colgantes silenciosos cuando symlinks es falso.

Distinto en la versión 3.8: Los llamadas al sistema de copia rápida específicos 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.

If copy_function is given, it must be a callable that takes two arguments src and dst, and will be used to copy src to dst 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: Los llamadas al sistema de copia rápida específicos 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.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

Starting from Python 3.8, all functions involving a file copy (copyfile(), copy(), copy2(), copytree(), and move()) may use platform-specific «fast-copy» syscalls in order to copy the file more efficiently (see bpo-33671). «fast-copy» means that the copying operation occurs within the kernel, avoiding the use of userspace buffers in Python as in «outfd.write(infd.read())».

En macOS, se usar 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

Este ejemplo es la implementación de la función copytree() , descrita arriba, con la cadena de documentación omitida. Demuestra muchas de las otras funciones provistas por este módulo.

def copytree(src, dst, symlinks=False):
    names = os.listdir(src)
    os.makedirs(dst)
    errors = []
    for name in names:
        srcname = os.path.join(src, name)
        dstname = os.path.join(dst, name)
        try:
            if symlinks and os.path.islink(srcname):
                linkto = os.readlink(srcname)
                os.symlink(linkto, dstname)
            elif os.path.isdir(srcname):
                copytree(srcname, dstname, symlinks)
            else:
                copy2(srcname, dstname)
            # XXX What about devices, sockets etc.?
        except OSError as why:
            errors.append((srcname, dstname, str(why)))
        # catch the Error from the recursive copytree so that we can
        # continue with other files
        except Error as err:
            errors.extend(err.args[0])
    try:
        copystat(src, dst)
    except OSError as why:
        # can't copy file access times on Windows
        if why.winerror is None:
            errors.extend((src, dst, str(why)))
    if errors:
        raise Error(errors)

Otro 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 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 is a directory that will be the root directory of the archive, all paths in the archive will be relative to it; for example, we typically chdir into root_dir before creating the archive.

base_dir is the directory where we start archiving from; i.e. base_dir will be the common prefix of all files and directories in the archive. base_dir must be given relative to root_dir. See Archiving example with base_dir for how to use base_dir and root_dir together.

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 POSIX.1-2001 formato pax 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.8.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.8.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

Archiving example with base_dir

In this example, similar to the one above, we show how to use make_archive(), but this time with the usage of base_dir. We now have the following directory structure:

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

In the final archive, please_add.txt should be included, but do_not_add.txt should not. Therefore we use the following:

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

Listing the files in the resulting archive gives us:

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

See also: The Single UNIX Specification, Version 2, Other Environment Variables.

Nuevo en la versión 3.3.