Debian Codegraph @

Doc/library/shutil.rst

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