Skip to content

importlib.resources.abc.ResourceReader docs/implementation discrepancies #143513

Closed
Closed
importlib.resources.abc.ResourceReader docs/implementation discrepancies#143513
Labels
docsDocumentation in the Doc dirtopic-importlib

Description

@moreati
moreati
opened on Jan 7, 2026

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

Activity

  1. moreati
    added
    docsDocumentation in the Doc dir
    on Jan 7, 2026
  2. github-project-automation
    added this to docs issueson Jan 7, 2026
  3. github-project-automation
    moved this to Todo in docs issueson Jan 7, 2026
  4. johnslavik
    added
    topic-importlib
    on Jan 7, 2026

  5. johnslavik commented on Jan 7, 2026

    @johnslavik
    johnslavik
    on Jan 7, 2026
    Member

    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?

  6. johnslavik commented on Jan 7, 2026

    @johnslavik
    johnslavik
    on Jan 7, 2026
    Member

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

  7. moreati commented on Jan 7, 2026

    @moreati
    moreati
    on Jan 7, 2026
    ContributorAuthor

    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

  8. moreati
    added a commit that references this issue on Jan 7, 2026

    pythongh-143513: Clarify changed argument name of ResourceReader.is_r…

    a05179a
  9. ZeroIntensity
    added a commit that references this issue on Jan 8, 2026

    gh-143513: Clarify changed argument name of `ResourceReader.is_resour…

    5462002
  10. miss-islington
    added 2 commits that reference this issue on Jan 8, 2026

    pythongh-143513: Clarify changed argument name of `ResourceReader.is_…

    5d7c09d

    pythongh-143513: Clarify changed argument name of `ResourceReader.is_…

    69f0d53
  11. ZeroIntensity
    added 2 commits that reference this issue on Jan 8, 2026

    [3.14] gh-143513: Clarify changed argument name of `ResourceReader.is…

    6c6eb7a

    [3.13] gh-143513: Clarify changed argument name of `ResourceReader.is…

    bcc0552

  12. moreati commented on Jan 8, 2026

    @moreati
    moreati
    on Jan 8, 2026
    ContributorAuthor

    contents() timeline (near identical to is_resource() timeline above)

    • 4ac5150 (Py 3.7) adds importlib.abc.ResourceReader, with contents() returning an empty interator
    • 6714825 (Py 3.10) resources in namespaces support, change to raise FileNotFoundError
    • e712a5b (Py 3.11) moves to importlib.resources.abc.ResourceReader

    importlib_resources.abc.ResourceReader.contents() has consistently raised FileNotFoundError since it was added in python/importlib_resources@e82b567. Typeshed doesn't care, exceptions aren't part of a type signature.

  13. moreati commented on Jan 8, 2026

    @moreati
    moreati
    on Jan 8, 2026
    ContributorAuthor
  14. moreati
    added 3 commits that reference this issue on Jan 8, 2026

    pythonGH-143513 Clarify historic behaviour of importlib ResourceReader

    591d63a

    pythonGH-143513: Remove importlib.abc documentation for removed ABCs

    110ee02

    pythonGH-143513: Remove importlib.abc documentation for removed ABCs

    ef016f5
  15. reidenong
    added a commit that references this issue on Jan 12, 2026

    pythongh-143513: Clarify changed argument name of `ResourceReader.is_…

    63beef6
  16. brettcannon
    added a commit that references this issue on Jan 22, 2026

    gh-143513: Remove importlib.abc documentation for removed ABCs (#143605)

    f8262b8
  17. miss-islington
    added a commit that references this issue on Jan 22, 2026

    pythongh-143513: Remove importlib.abc documentation for removed ABCs (p…

    47a86b9
  18. brettcannon
    added a commit that references this issue on Jan 22, 2026

    [3.14] gh-143513: Remove importlib.abc documentation for removed ABCs (…

    1fa1668
  19. brettcannon
    closed this as completedon Jan 22, 2026
  20. moreati
    added a commit that references this issue on Jan 23, 2026

    pythonGH-143513 Clarify historic behaviour of importlib ResourceReader

    9a8171c
  21. thunder-coding
    added 2 commits that reference this issue on Feb 15, 2026

    pythongh-143513: Clarify changed argument name of `ResourceReader.is_…

    5a287e9

    pythongh-143513: Remove importlib.abc documentation for removed ABCs (p…

    30a9f0f
  22. moreati
    added a commit that references this issue on May 4, 2026

    pythonGH-143513 Clarify historic behaviour of importlib ResourceReader

    1332404
  23. moreati
    added a commit that references this issue on Aug 19, 2026

    pythonGH-143513 Clarify historic behaviour of importlib ResourceReader

    43a739c
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc dirtopic-importlib

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions