From 9b1b0e54e7fde3433effc4bc259889267042d9c9 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 31 Oct 2014 10:02:40 +0100 Subject: #22613: elaborate on arguments of shutil archival functions (thanks Jacques Ducasse) --- Doc/library/shutil.rst | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index e4f348c..998254f 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -449,12 +449,17 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. *root_dir* and *base_dir* both default to the current directory. + If *dry_run* is true, no archive is created, but the operations that would be + executed are logged to *logger*. + *owner* and *group* are used when creating a tar archive. By default, uses the current owner and group. *logger* must be an object compatible with :pep:`282`, usually an instance of :class:`logging.Logger`. + The *verbose* argument is currently unused. + .. function:: get_archive_formats() @@ -474,14 +479,19 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. .. function:: register_archive_format(name, function, [extra_args, [description]]) - Register an archiver for the format *name*. *function* is a callable that - will be used to invoke the archiver. + Register an archiver for the format *name*. + + *function* is the callable that will be used to unpack archives. The callable + will receive the *base_name* of the file to create, followed by the + *base_dir* (which defaults to :data:`os.curdir`) to start archiving from. + Further arguments are passed as keyword arguments: *owner*, *group*, + *dry_run* and *logger* (as passed in :func:`make_archive`). If given, *extra_args* is a sequence of ``(name, value)`` pairs that will be used as extra keywords arguments when the archiver callable is used. *description* is used by :func:`get_archive_formats` which returns the - list of archivers. Defaults to an empty list. + list of archivers. Defaults to an empty string. .. function:: unregister_archive_format(name) -- cgit v0.12