[Python-checkins] bpo-22021: Update root_dir and base_dir documentation in shutil (GH-10367)

Miss Islington (bot) webhook-mailer at python.org
Mon Jun 8 01:07:14 EDT 2020


https://github.com/python/cpython/commit/d5489a964fadc028c7086218702daf6fae087340
commit: d5489a964fadc028c7086218702daf6fae087340
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2020-06-07T22:07:06-07:00
summary:

bpo-22021: Update root_dir and base_dir documentation in shutil (GH-10367)


Also added an example in shutil in order to make more clear how they are to be used.

Initially reported by Weinan Li on bpo.
(cherry picked from commit 7633371dace67aaa21eb4b86f889441571ec4167)

Co-authored-by: Lysandros Nikolaou <lisandrosnik at gmail.com>

files:
M Doc/library/shutil.rst

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 12e69a4ea040c..799505858f7f5 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -477,12 +477,14 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
    available), or "xztar" (if the :mod:`lzma` module is available).
 
    *root_dir* is a directory that will be the root directory of the
-   archive; for example, we typically chdir into *root_dir* before creating the
-   archive.
+   archive, all paths in the archive will be relative to it; for example,
+   we typically chdir into *root_dir* before creating the archive.
 
    *base_dir* is the directory where we start archiving from;
    i.e. *base_dir* will be the common prefix of all files and
-   directories in the archive.
+   directories in the archive.  *base_dir* must be given relative
+   to *root_dir*.  See :ref:`shutil-archiving-example-with-basedir` for how to
+   use *base_dir* and *root_dir* together.
 
    *root_dir* and *base_dir* both default to the current directory.
 
@@ -626,6 +628,48 @@ The resulting archive contains:
     -rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts
 
 
+.. _shutil-archiving-example-with-basedir:
+
+Archiving example with *base_dir*
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this example, similar to the `one above <shutil-archiving-example_>`_,
+we show how to use :func:`make_archive`, but this time with the usage of
+*base_dir*.  We now have the following directory structure:
+
+.. code-block:: shell-session
+
+    $ tree tmp
+    tmp
+    └── root
+        └── structure
+            ├── content
+                └── please_add.txt
+            └── do_not_add.txt
+
+In the final archive, :file:`please_add.txt` should be included, but
+:file:`do_not_add.txt` should not.  Therefore we use the following::
+
+    >>> from shutil import make_archive
+    >>> import os
+    >>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
+    >>> make_archive(
+    ...     archive_name,
+    ...     'tar',
+    ...     root_dir='tmp/root',
+    ...     base_dir='structure/content',
+    ... )
+    '/Users/tarek/my_archive.tar'
+
+Listing the files in the resulting archive gives us:
+
+.. code-block:: shell-session
+
+    $ python -m tarfile -l /Users/tarek/myarchive.tar
+    structure/content/
+    structure/content/please_add.txt
+
+
 Querying the size of the output terminal
 ----------------------------------------
 



More information about the Python-checkins mailing list