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

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?

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.

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.

New changeset d309bcc by Miss Islington (bot) in branch '3.10':
bpo-44195: Use 'TraversableResources' in the docs to match the implementation. (GH-26317)
d309bcc

New changeset ab4da07 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)
ab4da07