bpo-22021: Update root_dir and base_dir documentation in shutil (GH-1… · python/cpython@12dfbae (original) (raw)
`` @@ -567,12 +567,14 @@ provided. They rely on the :mod:zipfile and :mod:tarfile modules.
``
567
567
`` available), or "xztar" (if the :mod:lzma module is available).
``
568
568
``
569
569
` root_dir is a directory that will be the root directory of the
`
570
``
`-
archive; for example, we typically chdir into root_dir before creating the
`
571
``
`-
archive.
`
``
570
`+
archive, all paths in the archive will be relative to it; for example,
`
``
571
`+
we typically chdir into root_dir before creating the archive.
`
572
572
``
573
573
` base_dir is the directory where we start archiving from;
`
574
574
` i.e. base_dir will be the common prefix of all files and
`
575
``
`-
directories in the archive.
`
``
575
`+
directories in the archive. base_dir must be given relative
`
``
576
`` +
to root_dir. See :ref:shutil-archiving-example-with-basedir for how to
``
``
577
`+
use base_dir and root_dir together.
`
576
578
``
577
579
` root_dir and base_dir both default to the current directory.
`
578
580
``
`@@ -724,6 +726,48 @@ The resulting archive contains:
`
724
726
` -rw-r--r-- tarek/staff 37192 2010-02-06 18:23:10 ./known_hosts
`
725
727
``
726
728
``
``
729
`+
.. _shutil-archiving-example-with-basedir:
`
``
730
+
``
731
`+
Archiving example with base_dir
`
``
732
`+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`
``
733
+
``
734
`` +
In this example, similar to the one above <shutil-archiving-example_>_,
``
``
735
`` +
we show how to use :func:make_archive, but this time with the usage of
``
``
736
`+
base_dir. We now have the following directory structure:
`
``
737
+
``
738
`+
.. code-block:: shell-session
`
``
739
+
``
740
`+
$ tree tmp
`
``
741
`+
tmp
`
``
742
`+
└── root
`
``
743
`+
└── structure
`
``
744
`+
├── content
`
``
745
`+
└── please_add.txt
`
``
746
`+
└── do_not_add.txt
`
``
747
+
``
748
`` +
In the final archive, :file:please_add.txt should be included, but
``
``
749
`` +
:file:do_not_add.txt should not. Therefore we use the following::
``
``
750
+
``
751
`+
from shutil import make_archive
`
``
752
`+
import os
`
``
753
`+
archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
`
``
754
`+
make_archive(
`
``
755
`+
... archive_name,
`
``
756
`+
... 'tar',
`
``
757
`+
... root_dir='tmp/root',
`
``
758
`+
... base_dir='structure/content',
`
``
759
`+
... )
`
``
760
`+
'/Users/tarek/my_archive.tar'
`
``
761
+
``
762
`+
Listing the files in the resulting archive gives us:
`
``
763
+
``
764
`+
.. code-block:: shell-session
`
``
765
+
``
766
`+
$ python -m tarfile -l /Users/tarek/myarchive.tar
`
``
767
`+
structure/content/
`
``
768
`+
structure/content/please_add.txt
`
``
769
+
``
770
+
727
771
`Querying the size of the output terminal
`
728
772
`----------------------------------------
`
729
773
``