[issue47142] Document importlib.resources.abc.Traversable
New submission from Petr Viktorin <encukou@gmail.com>: 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.resou... [source]: https://github.com/python/cpython/blob/main/Lib/importlib/resources/abc.py#L... ---------- assignee: docs@python components: Documentation messages: 416164 nosy: docs@python, jaraco, petr.viktorin priority: normal severity: normal status: open title: Document importlib.resources.abc.Traversable _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue47142> _______________________________________
Change by Jason R. Coombs <jaraco@jaraco.com>: ---------- assignee: docs@python -> jaraco _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue47142> _______________________________________
Jason R. Coombs <jaraco@jaraco.com> added the comment:
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/3faa9f78d4b9a8c0fd4657b434bdb08ae1f28...) 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/3faa9f78d4b9a8c0fd4657b434bdb08ae1f28...) 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/3faa9f78d4b9a8c0fd4657b434bdb08ae1f28...). 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue47142> _______________________________________
Jason R. Coombs <jaraco@jaraco.com> added the comment:
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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue47142> _______________________________________
Jason R. Coombs <jaraco@jaraco.com> added the comment: Correction. In msg416618, link should have been: [docs for zipfile](https://docs.python.org/3/library/zipfile.html#zipinfo-objects) ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue47142> _______________________________________
participants (2)
-
Jason R. Coombs -
Petr Viktorin