importlib.resources.files is documented [0] as returning importlib.resources.abc.Traversable, which is an undocumented class (dead link) now. It should be documented.
The [source] has helpful docstrings, but is missing some details. I'd like to know these before writing some docs:

- Can the argument to `joinpath` contain path separators?
- Are the methods expected to raise specific exception types (e.g. if a resource is missing, or you call iterdir on a “file”)? This seems quite important for people who implement the protocol.


[0]: https://docs.python.org/dev/library/importlib.resources.html#importlib.resources.files
[source]: https://github.com/python/cpython/blob/main/Lib/importlib/resources/abc.py#L49

> Can the argument to `joinpath` contain path separators?

Good question. Currently, I'm aware of three concrete implementations of Traversable.joinpath:

- pathlib.Path.joinpath
- zipfile.Path.joinpath
- importlib.resources.simple.ResourceContainer.joinpath

``Traversable.joinpath`` was modeled after ``pathlib.Path.joinpath``, which itself is itself not rigorous in what path separators are allowed. The [docstring](https://github.com/python/cpython/blob/3faa9f78d4b9a8c0fd4657b434bdb08ae1f28800/Lib/pathlib.py#L754-L758) does indicate that each of the parameters will be combined with the existing path and acknowledges that absolute paths are possible. The [curated docs](https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.joinpath) only give examples, and curiously, those examples only use posixpath.sep, suggesting that it's recommended when passing compound paths to use posixpath separators as they're more widely supported.

For zipfile.Path, I observe that [joinpath does accept path separators](https://github.com/python/cpython/blob/3faa9f78d4b9a8c0fd4657b434bdb08ae1f28800/Lib/zipfile.py#L2438-L2440) but looking at the [docs for zipfile](https://gist.github.com/jaraco/5b266870c62680d6d6b3a876be321fa4), it's not even obvious to me what path separators are used in zipfiles, but I do observe there is [coercion to posixpath.sep](https://gist.github.com/jaraco/5b266870c62680d6d6b3a876be321fa4).

``ResourceContainer``, on the other hand, [will not accept path separators](https://github.com/python/cpython/blob/3faa9f78d4b9a8c0fd4657b434bdb08ae1f28800/Lib/importlib/resources/simple.py#L102-L105). This class, however, may not be used anywhere and probably could be extended to support path separators as well.

Here's what I propose:

- First, document that the interface is under-specified and that for maximum compatibility, a consumer should pass only relative paths using posixpath.sep or no separator at all. Additionally, explicitly declare that behavior with absolute paths is undefined and unsupported.
- Second, expand the interface on ``Traversable.joinpath`` to stipulate that the interface should accept multiple relative paths.
- Third, ``simple.ResourceContainer`` should be updated to meet that spec.

> Are the methods expected to raise specific exception types (e.g. if a resource is missing, or you call iterdir on a “file”)?

The short answer is no. The protocol does not stipulate specific exceptions. Perhaps it should be documented that any exceptions that occur when accessing the backing resource will propagate. Although, I do believe that statement is true for all Python code unless stated otherwise.

I agree it would be nice if the protocol could stipulate which exceptions might be raised by a given implementation, but I'm not confident that's possible, at least not without wrapping/adapting the pathlib.Path and zipfile.Path objects.

Does that answer the question? Are you working on another provider that implements this protocol? I'd be happy to consult on that effort.

Correction. In msg416618, link should have been:

[docs for zipfile](https://docs.python.org/3/library/zipfile.html#zipinfo-objects)