Repository navigation
Unclear documentation for shutil.copytree() #88513
Description
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = None
created_at = <Date 2021-06-08.09:17:12.166>
labels = ['3.9', '3.10', '3.11', 'type-feature', 'library', 'docs']
title = 'Unclear documentation for shutil.copytree()'
updated_at = <Date 2021-06-10.12:29:33.310>
user = 'https://bugs.python.org/tilmanvogel'bugs.python.org fields:
activity = <Date 2021-06-10.12:29:33.310>
actor = 'jack__d'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Library (Lib)']
creation = <Date 2021-06-08.09:17:12.166>
creator = 'tilman.vogel'
dependencies = []
files = []
hgrepos = []
issue_num = 44347
keywords = ['patch']
message_count = 4.0
messages = ['395315', '395452', '395489', '395494']
nosy_count = 4.0
nosy_names = ['docs@python', 'iritkatriel', 'tilman.vogel', 'jack__d']
pr_nums = ['26634', '26643']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue44347'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']
Activity
tilmanvogel commentedon Jun 8, 2021
I donot understand this sentence:
"dirs_exist_ok dictates whether to raise an exception in case dst or any
missing parent directory already exists."
How can a "missing parent directory already exist"?
My understanding would be that an existing
dstwould be OK (and copied into) but missing parent directories are just the ones abovedstthat also don't exist.Until 3.7, missing parent directories were documented to be auto-created (
mkdir -p-style) according to the documentation ("The destination directory, named by dst, must not already exist; it will be created as well as missing parent directories."). Was this feature really removed? If not, then this part was accidentally (?) dropped from documentation?What am I missing? I think, the documentation should be amended to make that clear.
iritkatriel commentedon Jun 9, 2021
From the code, this arg is simply passed to os.mkdirs() here:
cpython/Lib/shutil.py
Line 450 in e6e34e4
os.mkdir is documented here: https://docs.python.org/3/library/os.html#os.makedirs
and says just "If exist_ok is False (the default), an FileExistsError is raised if the target directory already exists."
So I agree that the sentence you highlighted can be improved.
Would you like to submit a patch?
2 remaining items
jdevries3133 commentedon Jun 9, 2021
I would like to submit a patch for this. This would be my first contribution :)
I am starting on a patch now.
jdevries3133 commentedon Jun 9, 2021
I've created a PR: #26634
I forgot to put a news entry, but hopefully that's ok since this is a very small change.
gh-88513: clarify shutil.copytree's dirs_exist_ok arg (GH-91434)
pythongh-88513: clarify shutil.copytree's dirs_exist_ok arg (pythonGH…
JelleZijlstra commentedon Apr 12, 2022
#91434 was merged to address this. Thanks for your contribution @jdevries3133! I'll close this issue once the backports (#91464, #91465) are merged.
gh-88513: clarify shutil.copytree's dirs_exist_ok arg (GH-91434) (GH-…
gh-88513: clarify shutil.copytree's dirs_exist_ok arg (GH-91434) (GH-…
pythongh-88513: clarify shutil.copytree's dirs_exist_ok arg (pythonGH…