shutil: Inconsistent return types when using pathlib

[srittau]

Bug report

Bug description:

Using pathlib with shutil usually works, but there are some quirks when it comes to return types. As an example, see the copy function (but other functions are affected as well):

cpython/Lib/shutil.py

Lines 468 to 484 in 67ded6a

	def copy(src, dst, *, follow_symlinks=True):
	"""Copy data and mode bits ("cp src dst"). Return the file's destination.
	The destination may be a directory.
	If follow_symlinks is false, symlinks won't be followed. This
	resembles GNU's "cp -P src dst".
	If source and destination are the same file, a SameFileError will be
	raised.
	"""
	if os.path.isdir(dst):
	dst = os.path.join(dst, os.path.basename(src))
	copyfile(src, dst, follow_symlinks=follow_symlinks)
	copymode(src, dst, follow_symlinks=follow_symlinks)
	return dst

In this case, if a Path object gets passed in as dst, it will be returned unchanged if it is not a directory, but a str will be returned if it is a directory. That's unexpected, the return type should be consistent, probably by always returning a str.

I assume that pathlib support is mostly incidental in shutil, considering that the latter predates the former. shutil should probably be reviewed for proper pathlib support at some point. (See also a few other pathlib/shutil related issues reported here.)

CPython versions tested on:

CPython main branch

Operating systems tested on:

No response

Linked PRs

• gh-132322: Ensure shutil functions return str when using pathlib #132820

[kinow]

probably by always returning a str.

Maybe that's the best option, since it look like shutil doesn't use pathlib directly.

[gpshead]

There may be code already depending on the existing behavior. ie: type checkers already presume it can return both per https://github.com/python/typeshed/blob/main/stdlib/shutil.pyi#L54

[srittau]

Changing this to return a consistent return type seems safe if code is already required to handle both types.