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 :term:`path-like objects <path-like object>` or strings. If 162 *dst* specifies a directory, the file will be copied into *dst* using the 163 base filename from *src*. Returns the 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 *dst* 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 .. versionchanged:: 3.9 375 Accepts a :term:`path-like object` for both *src* and *dst*. 376 377.. function:: disk_usage(path) 378 379 Return disk usage statistics about the given path as a :term:`named tuple` 380 with the attributes *total*, *used* and *free*, which are the amount of 381 total, used and free space, in bytes. *path* may be a file or a 382 directory. 383 384 .. versionadded:: 3.3 385 386 .. versionchanged:: 3.8 387 On Windows, *path* can now be a file or directory. 388 389 .. availability:: Unix, Windows. 390 391.. function:: chown(path, user=None, group=None) 392 393 Change owner *user* and/or *group* of the given *path*. 394 395 *user* can be a system user name or a uid; the same applies to *group*. At 396 least one argument is required. 397 398 See also :func:`os.chown`, the underlying function. 399 400 .. audit-event:: shutil.chown path,user,group shutil.chown 401 402 .. availability:: Unix. 403 404 .. versionadded:: 3.3 405 406 407.. function:: which(cmd, mode=os.F_OK | os.X_OK, path=None) 408 409 Return the path to an executable which would be run if the given *cmd* was 410 called. If no *cmd* would be called, return ``None``. 411 412 *mode* is a permission mask passed to :func:`os.access`, by default 413 determining if the file exists and executable. 414 415 When no *path* is specified, the results of :func:`os.environ` are used, 416 returning either the "PATH" value or a fallback of :attr:`os.defpath`. 417 418 On Windows, the current directory is always prepended to the *path* whether 419 or not you use the default or provide your own, which is the behavior the 420 command shell uses when finding executables. Additionally, when finding the 421 *cmd* in the *path*, the ``PATHEXT`` environment variable is checked. For 422 example, if you call ``shutil.which("python")``, :func:`which` will search 423 ``PATHEXT`` to know that it should look for ``python.exe`` within the *path* 424 directories. For example, on Windows:: 425 426 >>> shutil.which("python") 427 'C:\\Python33\\python.EXE' 428 429 .. versionadded:: 3.3 430 431 .. versionchanged:: 3.8 432 The :class:`bytes` type is now accepted. If *cmd* type is 433 :class:`bytes`, the result type is also :class:`bytes`. 434 435.. exception:: Error 436 437 This exception collects exceptions that are raised during a multi-file 438 operation. For :func:`copytree`, the exception argument is a list of 3-tuples 439 (*srcname*, *dstname*, *exception*). 440 441.. _shutil-platform-dependent-efficient-copy-operations: 442 443Platform-dependent efficient copy operations 444~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 445 446Starting from Python 3.8 all functions involving a file copy (:func:`copyfile`, 447:func:`copy`, :func:`copy2`, :func:`copytree`, and :func:`move`) may use 448platform-specific "fast-copy" syscalls in order to copy the file more 449efficiently (see :issue:`33671`). 450"fast-copy" means that the copying operation occurs within the kernel, avoiding 451the use of userspace buffers in Python as in "``outfd.write(infd.read())``". 452 453On macOS `fcopyfile`_ is used to copy the file content (not metadata). 454 455On Linux :func:`os.sendfile` is used. 456 457On Windows :func:`shutil.copyfile` uses a bigger default buffer size (1 MiB 458instead of 64 KiB) and a :func:`memoryview`-based variant of 459:func:`shutil.copyfileobj` is used. 460 461If the fast-copy operation fails and no data was written in the destination 462file then shutil will silently fallback on using less efficient 463:func:`copyfileobj` function internally. 464 465.. versionchanged:: 3.8 466 467.. _shutil-copytree-example: 468 469copytree example 470~~~~~~~~~~~~~~~~ 471 472This example is the implementation of the :func:`copytree` function, described 473above, with the docstring omitted. It demonstrates many of the other functions 474provided by this module. :: 475 476 def copytree(src, dst, symlinks=False): 477 names = os.listdir(src) 478 os.makedirs(dst) 479 errors = [] 480 for name in names: 481 srcname = os.path.join(src, name) 482 dstname = os.path.join(dst, name) 483 try: 484 if symlinks and os.path.islink(srcname): 485 linkto = os.readlink(srcname) 486 os.symlink(linkto, dstname) 487 elif os.path.isdir(srcname): 488 copytree(srcname, dstname, symlinks) 489 else: 490 copy2(srcname, dstname) 491 # XXX What about devices, sockets etc.? 492 except OSError as why: 493 errors.append((srcname, dstname, str(why))) 494 # catch the Error from the recursive copytree so that we can 495 # continue with other files 496 except Error as err: 497 errors.extend(err.args[0]) 498 try: 499 copystat(src, dst) 500 except OSError as why: 501 # can't copy file access times on Windows 502 if why.winerror is None: 503 errors.extend((src, dst, str(why))) 504 if errors: 505 raise Error(errors) 506 507Another example that uses the :func:`ignore_patterns` helper:: 508 509 from shutil import copytree, ignore_patterns 510 511 copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*')) 512 513This will copy everything except ``.pyc`` files and files or directories whose 514name starts with ``tmp``. 515 516Another example that uses the *ignore* argument to add a logging call:: 517 518 from shutil import copytree 519 import logging 520 521 def _logpath(path, names): 522 logging.info('Working in %s', path) 523 return [] # nothing will be ignored 524 525 copytree(source, destination, ignore=_logpath) 526 527 528.. _shutil-rmtree-example: 529 530rmtree example 531~~~~~~~~~~~~~~ 532 533This example shows how to remove a directory tree on Windows where some 534of the files have their read-only bit set. It uses the onerror callback 535to clear the readonly bit and reattempt the remove. Any subsequent failure 536will propagate. :: 537 538 import os, stat 539 import shutil 540 541 def remove_readonly(func, path, _): 542 "Clear the readonly bit and reattempt the removal" 543 os.chmod(path, stat.S_IWRITE) 544 func(path) 545 546 shutil.rmtree(directory, onerror=remove_readonly) 547 548.. _archiving-operations: 549 550Archiving operations 551-------------------- 552 553.. versionadded:: 3.2 554 555.. versionchanged:: 3.5 556 Added support for the *xztar* format. 557 558 559High-level utilities to create and read compressed and archived files are also 560provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. 561 562.. function:: make_archive(base_name, format, [root_dir, [base_dir, [verbose, [dry_run, [owner, [group, [logger]]]]]]]) 563 564 Create an archive file (such as zip or tar) and return its name. 565 566 *base_name* is the name of the file to create, including the path, minus 567 any format-specific extension. *format* is the archive format: one of 568 "zip" (if the :mod:`zlib` module is available), "tar", "gztar" (if the 569 :mod:`zlib` module is available), "bztar" (if the :mod:`bz2` module is 570 available), or "xztar" (if the :mod:`lzma` module is available). 571 572 *root_dir* is a directory that will be the root directory of the 573 archive, all paths in the archive will be relative to it; for example, 574 we typically chdir into *root_dir* before creating the archive. 575 576 *base_dir* is the directory where we start archiving from; 577 i.e. *base_dir* will be the common prefix of all files and 578 directories in the archive. *base_dir* must be given relative 579 to *root_dir*. See :ref:`shutil-archiving-example-with-basedir` for how to 580 use *base_dir* and *root_dir* together. 581 582 *root_dir* and *base_dir* both default to the current directory. 583 584 If *dry_run* is true, no archive is created, but the operations that would be 585 executed are logged to *logger*. 586 587 *owner* and *group* are used when creating a tar archive. By default, 588 uses the current owner and group. 589 590 *logger* must be an object compatible with :pep:`282`, usually an instance of 591 :class:`logging.Logger`. 592 593 The *verbose* argument is unused and deprecated. 594 595 .. audit-event:: shutil.make_archive base_name,format,root_dir,base_dir shutil.make_archive 596 597 .. versionchanged:: 3.8 598 The modern pax (POSIX.1-2001) format is now used instead of 599 the legacy GNU format for archives created with ``format="tar"``. 600 601 602.. function:: get_archive_formats() 603 604 Return a list of supported formats for archiving. 605 Each element of the returned sequence is a tuple ``(name, description)``. 606 607 By default :mod:`shutil` provides these formats: 608 609 - *zip*: ZIP file (if the :mod:`zlib` module is available). 610 - *tar*: Uncompressed tar file. Uses POSIX.1-2001 pax format for new archives. 611 - *gztar*: gzip'ed tar-file (if the :mod:`zlib` module is available). 612 - *bztar*: bzip2'ed tar-file (if the :mod:`bz2` module is available). 613 - *xztar*: xz'ed tar-file (if the :mod:`lzma` module is available). 614 615 You can register new formats or provide your own archiver for any existing 616 formats, by using :func:`register_archive_format`. 617 618 619.. function:: register_archive_format(name, function, [extra_args, [description]]) 620 621 Register an archiver for the format *name*. 622 623 *function* is the callable that will be used to unpack archives. The callable 624 will receive the *base_name* of the file to create, followed by the 625 *base_dir* (which defaults to :data:`os.curdir`) to start archiving from. 626 Further arguments are passed as keyword arguments: *owner*, *group*, 627 *dry_run* and *logger* (as passed in :func:`make_archive`). 628 629 If given, *extra_args* is a sequence of ``(name, value)`` pairs that will be 630 used as extra keywords arguments when the archiver callable is used. 631 632 *description* is used by :func:`get_archive_formats` which returns the 633 list of archivers. Defaults to an empty string. 634 635 636.. function:: unregister_archive_format(name) 637 638 Remove the archive format *name* from the list of supported formats. 639 640 641.. function:: unpack_archive(filename[, extract_dir[, format]]) 642 643 Unpack an archive. *filename* is the full path of the archive. 644 645 *extract_dir* is the name of the target directory where the archive is 646 unpacked. If not provided, the current working directory is used. 647 648 *format* is the archive format: one of "zip", "tar", "gztar", "bztar", or 649 "xztar". Or any other format registered with 650 :func:`register_unpack_format`. If not provided, :func:`unpack_archive` 651 will use the archive file name extension and see if an unpacker was 652 registered for that extension. In case none is found, 653 a :exc:`ValueError` is raised. 654 655 .. audit-event:: shutil.unpack_archive filename,extract_dir,format shutil.unpack_archive 656 657 .. versionchanged:: 3.7 658 Accepts a :term:`path-like object` for *filename* and *extract_dir*. 659 660 661.. function:: register_unpack_format(name, extensions, function[, extra_args[, description]]) 662 663 Registers an unpack format. *name* is the name of the format and 664 *extensions* is a list of extensions corresponding to the format, like 665 ``.zip`` for Zip files. 666 667 *function* is the callable that will be used to unpack archives. The 668 callable will receive the path of the archive, followed by the directory 669 the archive must be extracted to. 670 671 When provided, *extra_args* is a sequence of ``(name, value)`` tuples that 672 will be passed as keywords arguments to the callable. 673 674 *description* can be provided to describe the format, and will be returned 675 by the :func:`get_unpack_formats` function. 676 677 678.. function:: unregister_unpack_format(name) 679 680 Unregister an unpack format. *name* is the name of the format. 681 682 683.. function:: get_unpack_formats() 684 685 Return a list of all registered formats for unpacking. 686 Each element of the returned sequence is a tuple 687 ``(name, extensions, description)``. 688 689 By default :mod:`shutil` provides these formats: 690 691 - *zip*: ZIP file (unpacking compressed files works only if the corresponding 692 module is available). 693 - *tar*: uncompressed tar file. 694 - *gztar*: gzip'ed tar-file (if the :mod:`zlib` module is available). 695 - *bztar*: bzip2'ed tar-file (if the :mod:`bz2` module is available). 696 - *xztar*: xz'ed tar-file (if the :mod:`lzma` module is available). 697 698 You can register new formats or provide your own unpacker for any existing 699 formats, by using :func:`register_unpack_format`. 700 701 702.. _shutil-archiving-example: 703 704Archiving example 705~~~~~~~~~~~~~~~~~ 706 707In this example, we create a gzip'ed tar-file archive containing all files 708found in the :file:`.ssh` directory of the user:: 709 710 >>> from shutil import make_archive 711 >>> import os 712 >>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive')) 713 >>> root_dir = os.path.expanduser(os.path.join('~', '.ssh')) 714 >>> make_archive(archive_name, 'gztar', root_dir) 715 '/Users/tarek/myarchive.tar.gz' 716 717The resulting archive contains: 718 719.. code-block:: shell-session 720 721 $ tar -tzvf /Users/tarek/myarchive.tar.gz 722 drwx------ tarek/staff 0 2010-02-01 16:23:40 ./ 723 -rw-r--r-- tarek/staff 609 2008-06-09 13:26:54 ./authorized_keys 724 -rwxr-xr-x tarek/staff 65 2008-06-09 13:26:54 ./config 725 -rwx------ tarek/staff 668 2008-06-09 13:26:54 ./id_dsa 726 -rwxr-xr-x tarek/staff 609 2008-06-09 13:26:54 ./id_dsa.pub 727 -rw------- tarek/staff 1675 2008-06-09 13:26:54 ./id_rsa 728 -rw-r--r-- tarek/staff 397 2008-06-09 13:26:54 ./id_rsa.pub 729 -rw-r--r-- tarek/staff 37192 2010-02-06 18:23:10 ./known_hosts 730 731 732.. _shutil-archiving-example-with-basedir: 733 734Archiving example with *base_dir* 735~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 736 737In this example, similar to the `one above <shutil-archiving-example_>`_, 738we show how to use :func:`make_archive`, but this time with the usage of 739*base_dir*. We now have the following directory structure: 740 741.. code-block:: shell-session 742 743 $ tree tmp 744 tmp 745 └── root 746 └── structure 747 ├── content 748 └── please_add.txt 749 └── do_not_add.txt 750 751In the final archive, :file:`please_add.txt` should be included, but 752:file:`do_not_add.txt` should not. Therefore we use the following:: 753 754 >>> from shutil import make_archive 755 >>> import os 756 >>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive')) 757 >>> make_archive( 758 ... archive_name, 759 ... 'tar', 760 ... root_dir='tmp/root', 761 ... base_dir='structure/content', 762 ... ) 763 '/Users/tarek/my_archive.tar' 764 765Listing the files in the resulting archive gives us: 766 767.. code-block:: shell-session 768 769 $ python -m tarfile -l /Users/tarek/myarchive.tar 770 structure/content/ 771 structure/content/please_add.txt 772 773 774Querying the size of the output terminal 775---------------------------------------- 776 777.. function:: get_terminal_size(fallback=(columns, lines)) 778 779 Get the size of the terminal window. 780 781 For each of the two dimensions, the environment variable, ``COLUMNS`` 782 and ``LINES`` respectively, is checked. If the variable is defined and 783 the value is a positive integer, it is used. 784 785 When ``COLUMNS`` or ``LINES`` is not defined, which is the common case, 786 the terminal connected to :data:`sys.__stdout__` is queried 787 by invoking :func:`os.get_terminal_size`. 788 789 If the terminal size cannot be successfully queried, either because 790 the system doesn't support querying, or because we are not 791 connected to a terminal, the value given in ``fallback`` parameter 792 is used. ``fallback`` defaults to ``(80, 24)`` which is the default 793 size used by many terminal emulators. 794 795 The value returned is a named tuple of type :class:`os.terminal_size`. 796 797 See also: The Single UNIX Specification, Version 2, 798 `Other Environment Variables`_. 799 800 .. versionadded:: 3.3 801 802.. _`fcopyfile`: 803 http://www.manpagez.com/man/3/copyfile/ 804 805.. _`Other Environment Variables`: 806 http://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html#tag_002_003 807