Better docs for importlib.resources

[encukou]

The current documentation of importlib.resources can be improved.
The main hindrance to usability are references to classes that are not linked correctly, leaving the docs very hard to follow for someone who doesn't already know the module. For example, Traversable in the docs of files is not a link.

[encukou]

PR: #93611

[warsaw]

Just ran across this one too! importlib.resources.rst links to importlib.resources.abc.Traversable but it should be importlib.abc.Traversable. PR coming for that.

@encukou were there other problems you found?

[warsaw]

I've opened two PRs which seem to fix the documentation problem, but I'm not actually sure this is the right thing to do. The deal is that in 3.11, Traversable, ResourceReader, and TraversableResources were moved to importlib.resources.abc, with this compatibility hack added to importlib.abc:

# for compatibility with Python 3.10
from .resources.abc import ResourceReader, Traversable, TraversableResources

However, the documentation for importlib.resources.abc is included in importlib.rst (inside the :mod:importlib.abc section):

.. include:: importlib.resources.abc.rst

which is why (I think), the doc cross references to importlib.resources.abc.Traversable don't work (without the above PRs). I don't see any mention of this reorg in the What's New in Python 3.11 docs, nor in the importlib.abc documentation, so I'm not sure what the intended public API for these ABC's is.

@jaraco can you weigh in?

[encukou]

Yes, that confused me as well, so I went with the implementation here – <class 'importlib.resources.abc.Traversable'>.

[encukou]

were there other problems you found?

I sent a PR with improvements, it's probably better to look there, but:

• for migrating away from the deprecated functions, there's a link to importlib_resources docs, which says to look in the source of importlib_resources._legacy – which uses a private module for all of the implementation. (Perhaps with Traversable documentation being discoverable, this would be easier to use?)
• the deprecated functions take up most of the page, and could be moved to a new “you don't need to read this” section
• many references to types/functions could be links to the relevant docs, so they're more usable for people who don't already know them
• it's pure reference; there's no hint about why you would use this and not just __file__