1:mod:`shutil` --- High-level file operations 2============================================ 3 4.. module:: shutil 5 :synopsis: High-level file operations, including copying. 6 7.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 8.. partly based on the docstrings 9 10**Source code:** :source:`Lib/shutil.py` 11 12.. index:: 13 single: file; copying 14 single: copying files 15 16-------------- 17 18The :mod:`shutil` module offers a number of high-level operations on files and 19collections of files. In particular, functions are provided which support file 20copying and removal. For operations on individual files, see also the 21:mod:`os` module. 22 23.. warning:: 24 25 Even the higher-level file copying functions (:func:`shutil.copy`, 26 :func:`shutil.copy2`) cannot copy all file metadata. 27 28 On POSIX platforms, this means that file owner and group are lost as well 29 as ACLs. On Mac OS, the resource fork and other metadata are not used. 30 This means that resources will be lost and file type and creator codes will 31 not be correct. On Windows, file owners, ACLs and alternate data streams 32 are not copied. 33 34 35.. _file-operations: 36 37Directory and files operations 38------------------------------ 39 40.. function:: copyfileobj(fsrc, fdst[, length]) 41 42 Copy the contents of the file-like object *fsrc* to the file-like object *fdst*. 43 The integer *length*, if given, is the buffer size. In particular, a negative 44 *length* value means to copy the data without looping over the source data in 45 chunks; by default the data is read in chunks to avoid uncontrolled memory 46 consumption. Note that if the current file position of the *fsrc* object is not 47 0, only the contents from the current file position to the end of the file will 48 be copied. 49 50 51.. function:: copyfile(src, dst, *, follow_symlinks=True) 52 53 Copy the contents (no metadata) of the file named *src* to a file named 54 *dst* and return *dst* in the most efficient way possible. 55 *src* and *dst* are path-like objects or path names given as strings. 56 57 *dst* must be the complete target file name; look at :func:`~shutil.copy` 58 for a copy that accepts a target directory path. If *src* and *dst* 59 specify the same file, :exc:`SameFileError` is raised. 60 61 The destination location must be writable; otherwise, an :exc:`OSError` 62 exception will be raised. If *dst* already exists, it will be replaced. 63 Special files such as character or block devices and pipes cannot be 64 copied with this function. 65 66 If *follow_symlinks* is false and *src* is a symbolic link, 67 a new symbolic link will be created instead of copying the 68 file *src* points to. 69 70 .. audit-event:: shutil.copyfile src,dst shutil.copyfile 71 72 .. versionchanged:: 3.3 73 :exc:`IOError` used to be raised instead of :exc:`OSError`. 74 Added *follow_symlinks* argument. 75 Now returns *dst*. 76 77 .. versionchanged:: 3.4 78 Raise :exc:`SameFileError` instead of :exc:`Error`. Since the former is 79 a subclass of the latter, this change is backward compatible. 80 81 .. versionchanged:: 3.8 82 Platform-specific fast-copy syscalls may be used internally in order to 83 copy the file more efficiently. See 84 :ref:`shutil-platform-dependent-efficient-copy-operations` section. 85 86.. exception:: SameFileError 87 88 This exception is raised if source and destination in :func:`copyfile` 89 are the same file. 90 91 .. versionadded:: 3.4 92 93 94.. function:: copymode(src, dst, *, follow_symlinks=True) 95 96 Copy the permission bits from *src* to *dst*. The file contents, owner, and 97 group are unaffected. *src* and *dst* are path-like objects or path names 98 given as strings. 99 If *follow_symlinks* is false, and both *src* and *dst* are symbolic links, 100 :func:`copymode` will attempt to modify the mode of *dst* itself (rather 101 than the file it points to). This functionality is not available on every 102 platform; please see :func:`copystat` for more information. If 103 :func:`copymode` cannot modify symbolic links on the local platform, and it 104 is asked to do so, it will do nothing and return. 105 106 .. audit-event:: shutil.copymode src,dst shutil.copymode 107 108 .. versionchanged:: 3.3 109 Added *follow_symlinks* argument. 110 111.. function:: copystat(src, dst, *, follow_symlinks=True) 112 113 Copy the permission bits, last access time, last modification time, and 114 flags from *src* to *dst*. On Linux, :func:`copystat` also copies the 115 "extended attributes" where possible. The file contents, owner, and 116 group are unaffected. *src* and *dst* are path-like objects or path 117 names given as strings. 118 119 If *follow_symlinks* is false, and *src* and *dst* both 120 refer to symbolic links, :func:`copystat` will operate on 121 the symbolic links themselves rather than the files the 122 symbolic links refer to—reading the information from the 123 *src* symbolic link, and writing the information to the 124 *dst* symbolic link. 125 126 .. note:: 127 128 Not all platforms provide the ability to examine and 129 modify symbolic links. Python itself can tell you what 130 functionality is locally available. 131 132 * If ``os.chmod in os.supports_follow_symlinks`` is 133 ``True``, :func:`copystat` can modify the permission 134 bits of a symbolic link. 135 136 * If ``os.utime in os.supports_follow_symlinks`` is 137 ``True``, :func:`copystat` can modify the last access 138 and modification times of a symbolic link. 139 140 * If ``os.chflags in os.supports_follow_symlinks`` is 141 ``True``, :func:`copystat` can modify the flags of 142 a symbolic link. (``os.chflags`` is not available on 143 all platforms.) 144 145 On platforms where some or all of this functionality 146 is unavailable, when asked to modify a symbolic link, 147 :func:`copystat` will copy everything it can. 148 :func:`copystat` never returns failure. 149 150 Please see :data:`os.supports_follow_symlinks` 151 for more information. 152 153 .. audit-event:: shutil.copystat src,dst shutil.copystat 154 155 .. versionchanged:: 3.3 156 Added *follow_symlinks* argument and support for Linux extended attributes. 157 158.. function:: copy(src, dst, *, follow_symlinks=True) 159 160 Copies the file *src* to the file or directory *dst*. *src* and *dst* 161 should be strings. If *dst* specifies a directory, the file will be 162 copied into *dst* using the base filename from *src*. Returns the 163 path to the newly created file. 164 165 If *follow_symlinks* is false, and *src* is a symbolic link, 166 *dst* will be created as a symbolic link. If *follow_symlinks* 167 is true and *src* is a symbolic link, *dst* will be a copy of 168 the file *src* refers to. 169 170 :func:`~shutil.copy` copies the file data and the file's permission 171 mode (see :func:`os.chmod`). Other metadata, like the 172 file's creation and modification times, is not preserved. 173 To preserve all file metadata from the original, use 174 :func:`~shutil.copy2` instead. 175 176 .. audit-event:: shutil.copyfile src,dst shutil.copy 177 178 .. audit-event:: shutil.copymode src,dst shutil.copy 179 180 .. versionchanged:: 3.3 181 Added *follow_symlinks* argument. 182 Now returns path to the newly created file. 183 184 .. versionchanged:: 3.8 185 Platform-specific fast-copy syscalls may be used internally in order to 186 copy the file more efficiently. See 187 :ref:`shutil-platform-dependent-efficient-copy-operations` section. 188 189.. function:: copy2(src, dst, *, follow_symlinks=True) 190 191 Identical to :func:`~shutil.copy` except that :func:`copy2` 192 also attempts to preserve file metadata. 193 194 When *follow_symlinks* is false, and *src* is a symbolic 195 link, :func:`copy2` attempts to copy all metadata from the 196 *src* symbolic link to the newly-created *dst* symbolic link. 197 However, this functionality is not available on all platforms. 198 On platforms where some or all of this functionality is 199 unavailable, :func:`copy2` will preserve all the metadata 200 it can; :func:`copy2` never raises an exception because it 201 cannot preserve file metadata. 202 203 :func:`copy2` uses :func:`copystat` to copy the file metadata. 204 Please see :func:`copystat` for more information 205 about platform support for modifying symbolic link metadata. 206 207 .. audit-event:: shutil.copyfile src,dst shutil.copy2 208 209 .. audit-event:: shutil.copystat src,dst shutil.copy2 210 211 .. versionchanged:: 3.3 212 Added *follow_symlinks* argument, try to copy extended 213 file system attributes too (currently Linux only). 214 Now returns path to the newly created file. 215 216 .. versionchanged:: 3.8 217 Platform-specific fast-copy syscalls may be used internally in order to 218 copy the file more efficiently. See 219 :ref:`shutil-platform-dependent-efficient-copy-operations` section. 220 221.. function:: ignore_patterns(\*patterns) 222 223 This factory function creates a function that can be used as a callable for 224 :func:`copytree`\'s *ignore* argument, ignoring files and directories that 225 match one of the glob-style *patterns* provided. See the example below. 226 227 228.. function:: copytree(src, dst, symlinks=False, ignore=None, \ 229 copy_function=copy2, ignore_dangling_symlinks=False, \ 230 dirs_exist_ok=False) 231 232 Recursively copy an entire directory tree rooted at *src* to a directory 233 named *dst* and return the destination directory. *dirs_exist_ok* dictates 234 whether to raise an exception in case *dst* or any missing parent directory 235 already exists. 236 237 Permissions and times of directories are copied with :func:`copystat`, 238 individual files are copied using :func:`~shutil.copy2`. 239 240 If *symlinks* is true, symbolic links in the source tree are represented as 241 symbolic links in the new tree and the metadata of the original links will 242 be copied as far as the platform allows; if false or omitted, the contents 243 and metadata of the linked files are copied to the new tree. 244 245 When *symlinks* is false, if the file pointed by the symlink doesn't 246 exist, an exception will be added in the list of errors raised in 247 an :exc:`Error` exception at the end of the copy process. 248 You can set the optional *ignore_dangling_symlinks* flag to true if you 249 want to silence this exception. Notice that this option has no effect 250 on platforms that don't support :func:`os.symlink`. 251 252 If *ignore* is given, it must be a callable that will receive as its 253 arguments the directory being visited by :func:`copytree`, and a list of its 254 contents, as returned by :func:`os.listdir`. Since :func:`copytree` is 255 called recursively, the *ignore* callable will be called once for each 256 directory that is copied. The callable must return a sequence of directory 257 and file names relative to the current directory (i.e. a subset of the items 258 in its second argument); these names will then be ignored in the copy 259 process. :func:`ignore_patterns` can be used to create such a callable that 260 ignores names based on glob-style patterns. 261 262 If exception(s) occur, an :exc:`Error` is raised with a list of reasons. 263 264 If *copy_function* is given, it must be a callable that will be used to copy 265 each file. It will be called with the source path and the destination path 266 as arguments. By default, :func:`~shutil.copy2` is used, but any function 267 that supports the same signature (like :func:`~shutil.copy`) can be used. 268 269 .. audit-event:: shutil.copytree src,dst shutil.copytree 270 271 .. versionchanged:: 3.3 272 Copy metadata when *symlinks* is false. 273 Now returns *dst*. 274 275 .. versionchanged:: 3.2 276 Added the *copy_function* argument to be able to provide a custom copy 277 function. 278 Added the *ignore_dangling_symlinks* argument to silent dangling symlinks 279 errors when *symlinks* is false. 280 281 .. versionchanged:: 3.8 282 Platform-specific fast-copy syscalls may be used internally in order to 283 copy the file more efficiently. See 284 :ref:`shutil-platform-dependent-efficient-copy-operations` section. 285 286 .. versionadded:: 3.8 287 The *dirs_exist_ok* parameter. 288 289.. function:: rmtree(path, ignore_errors=False, onerror=None) 290 291 .. index:: single: directory; deleting 292 293 Delete an entire directory tree; *path* must point to a directory (but not a 294 symbolic link to a directory). If *ignore_errors* is true, errors resulting 295 from failed removals will be ignored; if false or omitted, such errors are 296 handled by calling a handler specified by *onerror* or, if that is omitted, 297 they raise an exception. 298 299 .. note:: 300 301 On platforms that support the necessary fd-based functions a symlink 302 attack resistant version of :func:`rmtree` is used by default. On other 303 platforms, the :func:`rmtree` implementation is susceptible to a symlink 304 attack: given proper timing and circumstances, attackers can manipulate 305 symlinks on the filesystem to delete files they wouldn't be able to access 306 otherwise. Applications can use the :data:`rmtree.avoids_symlink_attacks` 307 function attribute to determine which case applies. 308 309 If *onerror* is provided, it must be a callable that accepts three 310 parameters: *function*, *path*, and *excinfo*. 311 312 The first parameter, *function*, is the function which raised the exception; 313 it depends on the platform and implementation. The second parameter, 314 *path*, will be the path name passed to *function*. The third parameter, 315 *excinfo*, will be the exception information returned by 316 :func:`sys.exc_info`. Exceptions raised by *onerror* will not be caught. 317 318 .. audit-event:: shutil.rmtree path shutil.rmtree 319 320 .. versionchanged:: 3.3 321 Added a symlink attack resistant version that is used automatically 322 if platform supports fd-based functions. 323 324 .. versionchanged:: 3.8 325 On Windows, will no longer delete the contents of a directory junction 326 before removing the junction. 327 328 .. attribute:: rmtree.avoids_symlink_attacks 329 330 Indicates whether the current platform and implementation provides a 331 symlink attack resistant version of :func:`rmtree`. Currently this is 332 only true for platforms supporting fd-based directory access functions. 333 334 .. versionadded:: 3.3 335 336 337.. function:: move(src, dst, copy_function=copy2) 338 339 Recursively move a file or directory (*src*) to another location (*dst*) 340 and return the destination. 341 342 If the destination is an existing directory, then *src* is moved inside that 343 directory. If the destination already exists but is not a directory, it may 344 be overwritten depending on :func:`os.rename` semantics. 345 346 If the destination is on the current filesystem, then :func:`os.rename` is 347 used. Otherwise, *src* is copied to *dst* using *copy_function* and then 348 removed. In case of symlinks, a new symlink pointing to the target of *src* 349 will be created in or as *dst* and *src* will be removed. 350 351 If *copy_function* is given, it must be a callable that takes two arguments 352 *src* and *dst*, and will be used to copy *src* to *dest* if 353 :func:`os.rename` cannot be used. If the source is a directory, 354 :func:`copytree` is called, passing it the :func:`copy_function`. The 355 default *copy_function* is :func:`copy2`. Using :func:`~shutil.copy` as the 356 *copy_function* allows the move to succeed when it is not possible to also 357 copy the metadata, at the expense of not copying any of the metadata. 358 359 .. audit-event:: shutil.move src,dst shutil.move 360 361 .. versionchanged:: 3.3 362 Added explicit symlink handling for foreign filesystems, thus adapting 363 it to the behavior of GNU's :program:`mv`. 364 Now returns *dst*. 365 366 .. versionchanged:: 3.5 367 Added the *copy_function* keyword argument. 368 369 .. versionchanged:: 3.8 370 Platform-specific fast-copy syscalls may be used internally in order to 371 copy the file more efficiently. See 372 :ref:`shutil-platform-dependent-efficient-copy-operations` section. 373 374.. function:: disk_usage(path) 375 376 Return disk usage statistics about the given path as a :term:`named tuple` 377 with the attributes *total*, *used* and *free*, which are the amount of 378 total, used and free space, in bytes. *path* may be a file or a 379 directory. 380 381 .. versionadded:: 3.3 382 383 .. versionchanged:: 3.8 384 On Windows, *path* can now be a file or directory. 385 386 .. availability:: Unix, Windows. 387 388.. function:: chown(path, user=None, group=None) 389 390 Change owner *user* and/or *group* of the given *path*. 391 392 *user* can be a system user name or a uid; the same applies to *group*. At 393 least one argument is required. 394 395 See also :func:`os.chown`, the underlying function. 396 397 .. audit-event:: shutil.chown path,user,group shutil.chown 398 399 .. availability:: Unix. 400 401 .. versionadded:: 3.3 402 403 404.. function:: which(cmd, mode=os.F_OK | os.X_OK, path=None) 405 406 Return the path to an executable which would be run if the given *cmd* was 407 called. If no *cmd* would be called, return ``None``. 408 409 *mode* is a permission mask passed to :func:`os.access`, by default 410 determining if the file exists and executable. 411 412 When no *path* is specified, the results of :func:`os.environ` are used, 413 returning either the "PATH" value or a fallback of :attr:`os.defpath`. 414 415 On Windows, the current directory is always prepended to the *path* whether 416 or not you use the default or provide your own, which is the behavior the 417 command shell uses when finding executables. Additionally, when finding the 418 *cmd* in the *path*, the ``PATHEXT`` environment variable is checked. For 419 example, if you call ``shutil.which("python")``, :func:`which` will search 420 ``PATHEXT`` to know that it should look for ``python.exe`` within the *path* 421 directories. For example, on Windows:: 422 423 >>> shutil.which("python") 424 'C:\\Python33\\python.EXE' 425 426 .. versionadded:: 3.3 427 428 .. versionchanged:: 3.8 429 The :class:`bytes` type is now accepted. If *cmd* type is 430 :class:`bytes`, the result type is also :class:`bytes`. 431 432.. exception:: Error 433 434 This exception collects exceptions that are raised during a multi-file 435 operation. For :func:`copytree`, the exception argument is a list of 3-tuples 436 (*srcname*, *dstname*, *exception*). 437 438.. _shutil-platform-dependent-efficient-copy-operations: 439 440Platform-dependent efficient copy operations 441~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 442 443Starting from Python 3.8 all functions involving a file copy (:func:`copyfile`, 444:func:`copy`, :func:`copy2`, :func:`copytree`, and :func:`move`) may use 445platform-specific "fast-copy" syscalls in order to copy the file more 446efficiently (see :issue:`33671`). 447"fast-copy" means that the copying operation occurs within the kernel, avoiding 448the use of userspace buffers in Python as in "``outfd.write(infd.read())``". 449 450On macOS `fcopyfile`_ is used to copy the file content (not metadata). 451 452On Linux :func:`os.sendfile` is used. 453 454On Windows :func:`shutil.copyfile` uses a bigger default buffer size (1 MiB 455instead of 64 KiB) and a :func:`memoryview`-based variant of 456:func:`shutil.copyfileobj` is used. 457 458If the fast-copy operation fails and no data was written in the destination 459file then shutil will silently fallback on using less efficient 460:func:`copyfileobj` function internally. 461 462.. versionchanged:: 3.8 463 464.. _shutil-copytree-example: 465 466copytree example 467~~~~~~~~~~~~~~~~ 468 469This example is the implementation of the :func:`copytree` function, described 470above, with the docstring omitted. It demonstrates many of the other functions 471provided by this module. :: 472 473 def copytree(src, dst, symlinks=False): 474 names = os.listdir(src) 475 os.makedirs(dst) 476 errors = [] 477 for name in names: 478 srcname = os.path.join(src, name) 479 dstname = os.path.join(dst, name) 480 try: 481 if symlinks and os.path.islink(srcname): 482 linkto = os.readlink(srcname) 483 os.symlink(linkto, dstname) 484 elif os.path.isdir(srcname): 485 copytree(srcname, dstname, symlinks) 486 else: 487 copy2(srcname, dstname) 488 # XXX What about devices, sockets etc.? 489 except OSError as why: 490 errors.append((srcname, dstname, str(why))) 491 # catch the Error from the recursive copytree so that we can 492 # continue with other files 493 except Error as err: 494 errors.extend(err.args[0]) 495 try: 496 copystat(src, dst) 497 except OSError as why: 498 # can't copy file access times on Windows 499 if why.winerror is None: 500 errors.extend((src, dst, str(why))) 501 if errors: 502 raise Error(errors) 503 504Another example that uses the :func:`ignore_patterns` helper:: 505 506 from shutil import copytree, ignore_patterns 507 508 copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*')) 509 510This will copy everything except ``.pyc`` files and files or directories whose 511name starts with ``tmp``. 512 513Another example that uses the *ignore* argument to add a logging call:: 514 515 from shutil import copytree 516 import logging 517 518 def _logpath(path, names): 519 logging.info('Working in %s', path) 520 return [] # nothing will be ignored 521 522 copytree(source, destination, ignore=_logpath) 523 524 525.. _shutil-rmtree-example: 526 527rmtree example 528~~~~~~~~~~~~~~ 529 530This example shows how to remove a directory tree on Windows where some 531of the files have their read-only bit set. It uses the onerror callback 532to clear the readonly bit and reattempt the remove. Any subsequent failure 533will propagate. :: 534 535 import os, stat 536 import shutil 537 538 def remove_readonly(func, path, _): 539 "Clear the readonly bit and reattempt the removal" 540 os.chmod(path, stat.S_IWRITE) 541 func(path) 542 543 shutil.rmtree(directory, onerror=remove_readonly) 544 545.. _archiving-operations: 546 547Archiving operations 548-------------------- 549 550.. versionadded:: 3.2 551 552.. versionchanged:: 3.5 553 Added support for the *xztar* format. 554 555 556High-level utilities to create and read compressed and archived files are also 557provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. 558 559.. function:: make_archive(base_name, format, [root_dir, [base_dir, [verbose, [dry_run, [owner, [group, [logger]]]]]]]) 560 561 Create an archive file (such as zip or tar) and return its name. 562 563 *base_name* is the name of the file to create, including the path, minus 564 any format-specific extension. *format* is the archive format: one of 565 "zip" (if the :mod:`zlib` module is available), "tar", "gztar" (if the 566 :mod:`zlib` module is available), "bztar" (if the :mod:`bz2` module is 567 available), or "xztar" (if the :mod:`lzma` module is available). 568 569 *root_dir* is a directory that will be the root directory of the 570 archive, all paths in the archive will be relative to it; for example, 571 we typically chdir into *root_dir* before creating the archive. 572 573 *base_dir* is the directory where we start archiving from; 574 i.e. *base_dir* will be the common prefix of all files and 575 directories in the archive. *base_dir* must be given relative 576 to *root_dir*. See :ref:`shutil-archiving-example-with-basedir` for how to 577 use *base_dir* and *root_dir* together. 578 579 *root_dir* and *base_dir* both default to the current directory. 580 581 If *dry_run* is true, no archive is created, but the operations that would be 582 executed are logged to *logger*. 583 584 *owner* and *group* are used when creating a tar archive. By default, 585 uses the current owner and group. 586 587 *logger* must be an object compatible with :pep:`282`, usually an instance of 588 :class:`logging.Logger`. 589 590 The *verbose* argument is unused and deprecated. 591 592 .. audit-event:: shutil.make_archive base_name,format,root_dir,base_dir shutil.make_archive 593 594 .. versionchanged:: 3.8 595 The modern pax (POSIX.1-2001) format is now used instead of 596 the legacy GNU format for archives created with ``format="tar"``. 597 598 599.. function:: get_archive_formats() 600 601 Return a list of supported formats for archiving. 602 Each element of the returned sequence is a tuple ``(name, description)``. 603 604 By default :mod:`shutil` provides these formats: 605 606 - *zip*: ZIP file (if the :mod:`zlib` module is available). 607 - *tar*: Uncompressed tar file. Uses POSIX.1-2001 pax format for new archives. 608 - *gztar*: gzip'ed tar-file (if the :mod:`zlib` module is available). 609 - *bztar*: bzip2'ed tar-file (if the :mod:`bz2` module is available). 610 - *xztar*: xz'ed tar-file (if the :mod:`lzma` module is available). 611 612 You can register new formats or provide your own archiver for any existing 613 formats, by using :func:`register_archive_format`. 614 615 616.. function:: register_archive_format(name, function, [extra_args, [description]]) 617 618 Register an archiver for the format *name*. 619 620 *function* is the callable that will be used to unpack archives. The callable 621 will receive the *base_name* of the file to create, followed by the 622 *base_dir* (which defaults to :data:`os.curdir`) to start archiving from. 623 Further arguments are passed as keyword arguments: *owner*, *group*, 624 *dry_run* and *logger* (as passed in :func:`make_archive`). 625 626 If given, *extra_args* is a sequence of ``(name, value)`` pairs that will be 627 used as extra keywords arguments when the archiver callable is used. 628 629 *description* is used by :func:`get_archive_formats` which returns the 630 list of archivers. Defaults to an empty string. 631 632 633.. function:: unregister_archive_format(name) 634 635 Remove the archive format *name* from the list of supported formats. 636 637 638.. function:: unpack_archive(filename[, extract_dir[, format]]) 639 640 Unpack an archive. *filename* is the full path of the archive. 641 642 *extract_dir* is the name of the target directory where the archive is 643 unpacked. If not provided, the current working directory is used. 644 645 *format* is the archive format: one of "zip", "tar", "gztar", "bztar", or 646 "xztar". Or any other format registered with 647 :func:`register_unpack_format`. If not provided, :func:`unpack_archive` 648 will use the archive file name extension and see if an unpacker was 649 registered for that extension. In case none is found, 650 a :exc:`ValueError` is raised. 651 652 .. audit-event:: shutil.unpack_archive filename,extract_dir,format shutil.unpack_archive 653 654 .. versionchanged:: 3.7 655 Accepts a :term:`path-like object` for *filename* and *extract_dir*. 656 657 658.. function:: register_unpack_format(name, extensions, function[, extra_args[, description]]) 659 660 Registers an unpack format. *name* is the name of the format and 661 *extensions* is a list of extensions corresponding to the format, like 662 ``.zip`` for Zip files. 663 664 *function* is the callable that will be used to unpack archives. The 665 callable will receive the path of the archive, followed by the directory 666 the archive must be extracted to. 667 668 When provided, *extra_args* is a sequence of ``(name, value)`` tuples that 669 will be passed as keywords arguments to the callable. 670 671 *description* can be provided to describe the format, and will be returned 672 by the :func:`get_unpack_formats` function. 673 674 675.. function:: unregister_unpack_format(name) 676 677 Unregister an unpack format. *name* is the name of the format. 678 679 680.. function:: get_unpack_formats() 681 682 Return a list of all registered formats for unpacking. 683 Each element of the returned sequence is a tuple 684 ``(name, extensions, description)``. 685 686 By default :mod:`shutil` provides these formats: 687 688 - *zip*: ZIP file (unpacking compressed files works only if the corresponding 689 module is available). 690 - *tar*: uncompressed tar file. 691 - *gztar*: gzip'ed tar-file (if the :mod:`zlib` module is available). 692 - *bztar*: bzip2'ed tar-file (if the :mod:`bz2` module is available). 693 - *xztar*: xz'ed tar-file (if the :mod:`lzma` module is available). 694 695 You can register new formats or provide your own unpacker for any existing 696 formats, by using :func:`register_unpack_format`. 697 698 699.. _shutil-archiving-example: 700 701Archiving example 702~~~~~~~~~~~~~~~~~ 703 704In this example, we create a gzip'ed tar-file archive containing all files 705found in the :file:`.ssh` directory of the user:: 706 707 >>> from shutil import make_archive 708 >>> import os 709 >>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive')) 710 >>> root_dir = os.path.expanduser(os.path.join('~', '.ssh')) 711 >>> make_archive(archive_name, 'gztar', root_dir) 712 '/Users/tarek/myarchive.tar.gz' 713 714The resulting archive contains: 715 716.. code-block:: shell-session 717 718 $ tar -tzvf /Users/tarek/myarchive.tar.gz 719 drwx------ tarek/staff 0 2010-02-01 16:23:40 ./ 720 -rw-r--r-- tarek/staff 609 2008-06-09 13:26:54 ./authorized_keys 721 -rwxr-xr-x tarek/staff 65 2008-06-09 13:26:54 ./config 722 -rwx------ tarek/staff 668 2008-06-09 13:26:54 ./id_dsa 723 -rwxr-xr-x tarek/staff 609 2008-06-09 13:26:54 ./id_dsa.pub 724 -rw------- tarek/staff 1675 2008-06-09 13:26:54 ./id_rsa 725 -rw-r--r-- tarek/staff 397 2008-06-09 13:26:54 ./id_rsa.pub 726 -rw-r--r-- tarek/staff 37192 2010-02-06 18:23:10 ./known_hosts 727 728 729.. _shutil-archiving-example-with-basedir: 730 731Archiving example with *base_dir* 732~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 733 734In this example, similar to the `one above <shutil-archiving-example_>`_, 735we show how to use :func:`make_archive`, but this time with the usage of 736*base_dir*. We now have the following directory structure: 737 738.. code-block:: shell-session 739 740 $ tree tmp 741 tmp 742 └── root 743 └── structure 744 ├── content 745 └── please_add.txt 746 └── do_not_add.txt 747 748In the final archive, :file:`please_add.txt` should be included, but 749:file:`do_not_add.txt` should not. Therefore we use the following:: 750 751 >>> from shutil import make_archive 752 >>> import os 753 >>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive')) 754 >>> make_archive( 755 ... archive_name, 756 ... 'tar', 757 ... root_dir='tmp/root', 758 ... base_dir='structure/content', 759 ... ) 760 '/Users/tarek/my_archive.tar' 761 762Listing the files in the resulting archive gives us: 763 764.. code-block:: shell-session 765 766 $ python -m tarfile -l /Users/tarek/myarchive.tar 767 structure/content/ 768 structure/content/please_add.txt 769 770 771Querying the size of the output terminal 772---------------------------------------- 773 774.. function:: get_terminal_size(fallback=(columns, lines)) 775 776 Get the size of the terminal window. 777 778 For each of the two dimensions, the environment variable, ``COLUMNS`` 779 and ``LINES`` respectively, is checked. If the variable is defined and 780 the value is a positive integer, it is used. 781 782 When ``COLUMNS`` or ``LINES`` is not defined, which is the common case, 783 the terminal connected to :data:`sys.__stdout__` is queried 784 by invoking :func:`os.get_terminal_size`. 785 786 If the terminal size cannot be successfully queried, either because 787 the system doesn't support querying, or because we are not 788 connected to a terminal, the value given in ``fallback`` parameter 789 is used. ``fallback`` defaults to ``(80, 24)`` which is the default 790 size used by many terminal emulators. 791 792 The value returned is a named tuple of type :class:`os.terminal_size`. 793 794 See also: The Single UNIX Specification, Version 2, 795 `Other Environment Variables`_. 796 797 .. versionadded:: 3.3 798 799.. _`fcopyfile`: 800 http://www.manpagez.com/man/3/copyfile/ 801 802.. _`Other Environment Variables`: 803 http://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html#tag_002_003 804