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 :term:`file-like object <file 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 :term:`path-like objects <path-like object>` 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 :term:`path-like objects <path-like object>` 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 :term:`path-like objects <path-like object>` 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*. If *dst* specifies a file that already exists, 164 it will be replaced. Returns the path to the newly created file. 165 166 If *follow_symlinks* is false, and *src* is a symbolic link, 167 *dst* will be created as a symbolic link. If *follow_symlinks* 168 is true and *src* is a symbolic link, *dst* will be a copy of 169 the file *src* refers to. 170 171 :func:`~shutil.copy` copies the file data and the file's permission 172 mode (see :func:`os.chmod`). Other metadata, like the 173 file's creation and modification times, is not preserved. 174 To preserve all file metadata from the original, use 175 :func:`~shutil.copy2` instead. 176 177 .. audit-event:: shutil.copyfile src,dst shutil.copy 178 179 .. audit-event:: shutil.copymode src,dst shutil.copy 180 181 .. versionchanged:: 3.3 182 Added *follow_symlinks* argument. 183 Now returns path to the newly created file. 184 185 .. versionchanged:: 3.8 186 Platform-specific fast-copy syscalls may be used internally in order to 187 copy the file more efficiently. See 188 :ref:`shutil-platform-dependent-efficient-copy-operations` section. 189 190.. function:: copy2(src, dst, *, follow_symlinks=True) 191 192 Identical to :func:`~shutil.copy` except that :func:`copy2` 193 also attempts to preserve file metadata. 194 195 When *follow_symlinks* is false, and *src* is a symbolic 196 link, :func:`copy2` attempts to copy all metadata from the 197 *src* symbolic link to the newly created *dst* symbolic link. 198 However, this functionality is not available on all platforms. 199 On platforms where some or all of this functionality is 200 unavailable, :func:`copy2` will preserve all the metadata 201 it can; :func:`copy2` never raises an exception because it 202 cannot preserve file metadata. 203 204 :func:`copy2` uses :func:`copystat` to copy the file metadata. 205 Please see :func:`copystat` for more information 206 about platform support for modifying symbolic link metadata. 207 208 .. audit-event:: shutil.copyfile src,dst shutil.copy2 209 210 .. audit-event:: shutil.copystat src,dst shutil.copy2 211 212 .. versionchanged:: 3.3 213 Added *follow_symlinks* argument, try to copy extended 214 file system attributes too (currently Linux only). 215 Now returns path to the newly created file. 216 217 .. versionchanged:: 3.8 218 Platform-specific fast-copy syscalls may be used internally in order to 219 copy the file more efficiently. See 220 :ref:`shutil-platform-dependent-efficient-copy-operations` section. 221 222.. function:: ignore_patterns(*patterns) 223 224 This factory function creates a function that can be used as a callable for 225 :func:`copytree`\'s *ignore* argument, ignoring files and directories that 226 match one of the glob-style *patterns* provided. See the example below. 227 228 229.. function:: copytree(src, dst, symlinks=False, ignore=None, \ 230 copy_function=copy2, ignore_dangling_symlinks=False, \ 231 dirs_exist_ok=False) 232 233 Recursively copy an entire directory tree rooted at *src* to a directory 234 named *dst* and return the destination directory. All intermediate 235 directories needed to contain *dst* will also be created by default. 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 to 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 If *dirs_exist_ok* is false (the default) and *dst* already exists, a 270 :exc:`FileExistsError` is raised. If *dirs_exist_ok* is true, the copying 271 operation will continue if it encounters existing directories, and files 272 within the *dst* tree will be overwritten by corresponding files from the 273 *src* tree. 274 275 .. audit-event:: shutil.copytree src,dst shutil.copytree 276 277 .. versionchanged:: 3.2 278 Added the *copy_function* argument to be able to provide a custom copy 279 function. 280 Added the *ignore_dangling_symlinks* argument to silence dangling symlinks 281 errors when *symlinks* is false. 282 283 .. versionchanged:: 3.3 284 Copy metadata when *symlinks* is false. 285 Now returns *dst*. 286 287 .. versionchanged:: 3.8 288 Platform-specific fast-copy syscalls may be used internally in order to 289 copy the file more efficiently. See 290 :ref:`shutil-platform-dependent-efficient-copy-operations` section. 291 292 .. versionchanged:: 3.8 293 Added the *dirs_exist_ok* parameter. 294 295.. function:: rmtree(path, ignore_errors=False, onerror=None, *, onexc=None, dir_fd=None) 296 297 .. index:: single: directory; deleting 298 299 Delete an entire directory tree; *path* must point to a directory (but not a 300 symbolic link to a directory). If *ignore_errors* is true, errors resulting 301 from failed removals will be ignored; if false or omitted, such errors are 302 handled by calling a handler specified by *onexc* or *onerror* or, if both 303 are omitted, exceptions are propagated to the caller. 304 305 This function can support :ref:`paths relative to directory descriptors 306 <dir_fd>`. 307 308 .. note:: 309 310 On platforms that support the necessary fd-based functions a symlink 311 attack resistant version of :func:`rmtree` is used by default. On other 312 platforms, the :func:`rmtree` implementation is susceptible to a symlink 313 attack: given proper timing and circumstances, attackers can manipulate 314 symlinks on the filesystem to delete files they wouldn't be able to access 315 otherwise. Applications can use the :data:`rmtree.avoids_symlink_attacks` 316 function attribute to determine which case applies. 317 318 If *onexc* is provided, it must be a callable that accepts three parameters: 319 *function*, *path*, and *excinfo*. 320 321 The first parameter, *function*, is the function which raised the exception; 322 it depends on the platform and implementation. The second parameter, 323 *path*, will be the path name passed to *function*. The third parameter, 324 *excinfo*, is the exception that was raised. Exceptions raised by *onexc* 325 will not be caught. 326 327 The deprecated *onerror* is similar to *onexc*, except that the third 328 parameter it receives is the tuple returned from :func:`sys.exc_info`. 329 330 .. audit-event:: shutil.rmtree path,dir_fd shutil.rmtree 331 332 .. versionchanged:: 3.3 333 Added a symlink attack resistant version that is used automatically 334 if platform supports fd-based functions. 335 336 .. versionchanged:: 3.8 337 On Windows, will no longer delete the contents of a directory junction 338 before removing the junction. 339 340 .. versionchanged:: 3.11 341 Added the *dir_fd* parameter. 342 343 .. versionchanged:: 3.12 344 Added the *onexc* parameter, deprecated *onerror*. 345 346 .. versionchanged:: 3.13 347 :func:`!rmtree` now ignores :exc:`FileNotFoundError` exceptions for all 348 but the top-level path. 349 Exceptions other than :exc:`OSError` and subclasses of :exc:`!OSError` 350 are now always propagated to the caller. 351 352 .. attribute:: rmtree.avoids_symlink_attacks 353 354 Indicates whether the current platform and implementation provides a 355 symlink attack resistant version of :func:`rmtree`. Currently this is 356 only true for platforms supporting fd-based directory access functions. 357 358 .. versionadded:: 3.3 359 360 361.. function:: move(src, dst, copy_function=copy2) 362 363 Recursively move a file or directory (*src*) to another location and return 364 the destination. 365 366 If *dst* is an existing directory or a symlink to a directory, then *src* 367 is moved inside that directory. The destination path in that directory must 368 not already exist. 369 370 If *dst* already exists but is not a directory, it may be overwritten 371 depending on :func:`os.rename` semantics. 372 373 If the destination is on the current filesystem, then :func:`os.rename` is 374 used. Otherwise, *src* is copied to the destination using *copy_function* 375 and then removed. In case of symlinks, a new symlink pointing to the target 376 of *src* will be created as the destination and *src* will be removed. 377 378 If *copy_function* is given, it must be a callable that takes two arguments, 379 *src* and the destination, and will be used to copy *src* to the destination 380 if :func:`os.rename` cannot be used. If the source is a directory, 381 :func:`copytree` is called, passing it the *copy_function*. The 382 default *copy_function* is :func:`copy2`. Using :func:`~shutil.copy` as the 383 *copy_function* allows the move to succeed when it is not possible to also 384 copy the metadata, at the expense of not copying any of the metadata. 385 386 .. audit-event:: shutil.move src,dst shutil.move 387 388 .. versionchanged:: 3.3 389 Added explicit symlink handling for foreign filesystems, thus adapting 390 it to the behavior of GNU's :program:`mv`. 391 Now returns *dst*. 392 393 .. versionchanged:: 3.5 394 Added the *copy_function* keyword argument. 395 396 .. versionchanged:: 3.8 397 Platform-specific fast-copy syscalls may be used internally in order to 398 copy the file more efficiently. See 399 :ref:`shutil-platform-dependent-efficient-copy-operations` section. 400 401 .. versionchanged:: 3.9 402 Accepts a :term:`path-like object` for both *src* and *dst*. 403 404.. function:: disk_usage(path) 405 406 Return disk usage statistics about the given path as a :term:`named tuple` 407 with the attributes *total*, *used* and *free*, which are the amount of 408 total, used and free space, in bytes. *path* may be a file or a 409 directory. 410 411 .. note:: 412 413 On Unix filesystems, *path* must point to a path within a **mounted** 414 filesystem partition. On those platforms, CPython doesn't attempt to 415 retrieve disk usage information from non-mounted filesystems. 416 417 .. versionadded:: 3.3 418 419 .. versionchanged:: 3.8 420 On Windows, *path* can now be a file or directory. 421 422 .. availability:: Unix, Windows. 423 424.. function:: chown(path, user=None, group=None, *, dir_fd=None, \ 425 follow_symlinks=True) 426 427 Change owner *user* and/or *group* of the given *path*. 428 429 *user* can be a system user name or a uid; the same applies to *group*. At 430 least one argument is required. 431 432 See also :func:`os.chown`, the underlying function. 433 434 .. audit-event:: shutil.chown path,user,group shutil.chown 435 436 .. availability:: Unix. 437 438 .. versionadded:: 3.3 439 440 .. versionchanged:: 3.13 441 Added *dir_fd* and *follow_symlinks* parameters. 442 443 444.. function:: which(cmd, mode=os.F_OK | os.X_OK, path=None) 445 446 Return the path to an executable which would be run if the given *cmd* was 447 called. If no *cmd* would be called, return ``None``. 448 449 *mode* is a permission mask passed to :func:`os.access`, by default 450 determining if the file exists and is executable. 451 452 *path* is a "``PATH`` string" specifying the directories to look in, 453 delimited by :data:`os.pathsep`. When no *path* is specified, the 454 :envvar:`PATH` environment variable is read from :data:`os.environ`, 455 falling back to :data:`os.defpath` if it is not set. 456 457 On Windows, the current directory is prepended to the *path* if *mode* does 458 not include ``os.X_OK``. When the *mode* does include ``os.X_OK``, the 459 Windows API ``NeedCurrentDirectoryForExePathW`` will be consulted to 460 determine if the current directory should be prepended to *path*. To avoid 461 consulting the current working directory for executables: set the environment 462 variable ``NoDefaultCurrentDirectoryInExePath``. 463 464 Also on Windows, the :envvar:`PATHEXT` environment variable is used to 465 resolve commands that may not already include an extension. For example, 466 if you call ``shutil.which("python")``, :func:`which` will search ``PATHEXT`` 467 to know that it should look for ``python.exe`` within the *path* 468 directories. For example, on Windows:: 469 470 >>> shutil.which("python") 471 'C:\\Python33\\python.EXE' 472 473 This is also applied when *cmd* is a path that contains a directory 474 component:: 475 476 >> shutil.which("C:\\Python33\\python") 477 'C:\\Python33\\python.EXE' 478 479 .. versionadded:: 3.3 480 481 .. versionchanged:: 3.8 482 The :class:`bytes` type is now accepted. If *cmd* type is 483 :class:`bytes`, the result type is also :class:`bytes`. 484 485 .. versionchanged:: 3.12 486 On Windows, the current directory is no longer prepended to the search 487 path if *mode* includes ``os.X_OK`` and WinAPI 488 ``NeedCurrentDirectoryForExePathW(cmd)`` is false, else the current 489 directory is prepended even if it is already in the search path; 490 ``PATHEXT`` is used now even when *cmd* includes a directory component 491 or ends with an extension that is in ``PATHEXT``; and filenames that 492 have no extension can now be found. 493 494.. exception:: Error 495 496 This exception collects exceptions that are raised during a multi-file 497 operation. For :func:`copytree`, the exception argument is a list of 3-tuples 498 (*srcname*, *dstname*, *exception*). 499 500.. _shutil-platform-dependent-efficient-copy-operations: 501 502Platform-dependent efficient copy operations 503~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 504 505Starting from Python 3.8, all functions involving a file copy 506(:func:`copyfile`, :func:`~shutil.copy`, :func:`copy2`, 507:func:`copytree`, and :func:`move`) may use 508platform-specific "fast-copy" syscalls in order to copy the file more 509efficiently (see :issue:`33671`). 510"fast-copy" means that the copying operation occurs within the kernel, avoiding 511the use of userspace buffers in Python as in "``outfd.write(infd.read())``". 512 513On macOS `fcopyfile`_ is used to copy the file content (not metadata). 514 515On Linux :func:`os.sendfile` is used. 516 517On Windows :func:`shutil.copyfile` uses a bigger default buffer size (1 MiB 518instead of 64 KiB) and a :func:`memoryview`-based variant of 519:func:`shutil.copyfileobj` is used. 520 521If the fast-copy operation fails and no data was written in the destination 522file then shutil will silently fallback on using less efficient 523:func:`copyfileobj` function internally. 524 525.. versionchanged:: 3.8 526 527.. _shutil-copytree-example: 528 529copytree example 530~~~~~~~~~~~~~~~~ 531 532An example that uses the :func:`ignore_patterns` helper:: 533 534 from shutil import copytree, ignore_patterns 535 536 copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*')) 537 538This will copy everything except ``.pyc`` files and files or directories whose 539name starts with ``tmp``. 540 541Another example that uses the *ignore* argument to add a logging call:: 542 543 from shutil import copytree 544 import logging 545 546 def _logpath(path, names): 547 logging.info('Working in %s', path) 548 return [] # nothing will be ignored 549 550 copytree(source, destination, ignore=_logpath) 551 552 553.. _shutil-rmtree-example: 554 555rmtree example 556~~~~~~~~~~~~~~ 557 558This example shows how to remove a directory tree on Windows where some 559of the files have their read-only bit set. It uses the onexc callback 560to clear the readonly bit and reattempt the remove. Any subsequent failure 561will propagate. :: 562 563 import os, stat 564 import shutil 565 566 def remove_readonly(func, path, _): 567 "Clear the readonly bit and reattempt the removal" 568 os.chmod(path, stat.S_IWRITE) 569 func(path) 570 571 shutil.rmtree(directory, onexc=remove_readonly) 572 573.. _archiving-operations: 574 575Archiving operations 576-------------------- 577 578.. versionadded:: 3.2 579 580.. versionchanged:: 3.5 581 Added support for the *xztar* format. 582 583 584High-level utilities to create and read compressed and archived files are also 585provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. 586 587.. function:: make_archive(base_name, format, [root_dir, [base_dir, [verbose, [dry_run, [owner, [group, [logger]]]]]]]) 588 589 Create an archive file (such as zip or tar) and return its name. 590 591 *base_name* is the name of the file to create, including the path, minus 592 any format-specific extension. 593 594 *format* is the archive format: one of 595 "zip" (if the :mod:`zlib` module is available), "tar", "gztar" (if the 596 :mod:`zlib` module is available), "bztar" (if the :mod:`bz2` module is 597 available), or "xztar" (if the :mod:`lzma` module is available). 598 599 *root_dir* is a directory that will be the root directory of the 600 archive, all paths in the archive will be relative to it; for example, 601 we typically chdir into *root_dir* before creating the archive. 602 603 *base_dir* is the directory where we start archiving from; 604 i.e. *base_dir* will be the common prefix of all files and 605 directories in the archive. *base_dir* must be given relative 606 to *root_dir*. See :ref:`shutil-archiving-example-with-basedir` for how to 607 use *base_dir* and *root_dir* together. 608 609 *root_dir* and *base_dir* both default to the current directory. 610 611 If *dry_run* is true, no archive is created, but the operations that would be 612 executed are logged to *logger*. 613 614 *owner* and *group* are used when creating a tar archive. By default, 615 uses the current owner and group. 616 617 *logger* must be an object compatible with :pep:`282`, usually an instance of 618 :class:`logging.Logger`. 619 620 The *verbose* argument is unused and deprecated. 621 622 .. audit-event:: shutil.make_archive base_name,format,root_dir,base_dir shutil.make_archive 623 624 .. note:: 625 626 This function is not thread-safe when custom archivers registered 627 with :func:`register_archive_format` do not support the *root_dir* 628 argument. In this case it 629 temporarily changes the current working directory of the process 630 to *root_dir* to perform archiving. 631 632 .. versionchanged:: 3.8 633 The modern pax (POSIX.1-2001) format is now used instead of 634 the legacy GNU format for archives created with ``format="tar"``. 635 636 .. versionchanged:: 3.10.6 637 This function is now made thread-safe during creation of standard 638 ``.zip`` and tar archives. 639 640.. function:: get_archive_formats() 641 642 Return a list of supported formats for archiving. 643 Each element of the returned sequence is a tuple ``(name, description)``. 644 645 By default :mod:`shutil` provides these formats: 646 647 - *zip*: ZIP file (if the :mod:`zlib` module is available). 648 - *tar*: Uncompressed tar file. Uses POSIX.1-2001 pax format for new archives. 649 - *gztar*: gzip'ed tar-file (if the :mod:`zlib` module is available). 650 - *bztar*: bzip2'ed tar-file (if the :mod:`bz2` module is available). 651 - *xztar*: xz'ed tar-file (if the :mod:`lzma` module is available). 652 653 You can register new formats or provide your own archiver for any existing 654 formats, by using :func:`register_archive_format`. 655 656 657.. function:: register_archive_format(name, function, [extra_args, [description]]) 658 659 Register an archiver for the format *name*. 660 661 *function* is the callable that will be used to unpack archives. The callable 662 will receive the *base_name* of the file to create, followed by the 663 *base_dir* (which defaults to :data:`os.curdir`) to start archiving from. 664 Further arguments are passed as keyword arguments: *owner*, *group*, 665 *dry_run* and *logger* (as passed in :func:`make_archive`). 666 667 If *function* has the custom attribute ``function.supports_root_dir`` set to ``True``, 668 the *root_dir* argument is passed as a keyword argument. 669 Otherwise the current working directory of the process is temporarily 670 changed to *root_dir* before calling *function*. 671 In this case :func:`make_archive` is not thread-safe. 672 673 If given, *extra_args* is a sequence of ``(name, value)`` pairs that will be 674 used as extra keywords arguments when the archiver callable is used. 675 676 *description* is used by :func:`get_archive_formats` which returns the 677 list of archivers. Defaults to an empty string. 678 679 .. versionchanged:: 3.12 680 Added support for functions supporting the *root_dir* argument. 681 682 683.. function:: unregister_archive_format(name) 684 685 Remove the archive format *name* from the list of supported formats. 686 687 688.. function:: unpack_archive(filename[, extract_dir[, format[, filter]]]) 689 690 Unpack an archive. *filename* is the full path of the archive. 691 692 *extract_dir* is the name of the target directory where the archive is 693 unpacked. If not provided, the current working directory is used. 694 695 *format* is the archive format: one of "zip", "tar", "gztar", "bztar", or 696 "xztar". Or any other format registered with 697 :func:`register_unpack_format`. If not provided, :func:`unpack_archive` 698 will use the archive file name extension and see if an unpacker was 699 registered for that extension. In case none is found, 700 a :exc:`ValueError` is raised. 701 702 The keyword-only *filter* argument is passed to the underlying unpacking 703 function. For zip files, *filter* is not accepted. 704 For tar files, it is recommended to set it to ``'data'``, 705 unless using features specific to tar and UNIX-like filesystems. 706 (See :ref:`tarfile-extraction-filter` for details.) 707 The ``'data'`` filter will become the default for tar files 708 in Python 3.14. 709 710 .. audit-event:: shutil.unpack_archive filename,extract_dir,format shutil.unpack_archive 711 712 .. warning:: 713 714 Never extract archives from untrusted sources without prior inspection. 715 It is possible that files are created outside of the path specified in 716 the *extract_dir* argument, e.g. members that have absolute filenames 717 starting with "/" or filenames with two dots "..". 718 719 .. versionchanged:: 3.7 720 Accepts a :term:`path-like object` for *filename* and *extract_dir*. 721 722 .. versionchanged:: 3.12 723 Added the *filter* argument. 724 725.. function:: register_unpack_format(name, extensions, function[, extra_args[, description]]) 726 727 Registers an unpack format. *name* is the name of the format and 728 *extensions* is a list of extensions corresponding to the format, like 729 ``.zip`` for Zip files. 730 731 *function* is the callable that will be used to unpack archives. The 732 callable will receive: 733 734 - the path of the archive, as a positional argument; 735 - the directory the archive must be extracted to, as a positional argument; 736 - possibly a *filter* keyword argument, if it was given to 737 :func:`unpack_archive`; 738 - additional keyword arguments, specified by *extra_args* as a sequence 739 of ``(name, value)`` tuples. 740 741 *description* can be provided to describe the format, and will be returned 742 by the :func:`get_unpack_formats` function. 743 744 745.. function:: unregister_unpack_format(name) 746 747 Unregister an unpack format. *name* is the name of the format. 748 749 750.. function:: get_unpack_formats() 751 752 Return a list of all registered formats for unpacking. 753 Each element of the returned sequence is a tuple 754 ``(name, extensions, description)``. 755 756 By default :mod:`shutil` provides these formats: 757 758 - *zip*: ZIP file (unpacking compressed files works only if the corresponding 759 module is available). 760 - *tar*: uncompressed tar file. 761 - *gztar*: gzip'ed tar-file (if the :mod:`zlib` module is available). 762 - *bztar*: bzip2'ed tar-file (if the :mod:`bz2` module is available). 763 - *xztar*: xz'ed tar-file (if the :mod:`lzma` module is available). 764 765 You can register new formats or provide your own unpacker for any existing 766 formats, by using :func:`register_unpack_format`. 767 768 769.. _shutil-archiving-example: 770 771Archiving example 772~~~~~~~~~~~~~~~~~ 773 774In this example, we create a gzip'ed tar-file archive containing all files 775found in the :file:`.ssh` directory of the user:: 776 777 >>> from shutil import make_archive 778 >>> import os 779 >>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive')) 780 >>> root_dir = os.path.expanduser(os.path.join('~', '.ssh')) 781 >>> make_archive(archive_name, 'gztar', root_dir) 782 '/Users/tarek/myarchive.tar.gz' 783 784The resulting archive contains: 785 786.. code-block:: shell-session 787 788 $ tar -tzvf /Users/tarek/myarchive.tar.gz 789 drwx------ tarek/staff 0 2010-02-01 16:23:40 ./ 790 -rw-r--r-- tarek/staff 609 2008-06-09 13:26:54 ./authorized_keys 791 -rwxr-xr-x tarek/staff 65 2008-06-09 13:26:54 ./config 792 -rwx------ tarek/staff 668 2008-06-09 13:26:54 ./id_dsa 793 -rwxr-xr-x tarek/staff 609 2008-06-09 13:26:54 ./id_dsa.pub 794 -rw------- tarek/staff 1675 2008-06-09 13:26:54 ./id_rsa 795 -rw-r--r-- tarek/staff 397 2008-06-09 13:26:54 ./id_rsa.pub 796 -rw-r--r-- tarek/staff 37192 2010-02-06 18:23:10 ./known_hosts 797 798 799.. _shutil-archiving-example-with-basedir: 800 801Archiving example with *base_dir* 802~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 803 804In this example, similar to the `one above <shutil-archiving-example_>`_, 805we show how to use :func:`make_archive`, but this time with the usage of 806*base_dir*. We now have the following directory structure: 807 808.. code-block:: shell-session 809 810 $ tree tmp 811 tmp 812 └── root 813 └── structure 814 ├── content 815 └── please_add.txt 816 └── do_not_add.txt 817 818In the final archive, :file:`please_add.txt` should be included, but 819:file:`do_not_add.txt` should not. Therefore we use the following:: 820 821 >>> from shutil import make_archive 822 >>> import os 823 >>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive')) 824 >>> make_archive( 825 ... archive_name, 826 ... 'tar', 827 ... root_dir='tmp/root', 828 ... base_dir='structure/content', 829 ... ) 830 '/Users/tarek/my_archive.tar' 831 832Listing the files in the resulting archive gives us: 833 834.. code-block:: shell-session 835 836 $ python -m tarfile -l /Users/tarek/myarchive.tar 837 structure/content/ 838 structure/content/please_add.txt 839 840 841Querying the size of the output terminal 842---------------------------------------- 843 844.. function:: get_terminal_size(fallback=(columns, lines)) 845 846 Get the size of the terminal window. 847 848 For each of the two dimensions, the environment variable, ``COLUMNS`` 849 and ``LINES`` respectively, is checked. If the variable is defined and 850 the value is a positive integer, it is used. 851 852 When ``COLUMNS`` or ``LINES`` is not defined, which is the common case, 853 the terminal connected to :data:`sys.__stdout__` is queried 854 by invoking :func:`os.get_terminal_size`. 855 856 If the terminal size cannot be successfully queried, either because 857 the system doesn't support querying, or because we are not 858 connected to a terminal, the value given in ``fallback`` parameter 859 is used. ``fallback`` defaults to ``(80, 24)`` which is the default 860 size used by many terminal emulators. 861 862 The value returned is a named tuple of type :class:`os.terminal_size`. 863 864 See also: The Single UNIX Specification, Version 2, 865 `Other Environment Variables`_. 866 867 .. versionadded:: 3.3 868 869 .. versionchanged:: 3.11 870 The ``fallback`` values are also used if :func:`os.get_terminal_size` 871 returns zeroes. 872 873.. _`fcopyfile`: 874 http://www.manpagez.com/man/3/copyfile/ 875 876.. _`Other Environment Variables`: 877 https://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html#tag_002_003 878