convert shutil._PathReturn to a type parameter?

[dpinol]

Since shutil._PathReturn is defined as Any, it may hide type errors to mypy-like tools. E.g in the following code, mypy will not detect that f function is invoked with an str argument instead of a Path.

import shutil
from pathlib import Path


def f(p: Path) -> None:
    pass


def cp(target: str | Path) -> None:
    p = shutil.copy("/src", target)
    return f(p)

[srittau]

Unfortunately, changing this to a union in the general case would mean that users would need to add isinstance checks to the returned value in many cases. That said, looking at the implementation of copy(), I think we could do better for some cases: For example, passing str or bytes as dst will always return the same type. We could reflect that and keep the Any return type only when passing in a PathLike.

The best solution would be to fix the functions in the standard library to return consistent types, but that's out of scope for typeshed.

[dpinol]

I understand, thanks

[Avasam]

Given that the return type would be StrPath (ie: str | PathLike[str]) and that we can return a str if dst: str and str | _T otherwise, I'd argue that's a fine union to return.

Most cases of using a StrPath whether you actually have a str or a PathLike won't matter too much. If you do explicitly need a str after potentially passing a PathLike or explicitely need the same PathLike you passed, then you should really check the return here.

And once again, in most cases, you can coerce the type (using str() or Path())

>>> Path("")
WindowsPath('.')
>>> Path(Path())
WindowsPath('.')
>>> str(".")
'.'
>>> str(Path("."))
'.'

(this argument may not hold as well for bytespath though, what's a common PathLike[bytes] ?)