From f33e2c87a83917b5139d97fd8ef7cba7223ebef5 Mon Sep 17 00:00:00 2001 From: Jack DeVries Date: Mon, 11 Apr 2022 20:57:52 -0400 Subject: 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 | 17 +++++++++++------ Lib/shutil.py | 8 +++++--- .../2022-04-10-20-28-20.bpo-44347.Q1m3DM.rst | 1 + 3 files changed, 17 insertions(+), 9 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2022-04-10-20-28-20.bpo-44347.Q1m3DM.rst diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index ac271ce..75ffb79 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 22bd86d..de82453 100644 --- a/Lib/shutil.py +++ b/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: 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 0000000..27aa574 --- /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`. -- cgit v0.12