Repository navigation
Cannot import Anchor from importlib.resources #113238
Description
Activity
- added a commit that references this issue
on Dec 17, 2023 - added a commit that references this issue
on Dec 17, 2023 - added a commit that references this issue
on Jan 7, 2024 @jaraco Jason, I have changed the code of
importlib/resources/__init__.pyto match the documentation (Anchorimport).Is my PR correct or is the bug not in the code, but in the documentation and should we replace
AnchorwithPackagein the documentation?- added a commit that references this issue
on Jan 7, 2024 My intention was that Anchor (or Package) would not need to be exported, that it would serve as documentation but not be part of the API (and thus not depended upon by callers).
I'm not particularly experienced with type annotations in APIs, so I'm not sure what the best practice is here.
I'd be interested to know more about the caller's use case. Why is the caller passing an Anchor and not simply one of the specific types? What should happen should this package wish to evolve the meaning of Anchor; should the caller's type evolve with it automatically or should the caller maintain their own type?
Thanks both for looking into this!
My intention was that Anchor (or Package) would not need to be exported, that it would serve as documentation but not be part of the API (and thus not depended upon by callers).
I'm not particularly experienced with type annotations in APIs, so I'm not sure what the best practice is here.
I'd say
Anchoris already part of the API since it's used in the type annotation of public methods (e.g. https://github.com/python/importlib_resources/blob/main/importlib_resources/_common.py#L54 ).I'd be interested to know more about the caller's use case. Why is the caller passing an Anchor and not simply one of the specific types? What should happen should this package wish to evolve the meaning of Anchor; should the caller's type evolve with it automatically or should the caller maintain their own type?
Our use case is to type annotate a couple of wrapper methods around
importlib.resources.files(), see https://github.com/galaxyproject/galaxy/blob/dev/lib/galaxy/util/resources.py .
Given these are wrappers around the standard library, if something changes we will update them to shield the rest of the application from the changes (it's what they are there for).My intention was that Anchor (or Package) would not need to be exported, that it would serve as documentation but not be part of the API (and thus not depended upon by callers).
I'm not particularly experienced with type annotations in APIs, so I'm not sure what the best practice is here.
Since it's documented as a specific type, it should be exposed. If we don't want to expose a new type, we should probably just use
Union[str, ModuleType]directly in the documentation.I agree that the current documentation reads like
Anchoris a specific type exposed by the module.Reacted by Jason R. Coombs- added a commit that references this issue
on Jan 16, 2024 - added a commit that references this issue
on Jan 21, 2024 Can this be closed, or are there more actionable items?
I believe it can be closed. Comment or re-open if I've missed something.
Bug report
Bug description:
The Python 3.12 documentation of the standard library module
importlib.resourcesdescribes the importlib.resources.Anchor class, which is used for the type annotation of thefiles()function.But in reality
Anchoris not available to import fromimportlib.resources, it can only by found inimportlib.resources._commonas an alias forPackage(which is instead available fromimportlib.resources).To reproduce:
Expected result:
No
ImportErrorUse case:
To add type annotation to a function that receives an anchor and passes it to
files().CPython versions tested on:
3.12
Operating systems tested on:
Linux
Linked PRs