[Python-checkins] gh-88513: clarify shutil.copytree's dirs_exist_ok arg (GH-91434) (GH-91464)

Fri Apr 15 09:55:17 EDT 2022

https://github.com/python/cpython/commit/289f27d06b0d19739b114f6b2f60a6264655b8f6
commit: 289f27d06b0d19739b114f6b2f60a6264655b8f6
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: ambv <lukasz at langa.pl>
date: 2022年04月15日T15:55:13+02:00
summary:
gh-88513: clarify shutil.copytree's dirs_exist_ok arg (GH-91434) (GH-91464)
* add a paragraph to document this kwarg in detail
* update docstring in the source accordingly
(cherry picked from commit f33e2c87a83917b5139d97fd8ef7cba7223ebef5)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra at gmail.com>
files:
A Misc/NEWS.d/next/Documentation/2022-04-10-20-28-20.bpo-44347.Q1m3DM.rst
M Doc/library/shutil.rst
M Lib/shutil.py

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 5f71049f918e0..8ce0e80ec8120 100644
--- a/Doc/library/shutil.rst
+++ b/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
diff --git a/Lib/shutil.py b/Lib/shutil.py
index 37bf98df79672..2768bcf6ab815 100644
--- a/Lib/shutil.py
+++ b/Lib/shutil.py
@@ -516,9 +516,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
@@ -549,6 +546,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:
diff --git a/Misc/NEWS.d/next/Documentation/2022-04-10-20-28-20.bpo-44347.Q1m3DM.rst b/Misc/NEWS.d/next/Documentation/2022-04-10-20-28-20.bpo-44347.Q1m3DM.rst
new file mode 100644
index 0000000000000..27aa5742cd008
--- /dev/null
+++ b/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`.
