Repository navigation
Cannot import Anchor from importlib.resources #113238
Description
Bug report
Bug description:
The Python 3.12 documentation of the standard library module importlib.resources describes the importlib.resources.Anchor class, which is used for the type annotation of the files() function.
But in reality Anchor is not available to import from importlib.resources, it can only by found in importlib.resources._common as an alias for Package (which is instead available from importlib.resources).
To reproduce:
>>> from importlib.resources import Anchor
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ImportError: cannot import name 'Anchor' from 'importlib.resources' (/usr/lib/python3.12/importlib/resources/__init__.py)Expected result:
No ImportError
Use 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
Activity
Workaround ``ImportError`` for ``importlib.resources.Anchor``
Workaround ``ImportError`` for ``importlib.resources.Anchor``
pythongh-113238: add Anchor to importlib.resources
mikeziminio commentedon 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?pythongh-113238: add Anchor to importlib.resources
jaraco commentedon 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?
nsoranzo commentedon Jan 8, 2024
Thanks both for looking into this!
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 ).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).
FFY00 commentedon Jan 16, 2024
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.gh-113238: add Anchor to importlib.resources (#113801)
Workaround ``ImportError`` for ``importlib.resources.Anchor``
pythongh-113238: add Anchor to importlib.resources (python#113801)
pythongh-113238: add Anchor to importlib.resources (python#113801)
erlend-aasland commentedon Mar 12, 2024
Can this be closed, or are there more actionable items?
jaraco commentedon Mar 13, 2024
I believe it can be closed. Comment or re-open if I've missed something.
pythongh-113238: add Anchor to importlib.resources (python#113801)
[3.12] pythongh-113238: add Anchor to importlib.resources (pythonGH-1…
[3.12] gh-113238: add Anchor to importlib.resources (GH-113801) (#130499