Changeset 391 for python/trunk/Doc/library/shutil.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/shutil.rst (modified) (12 diffs)

python/trunk/Doc/library/shutil.rst

@@ -1 @@
-
 :mod:`shutil` --- High-level file operations
 ============================================
@@ -12 +11 @@
    single: copying files
 
+**Source code:** :source:`Lib/shutil.py`
+
+--------------
+
 The :mod:`shutil` module offers a number of high-level operations on files and
 collections of files.  In particular, functions are provided  which support file
@@ -19 +22 @@
 .. warning::
 
-   Even the higher-level file copying functions (:func:`copy`, :func:`copy2`)
-   can't copy all file metadata.
+   Even the higher-level file copying functions (:func:`shutil.copy`,
+   :func:`shutil.copy2`) can't copy all file metadata.
 
    On POSIX platforms, this means that file owner and group are lost as well
@@ -28 +31 @@
    are not copied.
 
+
+.. _file-operations:
+
+Directory and files operations
+------------------------------
 
 .. function:: copyfileobj(fsrc, fdst[, length])
@@ -42 +50 @@
 .. function:: copyfile(src, dst)
 
-   Copy the contents (no metadata) of the file named *src* to a file named *dst*.
-   *dst* must be the complete target file name; look at :func:`copy` for a copy that
-   accepts a target directory path.  If *src* and *dst* are the same files,
-   :exc:`Error` is raised.
+   Copy the contents (no metadata) of the file named *src* to a file named
+   *dst*.  *dst* must be the complete target file name; look at
+   :func:`shutil.copy` for a copy that accepts a target directory path.  If
+   *src* and *dst* are the same files, :exc:`Error` is raised.
    The destination location must be writable; otherwise,  an :exc:`IOError` exception
    will be raised. If *dst* already exists, it will be replaced.   Special files
@@ -75 +83 @@
 .. function:: copy2(src, dst)
 
-   Similar to :func:`copy`, but metadata is copied as well -- in fact, this is just
-   :func:`copy` followed by :func:`copystat`.  This is similar to the
-   Unix command :program:`cp -p`.
+   Similar to :func:`shutil.copy`, but metadata is copied as well -- in fact,
+   this is just :func:`shutil.copy` followed by :func:`copystat`.  This is
+   similar to the Unix command :program:`cp -p`.
 
 
@@ -89 +97 @@
 
 
-.. function:: copytree(src, dst[, symlinks=False[, ignore=None]])
+.. function:: copytree(src, dst, symlinks=False, ignore=None)
 
    Recursively copy an entire directory tree rooted at *src*.  The destination
-   directory, named by *dst*, must not already exist; it will be created as well
-   as missing parent directories.  Permissions and times of directories are
-   copied with :func:`copystat`, individual files are copied using
-   :func:`copy2`.
+   directory, named by *dst*, must not already exist; it will be created as
+   well as missing parent directories.  Permissions and times of directories
+   are copied with :func:`copystat`, individual files are copied using
+   :func:`shutil.copy2`.
 
    If *symlinks* is true, symbolic links in the source tree are represented as
-   symbolic links in the new tree; if false or omitted, the contents of the
-   linked files are copied to the new tree.
+   symbolic links in the new tree, but the metadata of the original links is NOT
+   copied; if false or omitted, the contents and metadata of the linked files
+   are copied to the new tree.
 
    If *ignore* is given, it must be a callable that will receive as its
@@ -154 +163 @@
 .. function:: move(src, dst)
 
-   Recursively move a file or directory to another location.
-
-   If the destination is on the current filesystem, then simply use rename.
-   Otherwise, copy src (with :func:`copy2`) to the dst and then remove src.
+   Recursively move a file or directory (*src*) to another location (*dst*).
+
+   If the destination is a directory or a symlink to a directory, then *src* is
+   moved inside that directory.
+
+   The destination directory must not already exist.  If the destination already
+   exists but is not a directory, it may be overwritten depending on
+   :func:`os.rename` semantics.
+
+   If the destination is on the current filesystem, then :func:`os.rename` is
+   used.  Otherwise, *src* is copied (using :func:`shutil.copy2`) to *dst* and
+   then removed.
 
    .. versionadded:: 2.3
@@ -164 +181 @@
 .. exception:: Error
 
-   This exception collects exceptions that raised during a multi-file operation. For
-   :func:`copytree`, the exception argument is a list of 3-tuples (*srcname*,
-   *dstname*, *exception*).
+   This exception collects exceptions that are raised during a multi-file
+   operation. For :func:`copytree`, the exception argument is a list of 3-tuples
+   (*srcname*, *dstname*, *exception*).
 
    .. versionadded:: 2.3
 
 
-.. _shutil-example:
-
-Example
--------
+.. _copytree-example:
+
+copytree example
+::::::::::::::::
 
 This example is the implementation of the :func:`copytree` function, described
@@ -203 +220 @@
                    copy2(srcname, dstname)
                # XXX What about devices, sockets etc.?
-           except (IOError, os.error), why:
+           except (IOError, os.error) as why:
                errors.append((srcname, dstname, str(why)))
            # catch the Error from the recursive copytree so that we can
            # continue with other files
-           except Error, err:
+           except Error as err:
                errors.extend(err.args[0])
        try:
@@ -214 +231 @@
            # can't copy file access times on Windows
            pass
-       except OSError, why:
+       except OSError as why:
            errors.extend((src, dst, str(why)))
        if errors:
@@ -239 +256 @@
    copytree(source, destination, ignore=_logpath)
 
+
+.. _archiving-operations:
+
+Archiving operations
+--------------------
+
+High-level utilities to create and read compressed and archived files are also
+provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
+
+.. function:: make_archive(base_name, format, [root_dir, [base_dir, [verbose, [dry_run, [owner, [group, [logger]]]]]]])
+
+   Create an archive file (eg. zip or tar) and returns 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" or "gztar".
+
+   *root_dir* is a directory that will be the root directory of the
+   archive; ie. we typically chdir into *root_dir* before creating the
+   archive.
+
+   *base_dir* is the directory where we start archiving from;
+   ie. *base_dir* will be the common prefix of all files and
+   directories in the archive.
+
+   *root_dir* and *base_dir* both default to the current directory.
+
+   *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`.
+
+   .. versionadded:: 2.7
+
+
+.. function:: get_archive_formats()
+
+   Return a list of supported formats for archiving.
+   Each element of the returned sequence is a tuple ``(name, description)``
+
+   By default :mod:`shutil` provides these formats:
+
+   - *gztar*: gzip'ed tar-file
+   - *bztar*: bzip2'ed tar-file
+   - *tar*: uncompressed tar file
+   - *zip*: ZIP file
+
+   You can register new formats or provide your own archiver for any existing
+   formats, by using :func:`register_archive_format`.
+
+   .. versionadded:: 2.7
+
+
+.. 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.
+
+   If given, *extra_args* is a sequence of ``(name, value)`` 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.
+
+   .. versionadded:: 2.7
+
+
+.. function::  unregister_archive_format(name)
+
+   Remove the archive format *name* from the list of supported formats.
+
+   .. versionadded:: 2.7
+
+
+.. _archiving-example:
+
+Archiving example
+:::::::::::::::::
+
+In this example, we create a gzip'ed tar-file archive containing all files
+found in the :file:`.ssh` directory of the user::
+
+    >>> from shutil import make_archive
+    >>> import os
+    >>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
+    >>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))
+    >>> make_archive(archive_name, 'gztar', root_dir)
+    '/Users/tarek/myarchive.tar.gz'
+
+The resulting archive contains::
+
+    $ tar -tzvf /Users/tarek/myarchive.tar.gz
+    drwx------ tarek/staff       0 2010-02-01 16:23:40 ./
+    -rw-r--r-- tarek/staff     609 2008-06-09 13:26:54 ./authorized_keys
+    -rwxr-xr-x tarek/staff      65 2008-06-09 13:26:54 ./config
+    -rwx------ tarek/staff     668 2008-06-09 13:26:54 ./id_dsa
+    -rwxr-xr-x tarek/staff     609 2008-06-09 13:26:54 ./id_dsa.pub
+    -rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa
+    -rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub
+    -rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts