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