runfiles: add pathlib.Path or importlib.Traversable API #3296
Description
The current runfiles library accepts runfile strings and returns file system strings.
This works fine for looking up specific resources, but can break when trying to list resources in a directory. The particular case is when a runfiles manifest is used without runfiles being materialized. In such a case, two problems occur: (1) there is no actual directory, and (2) files logically part of a runfiles directory may be in different underlying file system directories.
To fix this, we should have an API that returns an object that represents a path instead of the underlying filesystem path. The two candidates in the stdlib are pathlib.Path and importlib.Traversable. Traversable has a subset of Path methods.
IMHO, I think Path is slightly better -- Traversable is specific to the import system, while runfiles aren't.
Related slack discussion: https://bazelbuild.slack.com/archives/CDCMRLS23/p1758750938143029