jdevries3133 · Jun 9, 2021 · Jun 10, 2021 · Jun 10, 2021 · Jun 10, 2021 · Jun 10, 2021
@@ -230,9 +230,7 @@ Directory and files operations
               dirs_exist_ok=False)
 
    Recursively copy an entire directory tree rooted at *src* to a directory
-   named *dst* and return the destination directory. *dirs_exist_ok* dictates
-   whether to raise an exception in case *dst* or any missing parent directory
-   already exists.
+   named *dst* and return the destination directory.
 
    Permissions and times of directories are copied with :func:`copystat`,
    individual files are copied using :func:`~shutil.copy2`.
@@ -263,8 +261,13 @@ Directory and files operations
 
    If *copy_function* is given, it must be a callable that will be used to copy
    each file. It will be called with the source path and the destination path
-   as arguments. By default, :func:`~shutil.copy2` is used, but any function
-   that supports the same signature (like :func:`~shutil.copy`) can be used.
+   as arguments. By default, :func:`~shutil.copy2` is used, but any function
+   that supports the same signature (like :func:`~shutil.copy`) can be used.
+
+   If *dirs_exist_ok* is false (the default), a :exc:`FileExistsError` is
+   raised if *dst* already exists. Conversely, *dst* as well as any any parent
+   directory in the path to *dst* will be created if they do not exist when
+   the *dirs_exist_ok* flag is true.
 
    .. audit-event:: shutil.copytree src,dst shutil.copytree
 

@@ -509,9 +509,6 @@ def copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2,
              ignore_dangling_symlinks=False, dirs_exist_ok=False):
     """Recursively copy a directory tree and return the destination directory.
 
-    dirs_exist_ok dictates whether to raise an exception in case dst or any
-    missing parent directory already exists.
-
     If exception(s) occur, an Error is raised with a list of reasons.
 
     If the optional symlinks flag is true, symbolic links in the
@@ -542,6 +539,11 @@ def copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2,
     destination path as arguments. By default, copy2() is used, but any
     function that supports the same signature (like copy()) can be used.
 
+    If dirs_exist_ok is False (the default), a FileExistsError is
+    raised if dst already exists. Furthermore, any parent directory in the
+    path to dst will be created if they do not exist when the dirs_exist_ok
+    flag is True.
+
     """
     sys.audit("shutil.copytree", src, dst)
     with os.scandir(src) as itr:

diff --git a/Misc/NEWS.d/next/Documentation/2020-06-10-16-55-55.bpo-44347.Fjvuw7.rst b/Misc/NEWS.d/next/Documentation/2020-06-10-16-55-55.bpo-44347.Fjvuw7.rst
@@ -0,0 +1,2 @@
+Clarify the meaning of *dirs_exist_ok*, a kwarg passed to the shutil.copytree
+function.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		Clarify the meaning of dirs_exist_ok, a kwarg passed to the shutil.copytree
akulakov Jun 20, 2021 Copy link Copy Markdown Contributor Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. Let's make it a link -- :func:`shutil.copytree`
		function.