Source code:Lib/shutil.py
Theshutil module offers a number of high-level operations on files andcollections of files. In particular, functions are provided which support filecopying and removal. For operations on individual files, see also theos module.
Warning
Even the higher-level file copying functions (shutil.copy(),shutil.copy2()) cannot copy all file metadata.
On POSIX platforms, this means that file owner and group are lost as wellas ACLs. On Mac OS, the resource fork and other metadata are not used.This means that resources will be lost and file type and creator codes willnot be correct. On Windows, file owners, ACLs and alternate data streamsare not copied.
Copy the contents of the file-like objectfsrc to the file-like objectfdst.The integerlength, if given, is the buffer size. In particular, a negativelength value means to copy the data without looping over the source data inchunks; by default the data is read in chunks to avoid uncontrolled memoryconsumption. Note that if the current file position of thefsrc object is not0, only the contents from the current file position to the end of the file willbe copied.
Copy the contents (no metadata) of the file namedsrc to a file nameddst and returndst.src anddst are path names given as strings.dst must be the complete target file name; look atshutil.copy()for a copy that accepts a target directory path. Ifsrc anddstspecify the same file,Error is raised.
The destination location must be writable; otherwise, anOSErrorexception will be raised. Ifdst already exists, it will be replaced.Special files such as character or block devices and pipes cannot becopied with this function.
Iffollow_symlinks is false andsrc is a symbolic link,a new symbolic link will be created instead of copying thefilesrc points to.
Copy the permission bits fromsrc todst. The file contents, owner, andgroup are unaffected.src anddst are path names given as strings.Iffollow_symlinks is false, and bothsrc anddst are symbolic links,copymode() will attempt to modify the mode ofdst itself (ratherthan the file it points to). This functionality is not available on everyplatform; please seecopystat() for more information. Ifcopymode() cannot modify symbolic links on the local platform, and itis asked to do so, it will do nothing and return.
Changed in version 3.3:Addedfollow_symlinks argument.
Copy the permission bits, last access time, last modification time, andflags fromsrc todst. On Linux,copystat() also copies the“extended attributes” where possible. The file contents, owner, andgroup are unaffected.src anddst are path names given as strings.
Iffollow_symlinks is false, andsrc anddst bothrefer to symbolic links,copystat() will operate onthe symbolic links themselves rather than the files thesymbolic links refer to–reading the information from thesrc symbolic link, and writing the information to thedst symbolic link.
Note
Not all platforms provide the ability to examine andmodify symbolic links. Python itself can tell you whatfunctionality is locally available.
On platforms where some or all of this functionalityis unavailable, when asked to modify a symbolic link,copystat() will copy everything it can.copystat() never returns failure.
Please seeos.supports_follow_symlinksfor more information.
Changed in version 3.3:Addedfollow_symlinks argument and support for Linux extended attributes.
Copies the filesrc to the file or directorydst.src anddstshould be strings. Ifdst specifies a directory, the file will becopied intodst using the base filename fromsrc. Returns thepath to the newly created file.
Iffollow_symlinks is false, andsrc is a symbolic link,dst will be created as a symbolic link. Iffollow_symlinksis true andsrc is a symbolic link,dst will be a copy ofthe filesrc refers to.
copy() copies the file data and the file’s permissionmode (seeos.chmod()). Other metadata, like thefile’s creation and modification times, is not preserved.To preserve all file metadata from the original, usecopy2() instead.
Changed in version 3.3:Addedfollow_symlinks argument.Now returns path to the newly created file.
Identical tocopy() except thatcopy2()also attempts to preserve all file metadata.
Whenfollow_symlinks is false, andsrc is a symboliclink,copy2() attempts to copy all metadata from thesrc symbolic link to the newly-createddst symbolic link.However, this functionality is not available on all platforms.On platforms where some or all of this functionality isunavailable,copy2() will preserve all the metadatait can;copy2() never returns failure.
copy2() usescopystat() to copy the file metadata.Please seecopystat() for more informationabout platform support for modifying symbolic link metadata.
Changed in version 3.3:Addedfollow_symlinks argument, try to copy extendedfile system attributes too (currently Linux only).Now returns path to the newly created file.
This factory function creates a function that can be used as a callable forcopytree()‘signore argument, ignoring files and directories thatmatch one of the glob-stylepatterns provided. See the example below.
Recursively copy an entire directory tree rooted atsrc, returning thedestination directory. The destinationdirectory, named bydst, must not already exist; it will be created aswell as missing parent directories. Permissions and times of directoriesare copied withcopystat(), individual files are copied usingshutil.copy2().
Ifsymlinks is true, symbolic links in the source tree are represented assymbolic links in the new tree and the metadata of the original links willbe copied as far as the platform allows; if false or omitted, the contentsand metadata of the linked files are copied to the new tree.
Whensymlinks is false, if the file pointed by the symlink doesn’texist, a exception will be added in the list of errors raised inaError exception at the end of the copy process.You can set the optionalignore_dangling_symlinks flag to true if youwant to silence this exception. Notice that this option has no effecton platforms that don’t supportos.symlink().
Ifignore is given, it must be a callable that will receive as itsarguments the directory being visited bycopytree(), and a list of itscontents, as returned byos.listdir(). Sincecopytree() iscalled recursively, theignore callable will be called once for eachdirectory that is copied. The callable must return a sequence of directoryand file names relative to the current directory (i.e. a subset of the itemsin its second argument); these names will then be ignored in the copyprocess.ignore_patterns() can be used to create such a callable thatignores names based on glob-style patterns.
If exception(s) occur, anError is raised with a list of reasons.
Ifcopy_function is given, it must be a callable that will be used to copyeach file. It will be called with the source path and the destination pathas arguments. By default,shutil.copy2() is used, but any functionthat supports the same signature (likeshutil.copy()) can be used.
Changed in version 3.3:Copy metadata whensymlinks is false.Now returnsdst.
Changed in version 3.2:Added thecopy_function argument to be able to provide a custom copyfunction.Added theignore_dangling_symlinks argument to silent dangling symlinkserrors whensymlinks is false.
Delete an entire directory tree;path must point to a directory (but not asymbolic link to a directory). Ifignore_errors is true, errors resultingfrom failed removals will be ignored; if false or omitted, such errors arehandled by calling a handler specified byonerror or, if that is omitted,they raise an exception.
Note
On platforms that support the necessary fd-based functions a symlinkattack resistant version ofrmtree() is used by default. On otherplatforms, thermtree() implementation is susceptible to a symlinkattack: given proper timing and circumstances, attackers can manipulatesymlinks on the filesystem to delete files they wouldn’t be able to accessotherwise. Applications can use thermtree.avoids_symlink_attacksfunction attribute to determine which case applies.
Ifonerror is provided, it must be a callable that accepts threeparameters:function,path, andexcinfo.
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 tofunction. The third parameter,excinfo, will be the exception information returned bysys.exc_info(). Exceptions raised byonerror will not be caught.
Changed in version 3.3:Added a symlink attack resistant version that is used automaticallyif platform supports fd-based functions.
Recursively move a file or directory (src) to another location (dst)and return the destination.
If the destination is a directory or a symlink to a directory, thensrc ismoved inside that directory.
The destination directory must not already exist. If the destination alreadyexists but is not a directory, it may be overwritten depending onos.rename() semantics.
If the destination is on the current filesystem, thenos.rename() isused. Otherwise,src is copied (usingshutil.copy2()) todst andthen removed. In case of symlinks, a new symlink pointing to the target ofsrc will be created in or asdst andsrc will be removed.
Changed in version 3.3:Added explicit symlink handling for foreign filesystems, thus adaptingit to the behavior of GNU’smv.Now returnsdst.
Return disk usage statistics about the given path as anamed tuplewith the attributestotal,used andfree, which are the amount oftotal, used and free space, in bytes.
New in version 3.3.
Availability: Unix, Windows.
Change owneruser and/orgroup of the givenpath.
user can be a system user name or a uid; the same applies togroup. Atleast one argument is required.
See alsoos.chown(), the underlying function.
Availability: Unix.
New in version 3.3.
Return the path to an executable which would be run if the givencmd wascalled. If nocmd would be called, returnNone.
mode is a permission mask passed a toos.access(), by defaultdetermining if the file exists and executable.
When nopath is specified, the results ofos.environ() are used,returning either the “PATH” value or a fallback ofos.defpath.
On Windows, the current directory is always prepended to thepath whetheror not you use the default or provide your own, which is the behavior thecommand shell uses when finding executables. Additionaly, when finding thecmd in thepath, thePATHEXT environment variable is checked. Forexample, if you callshutil.which("python"),which() will searchPATHEXT to know that it should look forpython.exe within thepathdirectories. For example, on Windows:
>>>shutil.which("python")'C:\\Python33\\python.EXE'
New in version 3.3.
This exception collects exceptions that are raised during a multi-fileoperation. Forcopytree(), the exception argument is a list of 3-tuples(srcname,dstname,exception).
This example is the implementation of thecopytree() function, describedabove, with the docstring omitted. It demonstrates many of the other functionsprovided by this module.
defcopytree(src,dst,symlinks=False):names=os.listdir(src)os.makedirs(dst)errors=[]fornameinnames:srcname=os.path.join(src,name)dstname=os.path.join(dst,name)try:ifsymlinksandos.path.islink(srcname):linkto=os.readlink(srcname)os.symlink(linkto,dstname)elifos.path.isdir(srcname):copytree(srcname,dstname,symlinks)else:copy2(srcname,dstname)# XXX What about devices, sockets etc.?exceptOSErroraswhy:errors.append((srcname,dstname,str(why)))# catch the Error from the recursive copytree so that we can# continue with other filesexceptErroraserr:errors.extend(err.args[0])try:copystat(src,dst)exceptWindowsError:# can't copy file access times on WindowspassexceptOSErroraswhy:errors.extend((src,dst,str(why)))iferrors:raiseError(errors)
Another example that uses theignore_patterns() helper:
fromshutilimportcopytree,ignore_patternscopytree(source,destination,ignore=ignore_patterns('*.pyc','tmp*'))
This will copy everything except.pyc files and files or directories whosename starts withtmp.
Another example that uses theignore argument to add a logging call:
fromshutilimportcopytreeimportloggingdef_logpath(path,names):logging.info('Working in %s'%path)return[]# nothing will be ignoredcopytree(source,destination,ignore=_logpath)
New in version 3.2.
High-level utilities to create and read compressed and archived files are alsoprovided. They rely on thezipfile andtarfile modules.
Create an archive file (such as zip or tar) and return its name.
base_name is the name of the file to create, including the path, minusany format-specific extension.format is the archive format: one of“zip”, “tar”, “bztar” (if thebz2 module is available) or “gztar”.
root_dir is a directory that will be the root directory of thearchive; for example, we typically chdir intoroot_dir before creating thearchive.
base_dir is the directory where we start archiving from;i.e.base_dir will be the common prefix of all files anddirectories in the archive.
root_dir andbase_dir both default to the current directory.
owner andgroup are used when creating a tar archive. By default,uses the current owner and group.
logger must be an object compatible withPEP 282, usually an instance oflogging.Logger.
Return a list of supported formats for archiving.Each element of the returned sequence is a tuple(name,description)
By defaultshutil provides these formats:
You can register new formats or provide your own archiver for any existingformats, by usingregister_archive_format().
Register an archiver for the formatname.function is a callable thatwill be used to invoke the archiver.
If given,extra_args is a sequence of(name,value) pairs that will beused as extra keywords arguments when the archiver callable is used.
description is used byget_archive_formats() which returns thelist of archivers. Defaults to an empty list.
Remove the archive formatname from the list of supported formats.
Unpack an archive.filename is the full path of the archive.
extract_dir is the name of the target directory where the archive isunpacked. If not provided, the current working directory is used.
format is the archive format: one of “zip”, “tar”, or “gztar”. Or anyother format registered withregister_unpack_format(). If notprovided,unpack_archive() will use the archive file name extensionand see if an unpacker was registered for that extension. In case none isfound, aValueError is raised.
Registers an unpack format.name is the name of the format andextensions is a list of extensions corresponding to the format, like.zip for Zip files.
function is the callable that will be used to unpack archives. Thecallable will receive the path of the archive, followed by the directorythe archive must be extracted to.
When provided,extra_args is a sequence of(name,value) tuples thatwill be passed as keywords arguments to the callable.
description can be provided to describe the format, and will be returnedby theget_unpack_formats() function.
Unregister an unpack format.name is the name of the format.
Return a list of all registered formats for unpacking.Each element of the returned sequence is a tuple(name,extensions,description).
By defaultshutil provides these formats:
You can register new formats or provide your own unpacker for any existingformats, by usingregister_unpack_format().
In this example, we create a gzip’ed tar-file archive containing all filesfound in the.ssh directory of the user:
>>>fromshutilimportmake_archive>>>importos>>>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'
The resulting archive contains:
$ tar -tzvf /Users/tarek/myarchive.tar.gzdrwx------ 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
New in version 3.3.
Get the size of the terminal window.
For each of the two dimensions, the environment variable,COLUMNSandLINES respectively, is checked. If the variable is defined andthe value is a positive integer, it is used.
WhenCOLUMNS orLINES is not defined, which is the common case,the terminal connected tosys.__stdout__ is queriedby invokingos.get_terminal_size().
If the terminal size cannot be successfully queried, either becausethe system doesn’t support querying, or because we are notconnected to a terminal, the value given infallback parameteris used.fallback defaults to(80,24) which is the defaultsize used by many terminal emulators.
The value returned is a named tuple of typeos.terminal_size.
See also: The Single UNIX Specification, Version 2,Other Environment Variables.
11.8.linecache — Random access to text lines
11.10.macpath — Mac OS 9 path manipulation functions
Enter search terms or a module, class or function name.
