classification
Title: Unclear documentation for shutil.copytree()
Type: enhancement Stage: patch review
Components: Documentation, Library (Lib) Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, iritkatriel, jack__d, tilman.vogel
Priority: normal Keywords: patch

Created on 2021-06-08 09:17 by tilman.vogel, last changed 2021-06-10 12:29 by jack__d.

Pull Requests
URL Status Linked Edit
PR 26634 closed jack__d, 2021-06-09 23:54
PR 26643 open jack__d, 2021-06-10 12:29
Messages (4)
msg395315 - (view) Author: Tilman Vogel (tilman.vogel) Date: 2021-06-08 09:17
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.
msg395452 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-06-09 18:22
From the code, this arg is simply passed to os.mkdirs() here:
https://github.com/python/cpython/blob/e6e34e45222b9c7a63ba92386612acf768082ba0/Lib/shutil.py#L450

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?
msg395489 - (view) Author: Jack DeVries (jack__d) * Date: 2021-06-09 22:33
I would like to submit a patch for this. This would be my first contribution :)

I am starting on a patch now.
msg395494 - (view) Author: Jack DeVries (jack__d) * Date: 2021-06-09 23:58
I've created a PR: https://github.com/python/cpython/pull/26634

I forgot to put a news entry, but hopefully that's ok since this is a very small change.
History
Date User Action Args
2021-06-10 12:29:33jack__dsetpull_requests: + pull_request25229
2021-06-09 23:58:19jack__dsetmessages: + msg395494
2021-06-09 23:54:26jack__dsetkeywords: + patch
stage: patch review
pull_requests: + pull_request25220
2021-06-09 22:33:17jack__dsetnosy: + jack__d
messages: + msg395489
2021-06-09 18:23:19iritkatrielsetcomponents: + Library (Lib)
versions: + Python 3.11, - Python 3.8
2021-06-09 18:22:53iritkatrielsetnosy: + iritkatriel
messages: + msg395452
2021-06-08 09:17:12tilman.vogelcreate