Add entry for shutil's archiving operations.

rhettinger · rhettinger · commit 0929b1fc70e2 · 2011-01-23T11:29:08.000Z
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
@@ -234,19 +234,21 @@ Another example that uses the *ignore* argument to add a logging call::
    copytree(source, destination, ignore=_logpath)
 
 
-Archives operations
--------------------
+.. _archiving-operations:
+
+Archiving operations
+--------------------
 
 .. function:: make_archive(base_name, format, [root_dir, [base_dir, [verbose, [dry_run, [owner, [group, [logger]]]]]]])
 
-   Create an archive file (e.g. zip or tar) and returns its name.
+   Create an archive file (such as zip or tar) and return its name.
 
    *base_name* is the name of the file to create, including the path, minus
    any format-specific extension. *format* is the archive format: one of
    "zip", "tar", "bztar" (if the :mod:`bz2` module is available) or "gztar".
 
    *root_dir* is a directory that will be the root directory of the
-   archive; i.e. we typically chdir into *root_dir* before creating the
+   archive; for example, we typically chdir into *root_dir* before creating the
    archive.
 
    *base_dir* is the directory where we start archiving from;
@@ -258,6 +260,8 @@ Archives operations
    *owner* and *group* are used when creating a tar archive. By default,
    uses the current owner and group.
 
+   *logger* is an instance of :class:`logging.Logger`.
+
    .. versionadded:: 3.2
 
 
@@ -284,7 +288,7 @@ Archives operations
    Registers an archiver for the format *name*. *function* is a callable that
    will be used to invoke the archiver.
 
-   If given, *extra_args* is a sequence of ``(name, value)`` that will be
+   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
@@ -316,7 +320,7 @@ Archives operations
    .. versionadded:: 3.2
 
 
-.. function:: register_unpack_format(name, extensions, function[, extra_args[,description]])
+.. function:: register_unpack_format(name, extensions, function[, extra_args[, description]])
 
    Registers an unpack format. *name* is the name of the format and
    *extensions* is a list of extensions corresponding to the format, like
diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst
@@ -1194,6 +1194,40 @@ The :func:`shutil.copytree` function has two new options:
 
 (Contributed by Tarek Ziadé.)
 
+In addition, the :mod:`shutil` module now supports :ref:`archiving operations
+<archiving-operations>` for zipfiles, uncompressed tarfiles, gzipped tarfiles,
+and bzipped tarfiles.  And there are functions for registering additional
+archiving file formats (such as xz compressed tarfiles or custom formats).
+
+The principal functions are :func:`~shutil.make_archive` and
+:func:`~shutil.unpack_archive`.  By default, both operate on the current
+directory (which can be set by :func:`os.chdir`) and on any sub-directories.
+The archive filename needs to specified with a full pathname.  The archiving
+step is non-destructive (the original files are left unchanged).
+
+::
+
+    >>> import shutil, pprint
+    >>> os.chdir('mydata')                               # change to the source directory
+    >>> f = make_archive('/var/backup/mydata', 'zip')    # archive the current directory
+    >>> f                                                # show the name of archive
+    '/var/backup/mydata.zip'
+    >>> os.chdir('tmp')                                  # change to an unpacking
+    >>> shutil.unpack_archive('/var/backup/mydata.zip')  # recover the data
+    >>> pprint.pprint(shutil.get_archive_formats())      # display known formats
+    [('bztar', "bzip2'ed tar-file"),
+     ('gztar', "gzip'ed tar-file"),
+     ('tar', 'uncompressed tar file'),
+     ('zip', 'ZIP file')]
+    >>> shutil.register_archive_format(                  # register a new archive format
+            name = 'xz',
+            function = 'xz.compress',
+            extra_args = [('level', 8)],
+            description = 'xz compression'
+    )
+
+(Contributed by Tarek Ziadé.)
+
 sqlite3
 -------
 
@@ -1663,6 +1697,8 @@ reading directly from dictionaries and strings.
             - non-UTF8 percent encoding of non-ASCII characters
           Issue 2987 for IPv6 (RFC2732) support in urlparse
 
+.. XXX reprlib.recursive_repr
+
 
 Multi-threading
 ===============
