classification
Title: importlib.abc.TraversableReader is not implemented
Type: behavior Stage: resolved
Components: Versions: Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: FFY00, brett.cannon, jaraco, miss-islington
Priority: normal Keywords: patch

Created on 2021-05-20 19:19 by FFY00, last changed 2021-07-30 02:14 by jaraco. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 26271 closed FFY00, 2021-05-20 19:30
PR 26272 open FFY00, 2021-05-20 20:06
PR 26317 merged jaraco, 2021-05-23 13:12
PR 26334 merged miss-islington, 2021-05-24 17:08
PR 26335 merged miss-islington, 2021-05-24 17:08
Messages (6)
msg394052 - (view) Author: Filipe Laíns (FFY00) * (Python triager) Date: 2021-05-20 19:19
7f7e706d78ab968a1221c6179dfdba714860bd12 introduced the files() api and documented a importlib.abc.TraversableReader protocol, but it did not implement it.

This class is documented and marked as introduced in 3.9, but it's actually missing.
msg394197 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2021-05-23 13:14
I don't believe a `TraversableReader` protocol was intended. Instead, the referenced change introduced the `TraversableResources` ABC. There's a typo in the docs. I created PR 26317 instead to correct the mistake. WDYT?
msg394204 - (view) Author: Filipe Laíns (FFY00) * (Python triager) Date: 2021-05-23 15:48
We do implement the protocol, and not TraversableResources, in some places, such as DegenerateFiles for eg. It seems to me that maybe that is an issue and we actually want to inherit from TraversableResources.

The question here is, are people supposed to be implementing readers with just files(), or are they always expected to inherit TraversableResources?

Regardless of the usefulness in code, please also consider type hinting. If people are expecting to be using this protocol, we should expose it.
msg394257 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2021-05-24 17:07
> are people supposed to be implementing readers with just files(), or are they always expected to inherit TraversableResources?

A resource provider could potentially implement only the `files()` method (what I think you're calling `TraversableReader`), but my expectation was that all providers would provide a Reader derived from `TraversableResources` in order to provide backward-compatibility for the `ResourceReader` interface. Long term, I'd expect to deprecate all but `files()` on `TraversableResources`.

If a provider only implemented `files()` today and did not inherit from `TraversableResources`, they would still satisfy the `files()` API, but not the ResourceReader API (i.e. violate the expectation that `Loader.get_resource_reader` returns a ResourceReader).

I decided not to present both `TraversableReader` and `TraversableResources` as separate classes because the latter was sufficient for all known cases.

> It seems to me that maybe that is an issue and we actually want [DegenerateFiles] to inherit from TraversableResources.

Perhaps. What advantage would that have?

> Regardless of the usefulness in code, please also consider type hinting.

Agreed, there are some places where type hints would drastically improve readability.

> If people are expecting to be using this protocol, we should expose it.

My instinct is `TraversableResources` is the preferred protocol for now, although I think it's likely we'll want to separate out the TraversableReader when necessary. Let's plan to do that in importlib_resources first.
msg394258 - (view) Author: miss-islington (miss-islington) Date: 2021-05-24 17:30
New changeset d309bcc9e36adb2437a02550514df3efeb1b2343 by Miss Islington (bot) in branch '3.10':
bpo-44195: Use 'TraversableResources' in the docs to match the implementation. (GH-26317)
https://github.com/python/cpython/commit/d309bcc9e36adb2437a02550514df3efeb1b2343
msg394259 - (view) Author: miss-islington (miss-islington) Date: 2021-05-24 17:33
New changeset ab4da079232356e781743b2782148bc7c03f1ee3 by Miss Islington (bot) in branch '3.9':
[3.9] bpo-44195: Use 'TraversableResources' in the docs to match the implementation. (GH-26317) (GH-26335)
https://github.com/python/cpython/commit/ab4da079232356e781743b2782148bc7c03f1ee3
History
Date User Action Args
2021-07-30 02:14:55jaracosetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2021-05-24 17:33:11miss-islingtonsetmessages: + msg394259
2021-05-24 17:30:12miss-islingtonsetmessages: + msg394258
2021-05-24 17:08:24miss-islingtonsetpull_requests: + pull_request24927
2021-05-24 17:08:19miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request24926
2021-05-24 17:07:30jaracosetmessages: + msg394257
2021-05-23 15:48:36FFY00setmessages: + msg394204
2021-05-23 13:14:01jaracosetmessages: + msg394197
2021-05-23 13:12:11jaracosetpull_requests: + pull_request24912
2021-05-20 20:06:11FFY00setpull_requests: + pull_request24877
2021-05-20 19:30:01FFY00setkeywords: + patch
stage: patch review
pull_requests: + pull_request24876
2021-05-20 19:19:52FFY00create