Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-10-31 05:31:20 +00:00
Code Issues Projects Releases Packages Wiki Activity

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

Browse source 
* add a paragraph to document this kwarg in detail
* update docstring in the source accordingly
This commit is contained in:
Jack DeVries 2022-04-11 20:57:52 -04:00 • committed by GitHub
parent 9ebcece82f
commit f33e2c87a8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 17 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

17
Doc/library/shutil.rst
View file

@ -230,9 +230,8 @@ Directory and files operations
dirs_exist_ok=False) dirs_exist_ok=False)
Recursively copy an entire directory tree rooted at *src* to a directory Recursively copy an entire directory tree rooted at *src* to a directory
named *dst* and return the destination directory. *dirs_exist_ok* dictates named *dst* and return the destination directory. All intermediate
whether to raise an exception in case *dst* or any missing parent directory directories needed to contain *dst* will also be created by default.
already exists.
Permissions and times of directories are copied with :func:`copystat`, Permissions and times of directories are copied with :func:`copystat`,
individual files are copied using :func:`~shutil.copy2`. 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 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 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 as arguments. By default, :func:`~shutil.copy2` is used, but any function
  that supports the same signature (like :func:`~shutil.copy`) can be used. 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 .. audit-event:: shutil.copytree src,dst shutil.copytree
@ -275,7 +280,7 @@ Directory and files operations
.. versionchanged:: 3.2 .. versionchanged:: 3.2
Added the *copy_function* argument to be able to provide a custom copy Added the *copy_function* argument to be able to provide a custom copy
function. 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. errors when *symlinks* is false.
.. versionchanged:: 3.8 .. versionchanged:: 3.8

8
Lib/shutil.py
View file

@ -518,9 +518,6 @@ def copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2,
ignore_dangling_symlinks=False, dirs_exist_ok=False): ignore_dangling_symlinks=False, dirs_exist_ok=False):
"""Recursively copy a directory tree and return the destination directory. """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 exception(s) occur, an Error is raised with a list of reasons.
If the optional symlinks flag is true, symbolic links in the 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 destination path as arguments. By default, copy2() is used, but any
function that supports the same signature (like copy()) can be used. 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) sys.audit("shutil.copytree", src, dst)
with os.scandir(src) as itr: with os.scandir(src) as itr:

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

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