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