Commit 396fad7a authored by Tarek Ziadé's avatar Tarek Ziadé

Merged revisions 78359-78360 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r78359 | tarek.ziade | 2010-02-23 00:16:41 -0500 (Tue, 23 Feb 2010) | 1 line

  added make_archive (and secondary APIs) to shutil
........
  r78360 | tarek.ziade | 2010-02-23 00:20:22 -0500 (Tue, 23 Feb 2010) | 1 line

  added a note on shutil new APIs
........
parent e04deb1a
...@@ -26,6 +26,8 @@ copying and removal. For operations on individual files, see also the ...@@ -26,6 +26,8 @@ copying and removal. For operations on individual files, see also the
not be correct. On Windows, file owners, ACLs and alternate data streams not be correct. On Windows, file owners, ACLs and alternate data streams
are not copied. are not copied.
Directory and files operations
------------------------------
.. function:: copyfileobj(fsrc, fdst[, length]) .. function:: copyfileobj(fsrc, fdst[, length])
...@@ -150,8 +152,8 @@ copying and removal. For operations on individual files, see also the ...@@ -150,8 +152,8 @@ copying and removal. For operations on individual files, see also the
.. _shutil-example: .. _shutil-example:
Example copytree example
------- ::::::::::::::::
This example is the implementation of the :func:`copytree` function, described This example is the implementation of the :func:`copytree` function, described
above, with the docstring omitted. It demonstrates many of the other functions above, with the docstring omitted. It demonstrates many of the other functions
...@@ -189,3 +191,117 @@ provided by this module. :: ...@@ -189,3 +191,117 @@ provided by this module. ::
if errors: if errors:
raise Error(errors) raise Error(errors)
Another example that uses the :func:`ignore_patterns` helper::
from shutil import copytree, ignore_patterns
copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))
This will copy everything except ``.pyc`` files and files or directories whose
name starts with ``tmp``.
Another example that uses the *ignore* argument to add a logging call::
from shutil import copytree
import logging
def _logpath(path, names):
logging.info('Working in %s' % path)
return [] # nothing will be ignored
copytree(source, destination, ignore=_logpath)
Archives operations
-------------------
.. 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", "ztar", 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.
.. versionadded:: 2.7
.. function:: get_archive_formats()
Returns 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
- *ztar*: compressed 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]])
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
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
:::::::::::::::::
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
...@@ -877,6 +877,9 @@ changes, or look through the Subversion logs for all the details. ...@@ -877,6 +877,9 @@ changes, or look through the Subversion logs for all the details.
accepts a file object, in addition to the path names accepted in earlier accepts a file object, in addition to the path names accepted in earlier
versions. (Contributed by Gabriel Genellina; :issue:`4756`.) versions. (Contributed by Gabriel Genellina; :issue:`4756`.)
* XXX the :mod:`shutil` module has now a :func:`make_archive` function
(see the module doc, contributed by Tarek)
.. ====================================================================== .. ======================================================================
.. whole new modules get described in subsections here .. whole new modules get described in subsections here
......
This diff is collapsed.
This diff is collapsed.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment