Unclear documentation for shutil.copytree()

[tilmanvogel]

BPO	44347
Nosy	@iritkatriel, @jdevries3133
PRs	bpo-44347: [doc] clarify meaning of shutil.copytree's dirs_exist_ok kwarg #26634 bpo-44347: [doc] clarify meaning of shutil.copytree's dirs_exist_ok kwarg #26643

^{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']

[tilmanvogel]

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 dst would be OK (and copied into) but missing parent directories are just the ones above dst that 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]

From the code, this arg is simply passed to os.mkdirs() here:

cpython/Lib/shutil.py

Line 450 in e6e34e4

os.makedirs(dst, exist_ok=dirs_exist_ok)

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?