bpo-22021: Update root_dir and base_dir documentation in shutil (GH-1… · python/cpython@d5489a9 (original) (raw)
`` @@ -477,12 +477,14 @@ provided. They rely on the :mod:zipfile and :mod:tarfile modules.
``
477
477
`` available), or "xztar" (if the :mod:lzma module is available).
``
478
478
``
479
479
` root_dir is a directory that will be the root directory of the
`
480
``
`-
archive; for example, we typically chdir into root_dir before creating the
`
481
``
`-
archive.
`
``
480
`+
archive, all paths in the archive will be relative to it; for example,
`
``
481
`+
we typically chdir into root_dir before creating the archive.
`
482
482
``
483
483
` base_dir is the directory where we start archiving from;
`
484
484
` i.e. base_dir will be the common prefix of all files and
`
485
``
`-
directories in the archive.
`
``
485
`+
directories in the archive. base_dir must be given relative
`
``
486
`` +
to root_dir. See :ref:shutil-archiving-example-with-basedir for how to
``
``
487
`+
use base_dir and root_dir together.
`
486
488
``
487
489
` root_dir and base_dir both default to the current directory.
`
488
490
``
`@@ -626,6 +628,48 @@ The resulting archive contains:
`
626
628
` -rw-r--r-- tarek/staff 37192 2010-02-06 18:23:10 ./known_hosts
`
627
629
``
628
630
``
``
631
`+
.. _shutil-archiving-example-with-basedir:
`
``
632
+
``
633
`+
Archiving example with base_dir
`
``
634
`+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`
``
635
+
``
636
`` +
In this example, similar to the one above <shutil-archiving-example_>_,
``
``
637
`` +
we show how to use :func:make_archive, but this time with the usage of
``
``
638
`+
base_dir. We now have the following directory structure:
`
``
639
+
``
640
`+
.. code-block:: shell-session
`
``
641
+
``
642
`+
$ tree tmp
`
``
643
`+
tmp
`
``
644
`+
└── root
`
``
645
`+
└── structure
`
``
646
`+
├── content
`
``
647
`+
└── please_add.txt
`
``
648
`+
└── do_not_add.txt
`
``
649
+
``
650
`` +
In the final archive, :file:please_add.txt should be included, but
``
``
651
`` +
:file:do_not_add.txt should not. Therefore we use the following::
``
``
652
+
``
653
`+
from shutil import make_archive
`
``
654
`+
import os
`
``
655
`+
archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
`
``
656
`+
make_archive(
`
``
657
`+
... archive_name,
`
``
658
`+
... 'tar',
`
``
659
`+
... root_dir='tmp/root',
`
``
660
`+
... base_dir='structure/content',
`
``
661
`+
... )
`
``
662
`+
'/Users/tarek/my_archive.tar'
`
``
663
+
``
664
`+
Listing the files in the resulting archive gives us:
`
``
665
+
``
666
`+
.. code-block:: shell-session
`
``
667
+
``
668
`+
$ python -m tarfile -l /Users/tarek/myarchive.tar
`
``
669
`+
structure/content/
`
``
670
`+
structure/content/please_add.txt
`
``
671
+
``
672
+
629
673
`Querying the size of the output terminal
`
630
674
`----------------------------------------
`
631
675
``