This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Document
Type: Stage:
Components: Documentation Versions:
Status: open Resolution:
Dependencies: Superseder:
Assigned To: jaraco Nosy List: docs@python, jaraco, petr.viktorin
Priority: normal Keywords:

Created on 2022-03-28 12:48 by petr.viktorin, last changed 2022-04-11 14:59 by admin.

Messages (4)
msg416164 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2022-03-28 12:48
importlib.resources.files is documented [0] as returning, 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.

msg416617 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2022-04-03 12:55
> 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]( does indicate that each of the parameters will be combined with the existing path and acknowledges that absolute paths are possible. The [curated docs]( 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]( but looking at the [docs for zipfile](, it's not even obvious to me what path separators are used in zipfiles, but I do observe there is [coercion to posixpath.sep](

``ResourceContainer``, on the other hand, [will not accept path separators]( 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.
msg416618 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2022-04-03 13:04
> 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.
msg416619 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2022-04-03 13:06
Correction. In msg416618, link should have been:

[docs for zipfile](
Date User Action Args
2022-04-11 14:59:57adminsetgithub: 91298
2022-04-03 13:06:57jaracosetmessages: + msg416619
2022-04-03 13:04:38jaracosetmessages: + msg416618
2022-04-03 12:55:22jaracosetmessages: + msg416617
2022-03-28 12:59:22jaracosetassignee: docs@python -> jaraco
2022-03-28 12:48:15petr.viktorincreate