[Python-checkins] gh-88513: clarify shutil.copytree's dirs_exist_ok arg (GH-91434) (GH-91465)
JelleZijlstra
webhook-mailer at python.org
Tue Apr 12 22:58:17 EDT 2022
https://github.com/python/cpython/commit/a8d245a675c11972390d1cfaea4a97151162e6e7
commit: a8d245a675c11972390d1cfaea4a97151162e6e7
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: JelleZijlstra <jelle.zijlstra at gmail.com>
date: 2022-04-12T19:58:02-07:00
summary:
gh-88513: clarify shutil.copytree's dirs_exist_ok arg (GH-91434) (GH-91465)
* add a paragraph to document this kwarg in detail
* update docstring in the source accordingly
(cherry picked from commit f33e2c87a83917b5139d97fd8ef7cba7223ebef5)
Co-authored-by: Jack DeVries <jdevries3133 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 c048cdf9b2cbd..48a60c0d28d07 100644
--- a/Lib/shutil.py
+++ b/Lib/shutil.py
@@ -526,9 +526,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
@@ -559,6 +556,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`.
More information about the Python-checkins
mailing list