Add typing overloads to CloudPath.open()

[0xbe7a]

Currently, the return type of CloudPath.open() is always IO[Any]. This differs from pathlib.Path.open(), which returns more specific types like TextIOWrapper, FileIO, BufferedRandom, BufferedWriter, BufferedReader, BinaryIO, or IO[Any] depending on arguments such as mode, buffering, and encoding. The more specific return types are useful for catching typing issues where a library expects a file handle in binary or text mode, specified as IO[bytes] or IO[str], respectively. With the current behavior, passing a file handle returned by CloudPath.open() often requires using typing.cast() or # type: ignore.

Here’s an example illustrating the current behavior compared to pathlib.Path.open():

from pathlib import Path
from cloudpathlib import CloudPath

cloud_path = CloudPath("s3://bucket/key")  # type: ignore
local_path = Path("test.txt")

with local_path.open("w") as f:
    reveal_type(f)  # Revealed type: io.TextIOWrapper

with local_path.open("wb") as f:
    reveal_type(f)  # Revealed type: io.BufferedWriter

with cloud_path.open("w") as f:
    reveal_type(f)  # Revealed type: typing.IO[Any]

with cloud_path.open("wb") as f:
    reveal_type(f)  # Revealed type: typing.IO[Any]

[pjbull]

Thanks @0xbe7a, this is released now in v0.19.0 if you want to upgrade and test your use case