gh-88513: clarify shutil.copytree's dirs_exist_ok arg (GH-91434)

* add a paragraph to document this kwarg in detail
* update docstring in the source accordingly

Doc/library/shutil.rst

@@ -230,9 +230,8 @@ 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.  All intermediate
+   directories needed to contain *dst* will also be created by default.
 
    Permissions and times of directories are copied with :func:`copystat`,
    individual files are copied using :func:`~shutil.copy2`.
@@ -263,8 +262,14 @@ 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) and *dst* already exists, a
+   :exc:`FileExistsError` is raised. If *dirs_exist_ok* is true, the copying
+   operation will continue if it encounters existing directories, and files
+   within the *dst* tree will be overwritten by corresponding files from the
+   *src* tree.
 
    .. audit-event:: shutil.copytree src,dst shutil.copytree
 
@@ -275,7 +280,7 @@ Directory and files operations
    .. versionchanged:: 3.2
       Added the *copy_function* argument to be able to provide a custom copy
       function.
-      Added the *ignore_dangling_symlinks* argument to silent dangling symlinks
+      Added the *ignore_dangling_symlinks* argument to silence dangling symlinks
       errors when *symlinks* is false.
 
    .. versionchanged:: 3.8

Lib/shutil.py

@@ -518,9 +518,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
@@ -551,6 +548,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) and `dst` already exists, a
+    `FileExistsError` is raised. If `dirs_exist_ok` is true, the copying
+    operation will continue if it encounters existing directories, and files
+    within the `dst` tree will be overwritten by corresponding files from the
+    `src` tree.
     """
     sys.audit("shutil.copytree", src, dst)
     with os.scandir(src) as itr:

Misc/NEWS.d/next/Documentation/2022-04-10-20-28-20.bpo-44347.Q1m3DM.rst

@@ -0,0 +1 @@
+Clarify the meaning of *dirs_exist_ok*, a kwarg of :func:`shutil.copytree`.