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.
This commit is contained in:
Lysandros Nikolaou 2020-06-08 08:01:21 +03:00 committed by GitHub
parent 37eed5a9ee
commit 7633371dac
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 47 additions and 3 deletions

View File

@ -570,12 +570,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.
@ -727,6 +729,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
----------------------------------------