Skip to content

[3.6] bpo-22021: Update root_dir and base_dir documentation in shutil (GH-10367) #20712

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
miss-islington wants to merge 1 commit into from
Closed

[3.6] bpo-22021: Update root_dir and base_dir documentation in shutil (GH-10367) #20712

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 47 additions & 3 deletions Doc/library/shutil.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -623,6 +625,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
----------------------------------------

Expand Down