Provide a protocol for `__vfspath__`

[ap--]

Hi @barneygale,

I moved universal-pathlib to depend on pathlib_abc now, and I am now planning how to best roll out support for virtual path like objects to other libraries.

In a many of the packages a usual pattern is to accept str | os.PathLike and then use open() or convert to pathlib.Path, and in non-local cases have some other mechanism to ultimately provide a readable / writable buffer. By now, most of these packages are type annotated too.

To support these patterns, I think pathlib_abc should ship a __vfspath__ protocol to allow the libraries to correctly type annotate their input parameters. In many cases I think that vfsopen can either serve as a drop-in replacement or would just be used inside a thin wrapper.

from typing import Protocol
from typing import IO
from pathlib_abc import vfsopen

class VFSPathLike(Protocol):
    def __vfspath__(self) -> str: ...

def get_buffer(p: str | os.PathLike[str] | VFSPathLike, /, *, mode: str) -> IO[...]:
    return vfsopen(p, mode)

I'm shipping this in universal-pathlib https://github.com/fsspec/universal_pathlib/blob/b6c3e588e42d62d2c35e170bdc461feedc1c4232/upath/types/__init__.py#L41-L45 but as with all things, the hardest part is naming it correctly. Not sure if it should be VPathLike or SupportsVFSPath or something else...

Update: Writing this, I realize that what this actually needs, would be the correct openable protocol, but since that is still in flux, it seems everyone who implements __vfspath__ very likely is working on Joinable, Reabable, Writable path subclassess. So they seem at least for now tightly bound.

[phil65]

Please also add @runtime_checkable to align it with os.PathLike :)