Nota
¡Ayúdanos a traducir la documentación oficial de Python al Español! Puedes encontrar más información en Como contribuir. Ayuda a acercar Python a más personas de habla hispana.
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 lanzaSameFileError
.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 argumentossrc
,dst
.Distinto en la versión 3.3: Solía generarse
IOError
en lugar deOSError
. Se añadió el argumento follow_symlinks. Ahora retorna dst.Distinto en la versión 3.4: Genera
SameFileError
en lugar deError
. 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éasecopystat()
para mayor información. Sicopymode()
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 argumentossrc
,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
esTrue
,copystat()
puede modificar los bits de permiso de un enlace simbólico.Si
os.utime in os.supports_follow_symlinks
esTrue
,copystat()
puede modificar el último acceso y las veces que un enlace simbólico fue modificado.Si
os.chflags in os.supports_follow_symlinks
esTrue
,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 argumentossrc
,dst
.Distinto en la versión 3.3: Se ha añadido el argumento follow_symlinks y el soporte para atributos extendidos de Linux.
- shutil.copy(src, dst, *, follow_symlinks=True)¶
Copia el archivo src al archivo o directorio dst. src y dst deberían ser objetos tipo ruta o cadenas de caracteres (strings). Si dst especifica un directorio, el archivo será copiado en dst usando el nombre de archivo base de src. Si dst especifica un archivo que existe, será reemplazado. Retorna la ruta del archivo recién creado.
Si follow_symlinks es falso, y src es un enlace simbólico, dst se creará como enlace simbólico. Si follow_symlinks es verdadero y src es un enlace simbólico, dst será una copia del archivo al que src hace referencia.
copy()
copia los datos del archivo y el modo de permiso del archivo (véaseos.chmod()
). Otros metadatos, como los tiempos de creación y modificación de archivos, no se preservan. Para preservar todos los metadatos del archivo, usacopy2()
en su lugar.Se genera un evento de auditoría
shutil.copyfile
con argumentossrc
,dst
.Genera un evento de auditoría
shutil.copymode
con argumentossrc
,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 quecopy2()
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()
usacopystat()
para copiar todos los metadatos del archivo. Véasecopystat()
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 argumentossrc
,dst
.Genera un evento de auditoría
shutil.copystat
con argumentossrc
,dst
.Distinto en la versión 3.3: Añadido el argumento follow_symlinks, intenta copiar también los atributos del sistema de archivos extendidos (actualmente solo en Linux). Ahora retorna la ruta de acceso al archivo recién creado.
Distinto en la versión 3.8: Las llamadas a sistema de copia rápida específicas de la plataforma se pueden usar internamente para copiar el archivo de manera más eficiente. Véase la sección Operaciones de copia eficientes dependientes de la plataforma.
- shutil.ignore_patterns(*patterns)¶
Esta función de fábrica crea una función que puede ser usada como un invocable para el argumento ignore de
copytree()
, ignorando los archivos y directorios que coinciden con uno de los patrones patterns de estilo glob provistos. Véase el ejemplo siguiente.
- shutil.copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False)¶
Copia recursivamente un directorio completo que inicia en src hasta un directorio llamado dst y devuelve el directorio destino. Todos los directorios intermedios necesarios para contener dst serán creados por default.
Los permisos y los tiempos de directorios son copiados con
copystat()
; los archivos individuales son copiados usandocopy2()
.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 admitenos.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 retornaos.listdir()
. Ya quecopytree()
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 (comocopy()
).Si dirs_exist_ok es falso (el default) y dst existe, la excepción
FileExistsError
es lanzada. Si dirs_exist_ok es verdadero, la operación de copiado continuara si encuentra directorios existentes, los archivos dentro del árbol de dst serán sobreescritos por los archivos correspondientes del árbol src.Se genera un evento de auditoría
shutil.copytree
con argumentossrc
,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 para silenciar los errores de enlaces colgantes cuando symlinks es falso.
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, *, onexc=None, dir_fd=None)¶
Delete an entire directory tree; path must point to a directory (but not a symbolic link to a directory). If ignore_errors is true, errors resulting from failed removals will be ignored; if false or omitted, such errors are handled by calling a handler specified by onexc or onerror or, if both are omitted, exceptions are propagated to the caller.
Esta función puede soportar rutas relativas a descriptores de directorio.
Nota
En plataformas que admiten las funciones basadas en descriptores de archivo necesarias, una versión resistente de
rmtree()
al ataque de enlace simbólico se usa por defecto. En otras plataformas, la implementaciónrmtree()
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ónrmtree.avoids_symlink_attacks
para determinar qué caso aplica.If onexc is provided, it must be a callable that accepts three parameters: function, path, and excinfo.
The first parameter, function, is the function which raised the exception; it depends on the platform and implementation. The second parameter, path, will be the path name passed to function. The third parameter, excinfo, is the exception that was raised. Exceptions raised by onexc will not be caught.
The deprecated onerror is similar to onexc, except that the third parameter it receives is the tuple returned from
sys.exc_info()
.Genera un evento de auditoría
shutil.rmtree
con argumentospath
,dir_fd
.Distinto en la versión 3.3: Se añadió una versión resistente a los ataques de enlaces simbólicos que se usan automáticamente si la plataforma admite funciones pasadas en descriptores de archivo.
Distinto en la versión 3.8: En Windows, ya no eliminará los contenidos de un cruce de directorios antes de quitar el cruce.
Distinto en la versión 3.11: El parámetro dir_fd.
Distinto en la versión 3.12: Added the onexc parameter, deprecated onerror.
- 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 iscopy2()
. Usingcopy()
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 argumentossrc
,dst
.Distinto en la versión 3.3: Se añadió el manejo explícito de enlaces simbólicos para sistemas de archivos extranjeros, de manera que se adapta al comportamiento del mv del GNU. Ahora retorna dst.
Distinto en la versión 3.5: Se agregó el argumento de keyword copy_function.
Distinto en la versión 3.8: Las llamadas a sistema de copia rápida específicas de la plataforma se pueden usar internamente para copiar el archivo de manera más eficiente. Véase la sección Operaciones de copia eficientes dependientes de la plataforma.
Distinto en la versión 3.9: Acepta un objeto tipo ruta como src y dst.
- shutil.disk_usage(path)¶
Retorna las estadísticas de uso de disco sobre la ruta de acceso dada como un named tuple con los atributos total, used y free, que son las cantidades del espacio total, el usado y el libre, en bytes. path puede ser un archivo o un directorio.
Nota
On Unix filesystems, path must point to a path within a mounted filesystem partition. On those platforms, CPython doesn’t attempt to retrieve disk usage information from non-mounted filesystems.
Nuevo en la versión 3.3.
Distinto en la versión 3.8: En Windows, path ahora puede ser un archivo o un directorio.
Disponibilidad: Unix, Windows.
- shutil.chown(path, user=None, group=None)¶
Cambia el propietario user y/o group de la ruta dada.
user puede ser un nombre usuario de sistema o un UID (identificador de usuario); lo mismo aplica a group. Se requiere al menos un argumento.
Véase también
os.chown()
, la función subyacente.Genera un evento de auditoría
shutil.chown
con argumentospath
,user
,group
.Disponibilidad: Unix.
Nuevo en la versión 3.3.
- shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)¶
Retorna la ruta de acceso a un ejecutable que se ejecutaría si el cmd dado se invoca. Si no se invoca a cmd, retorna
None
.mode es una máscara de permiso que se pasa a
os.access()
, que determinar por defecto si el archivo existe y es ejecutable.When no path is specified, the results of
os.environ()
are used, returning either the «PATH» value or a fallback ofos.defpath
.On Windows, the current directory is prepended to the path if mode does not include
os.X_OK
. When the mode does includeos.X_OK
, the Windows APINeedCurrentDirectoryForExePathW
will be consulted to determine if the current directory should be prepended to path. To avoid consulting the current working directory for executables: set the environment variableNoDefaultCurrentDirectoryInExePath
.Also on Windows, the
PATHEXT
variable is used to resolve commands that may not already include an extension. For example, if you callshutil.which("python")
,which()
will searchPATHEXT
to know that it should look forpython.exe
within the path directories. For example, on Windows:>>> shutil.which("python") 'C:\\Python33\\python.EXE'
This is also applied when cmd is a path that contains a directory component:
>> shutil.which("C:\\Python33\\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 esbytes
, el tipo resultante también esbytes
.Distinto en la versión 3.12: On Windows, the current directory is no longer prepended to the search path if mode includes
os.X_OK
and WinAPINeedCurrentDirectoryForExePathW(cmd)
is false, else the current directory is prepended even if it is already in the search path;PATHEXT
is used now even when cmd includes a directory component or ends with an extension that is inPATHEXT
; and filenames that have no extension can now be found.
- exception shutil.Error¶
Esta excepción recopila las excepciones que se generan durante una operación de varios archivos. Para
copytree()
, el argumento de excepción es una lista de 3 tuplas (scrname, dstname, exception).
Operaciones de copia eficientes dependientes de la plataforma¶
A partir de Python 3.8, todas las funciones que incluyen una copia de archivo (copyfile()
, copy()
, copy2()
, copytree()
, y move()
) puede usar llamadas a sistema de «copia rápida» específicas a cada plataforma para poder copiar el archivo de forma más eficiente (véase bpo-33671). «copia rápida» significa que la operación de copia ocurre dentro del núcleo, evitando el uso de búferes en espacio de usuario en Python como en «outfd.write(infd.read())
».
En macOS, se usa fcopyfile para copiar el contenido del archivo (pero no los metadatos).
En Linux, se usa os.sendfile()
.
En Windows, shutil.copyfile()
usa un tamaño de búfer predeterminado más grande (1 MiB en lugar de 64 KiB) y se usa una variante de shutil.copyfileobj()
basada en memoryview()
.
Si ocurre un error en la operación de copia rápida y no se ha escrito ningún dato en el archivo de destino, entonces shutil recurrirá silenciosamente a usar la función copyfileobj()
menos eficiente internamente.
Distinto en la versión 3.8.
ejemplo de copytree¶
Un ejemplo que usa el auxiliar ignore_patterns()
:
from shutil import copytree, ignore_patterns
copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))
Esto copiará todo excepto archivos .pyc
y archivos o directorios cuyo nombre comience con tmp
.
Otro ejemplo que usa el argumento ignore para agregar una llamada a iniciar sesión:
from shutil import copytree
import logging
def _logpath(path, names):
logging.info('Working in %s', path)
return [] # nothing will be ignored
copytree(source, destination, ignore=_logpath)
ejemplo de rmtree¶
This example shows how to remove a directory tree on Windows where some of the files have their read-only bit set. It uses the onexc callback to clear the readonly bit and reattempt the remove. Any subsequent failure will propagate.
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, onexc=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ódulozlib
está disponible), «bztar» (si el módulobz2
está disponible), o «xztar» (si el módulolzma
).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 argumentosbase_name
,format
,root_dir
,base_dir
.Nota
This function is not thread-safe when custom archivers registered with
register_archive_format()
do not support the root_dir argument. In this case it temporarily changes the current working directory of the process to root_dir 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: Esta función ahora es segura para hilos durante la creación de archivos estándar
.zip
y tar.
- shutil.get_archive_formats()¶
Retorna una lista de formatos admitidos para archivado. Cada elemento de una secuencia retornada es una tupla
(name, description)
.Por defecto,
shutil
provee los siguientes formatos:zip: archivo ZIP (si el módulo
zlib
está disponible).tar: archivo tar sin comprimir. Utiliza el formato pax POSIX.1-2001 para archivos nuevos.
gztar: archivo tar comprimido con gzip (si el módulo
zlib
está disponible).bztar: archivo tar comprimido con bzip2 (si el módulo
bz2
está disponible).xztar: archivo tar comprimido con xz (si el módulo
lzma
está disponible).
Puedes registrar formatos nuevos o proporcionar tu propio archivador para cualquier formato existente, usando
register_archive_format()
.
- shutil.register_archive_format(name, function[, extra_args[, description]])¶
Registra un archivador para el formato name.
function es el invocable que se usará para desempacar archivos. El invocable recibirá el base_name del archivo para crearlo, seguido por base_dir (que cae por defecto en
os.curdir
) para comenzar a archivar desde allí. Otros argumentos se pasan como argumentos de palabras clave: owner, group, dry_run y logger (como se pasa enmake_archive()
).If function has the custom attribute
function.supports_root_dir
set toTrue
, the root_dir argument is passed as a keyword argument. Otherwise the current working directory of the process is temporarily changed to root_dir before calling function. In this casemake_archive()
is not thread-safe.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.Distinto en la versión 3.12: Added support for functions supporting the root_dir argument.
- 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 unValueError
.The keyword-only filter argument 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 argumentosfilename
,extract_dir
,format
.Advertencia
Nunca extraiga archivos de fuentes no confiables sin una inspección previa. Es posible que los archivos sean creados fuera de la ruta especificada en el argumento extract_dir, p.e. miembros que tienen nombres de archivo absolutos comenzando con "/" or nombres de archivos con dos puntos "..".
Distinto en la versión 3.7: Acepta un path-like object como filename y extract_dir.
Distinto en la versión 3.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
yLINES
respectivamente. Si la variable está definida y el valor es un entero positivo, se utiliza.Cuando
COLUMNS
oLINES
no está definido, como suele ocurrir, la terminal conectada asys.__stdout__
se consulta invocandoos.get_terminal_size()
.Si el tamaño de la terminal no se puede consultar correctamente, ya sea porque el sistema no admite consultas o porque no estamos conectados a una terminal, se usa el valor dado en el parámetro
fallback
.fallback
tiene por defecto(80, 24)
, que es el tamaño por defecto que se usa en muchos emuladores de terminal.El valor retornado es una tupla con su respectivo nombre, de tipo
os.terminal_size
.Ver también: The Single UNIX Specification, Versión 2, Other Environment Variables.
Nuevo en la versión 3.3.
Distinto en la versión 3.11: Los valores
fallback
son usados también sios.get_terminal_size()
devuelve zeros.