Skip to content

bpo-22021: Update root_dir and base_dir documentation in shutil #10367

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

Merged
miss-islington merged 5 commits into from
Jun 8, 2020
Merged

bpo-22021: Update root_dir and base_dir documentation in shutil #10367

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1a377d8
bpo-22021: Update root_dir and base_dir documentation and added an ex…
lysnikolaou Nov 6, 2018
6adce16
bpo-22021: Better wording in the explanation of root dir, minor chang…
lysnikolaou Mar 4, 2019
2d3f205
bpo-22021: Yet another rewording of the explanation, minor tweaks to …
lysnikolaou May 13, 2019
55858e7
bpo-22021: Link to the example from the make_archive function docs
lysnikolaou May 13, 2019
147b454
Update shutil.rst
berkerpeksag May 14, 2019
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 @@ -531,12 +531,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 @@ -680,6 +682,48 @@ The resulting archive contains:
-rw-r--r-- tarek/staff 37192 2010-02-06 18:23:10 ./known_hosts


.. _shutil-archiving-example-with-basedir:
Copy link
Copy Markdown
Member

@berkerpeksag berkerpeksag May 13, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you please link to the example from the make_archive() documentation?

Copy link
Copy Markdown
Member Author

@lysnikolaou lysnikolaou May 13, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @berkerpeksag for the review. From where exactly would you think it would be best to link? From the title itself or from somewhere in the text?

Copy link
Copy Markdown
Member

@berkerpeksag berkerpeksag May 13, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm thinking about adding something like "See :ref:`shutil-archiving-example-with-basedir` for how to use *base_dir* and *root_dir* together." after https://github.com/python/cpython/pull/10367/files#diff-bda6196613f849e0aa43c7e2dd9f6068R540

What do you think?

Copy link
Copy Markdown
Member Author

@lysnikolaou lysnikolaou May 13, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would be really nice actually. This way someone, who might not scroll all the way down, will not miss the example. I think it may be a better idea to not have a whole new paragraph for the "See the example" bit. It feels more natural to me to just append it at the end of the current paragraph. What is your view on that?

Copy link
Copy Markdown
Member

@berkerpeksag berkerpeksag May 13, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good to me!


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