importlib.resources.abc.ResourceReader docs/implementation discrepancies

[moreati]

Documentation

Docs for importlib.resources.abc.ResourceReader and the implementation differ in a few details. So far I've noticed

• Parameter name of is_resource() differs
  Docs: is_resource(name).
  Code: is_resource(... path ...)Implementation calls the parameter path
• Behaviour of contents() differs
  Docs: "The abstract method returns an iterable of no items."
  Code: raise FileNotFoundError

If fixes are desired then I'm happy to take it on, and coordinate fixes with e.g. https://github.com/python/importlib_resources, https://github.com/python/typeshed

Linked PRs

• gh-143513: Clarify changed argument name of ResourceReader.is_resource() #143523
• [3.14] gh-143513: Clarify changed argument name of ResourceReader.is_resource (GH-143523) #143562
• [3.13] gh-143513: Clarify changed argument name of ResourceReader.is_resource (GH-143523) #143563
• gh-143513: Clarify historic behaviour of importlib ResourceReader #143574
• gh-143513: Remove importlib.abc documentation for removed ABCs #143605
• [3.14] gh-143513: Remove importlib.abc documentation for removed ABCs (GH-143605) #144166

[johnslavik]

Thank you!

If fixes are desired

In the importlib.resources.abc.ResourceReader.is_resource case, judging by this change in the typeshed, the parameter used to be name until 3.10 but the documentation must have not been updated accordingly (I didn't confirm with our log though :-)).
It may be desired to pass this parameter by keyword, so the name matters in terms of our API contract.
Therefore I'd say yes, fixing this in the docs is desired definitely!

However, in the contents() case: @jaraco, should we change the last sentence from the documentation or should the behavior be updated to reflect the documentation?

[johnslavik]

I don't think we'll change contents() anyway so I'd say go for the two fixes :-)

[moreati]

Timeline for my reference

• 4ac5150 (Py 3.7) adds importlib.abc.ResourceReader, with is_resource(name)
• 6714825 (Py 3.10) resources in namespaces support, change to is_resource(path)
• e712a5b (Py 3.11) moves to importlib.resources.abc.ResourceReader

importlib_resources.abc.ResourceReader has consistently used is_resource(path) since that method was added in python/importlib_resources@e82b567