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