Documentation

(A clear and concise description of the issue.)

In the doc of shutil it says:

If the destination is an existing directory, then *src* is moved inside that
directory. If the destination already exists but is not a directory, it may
be overwritten depending on :func:`os.rename` semantics.

However, before calling os.rename, it checks the existence of the destination path, and raises Error if it exists. see shutil.py.

This behavior is not described in the documentation, and may be different from how files are overwritten in os.rename. For example, os.rename('a.txt', '/b') will silently replace /b/a.txt on Unix, but shutil.move('a.txt', '/b') will raise an Error.

In the docstring however, this is described much more clear:

If the destination is a directory or a symlink to a directory, the source
is moved inside the directory. The destination path must not already
exist.

If the destination already exists but is not a directory, it may be
overwritten depending on os.rename() semantics.

This should be also in the documentation, IMO.

Linked PRs

• gh-113803: Fix inaccurate documentation for shutil.move when dst is an existing directory #113837