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