Cannot import ``Anchor`` from ``importlib.resources``

[nsoranzo]

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

Linked PRs

• [3.12] gh-113238: add Anchor to importlib.resources #113799
• gh-113238: add Anchor to importlib.resources #113801
• [3.12] gh-113238: add Anchor to importlib.resources (GH-113801) #130499

[mikeziminio]

@jaraco Jason, I have changed the code of importlib/resources/__init__.py to match the documentation (Anchor import).

Is my PR correct or is the bug not in the code, but in the documentation and should we replace Anchor with Package in the documentation?

[jaraco]

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]

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 Anchor is 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).

[FFY00]

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 Anchor is a specific type exposed by the module.