[issue47142] Document importlib.resources.abc.Traversable

[Jason R. Coombs]

Jason R. Coombs  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue47142] Document importlib.resources.abc.Traversable

[Jason R. Coombs]

Jason R. Coombs  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue47142] Document importlib.resources.abc.Traversable

[Jason R. Coombs]

Jason R. Coombs  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/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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue47142] Document importlib.resources.abc.Traversable

[Jason R. Coombs]

Change by Jason R. Coombs :


--
assignee: docs@python -> jaraco

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue47142] Document importlib.resources.abc.Traversable

[Petr Viktorin]

New submission from Petr Viktorin :

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

--
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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com