shutil.copytree's docstring [1] and documentation [2] states that, "If exception(s) occur, an Error is raised with a list of reasons," but it can raise OSErrors at the top-level call. For example:

>>> import shutil
>>> shutil.copytree(nonexistent_dir, dst)
FileNotFoundError: [WinError 3] The system cannot find the path specified: '...'

>>> shutil.copytree(actually_a_file, dst)
NotADirectoryError: [WinError 267] The directory name is invalid: '...'

>>> shutil.copytree(src, dst_already_exists, dirs_exist_ok=False)
FileExistsError: [WinError 183] Cannot create a file when that file already exists: '...'

The errors above happen because shutil.copytree and shutil._copytree call os.scandir and os.makedir respectively without wrapping any exceptions inside shutil.Error. [3][4]


It seems like shutil.copytree(src, dst) only raises a shutil.Error if an OSError or shutil.Error was raised when copying over a file in src or during a recursive call to shutil.copytree for a subdirectory of src:

>>> shutil.copytree(dir_with_broken_symblink, dst)
shutil.Error: [('a\\symlink', 'b\\symlink', "[Errno 2] No such file or directory: 'a\\\\symlink'")]


Is this behavior intended? Should shutil.copytree be changed so that exceptions for the top level are wrapped inside shutil.Error, or should the documentation for shutil.copytree mention that it can raise exceptions that aren't shutil.Error? (Or is this just a non-issue?)


[1]: https://github.com/python/cpython/blob/b494f5935c92951e75597bfe1c8b1f3112fec270/Lib/shutil.py#L522
[2]: https://docs.python.org/3.10/library/shutil.html?highlight=shutil#shutil.copytree
[3]: https://github.com/python/cpython/blob/b494f5935c92951e75597bfe1c8b1f3112fec270/Lib/shutil.py#L554
[4]: https://github.com/python/cpython/blob/b494f5935c92951e75597bfe1c8b1f3112fec270/Lib/shutil.py#L457