Description

Viicos

opened on Sep 4, 2026

Issue body actions

Feature or enhancement

Proposal:

annotationlib implements an optimization to resolve forward references in ForwardRef.evaluate(), by doing a simple lookup in the namespace:

cpython/Lib/annotationlib.py

Lines 193 to 210 in 112560e

	if arg.isidentifier() and not keyword.iskeyword(arg):
	if arg in locals:
	return locals[arg]
	elif arg in globals:
	return globals[arg]
	elif hasattr(builtins, arg):
	return getattr(builtins, arg)
	elif is_forwardref_format:
	return self
	else:
	raise NameError(_NAME_ERROR_MSG.format(name=arg), name=arg)
	else:
	code = self.__forward_code__
	try:
	return eval(code, globals=globals, locals=locals)
	except Exception:
	if not is_forwardref_format:
	raise

This gives slightly inconsistent results with lazy imports that fail to resolve:

# lazy_mod.py

Alias = list

raise Exception()

from annotationlib import Format, get_annotations

lazy from lazy_mod import Alias

class A:
    a: Alias

class B:
    a: Alias[int]

get_annotations(A, format=Format.FORWARDREF)
#> {'a': <lazy_import 'failing_mod.Alias'>}
get_annotations(B, format=Format.FORWARDREF)
#> {'a': ForwardRef('Alias[int]', is_class=True, owner=<class '__main__.B'>)}

I'm wondering if for A, it should instead wrap a's annotation in a ForwardRef, so that users can then call evaluate() on it (e.g. with Format.VALUE) so that the exception from lazy_mod gets raised accordingly. Alternatively, the lazy import instance could be kept as is, but it would be great to document the resolve() method on types.LazyImportType.

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

• gh-156924: Try reifying lazy imports in ForwarRef.evaluate() #156940
• [3.15] gh-156924: Try reifying lazy imports in ForwarRef.evaluate() (GH-156940) #157224

Activity

1. Viicos

   added

   type-featureA feature request or enhancementA feature request or enhancement

   on Sep 4, 2026
2. aisk

   added

   topic-typing

   topic-lazy-imports

   on Sep 4, 2026
3. JelleZijlstra

   added

   3.15bugs and security fixesbugs and security fixes

   on Sep 4, 2026
4. JelleZijlstra commented on Sep 4, 2026

   

   JelleZijlstra

   on Sep 4, 2026

   Member

   More actions

   Good catch, I think we should solve this before 3.15 final. My preferred solution would be to wrap LazyImportType instances in a ForwardRef (as you suggest). That way, we'll need some special casing inside annotationlib, but LazyImportType objects won't escape to callers.
5. 94mbi7 commented on Sep 7, 2026

   

   94mbi7

   on Sep 7, 2026

   More actions

   can i work on it if its still open
6. johnslavik commented on Sep 7, 2026

   

   johnslavik

   on Sep 7, 2026

   Member

   More actions

   Alternatively, the lazy import instance could be kept as is, but it would be great to document the resolve() method on types.LazyImportType.

   I'm surprised it wasn't documented.
7. JelleZijlstra

   added a commit that references this issue on Sep 9, 2026

   gh-156924: Try reifying lazy imports in `ForwarRef.evaluate()` (#156940)

   52ffffe
8. hugovk

   added a commit that references this issue on Sep 10, 2026

   [3.15] gh-156924: Try reifying lazy imports in `ForwarRef.evaluate()` (…

   013c4ae
9. hugovk

   closed this as completedon Sep 10, 2026
10. maurycy

    added a commit that references this issue on Sep 10, 2026

    Merge branch 'main' into tachyon-native-callable

    e028ff5
11. clin1234

    added a commit that references this issue on Sep 12, 2026

    pythongh-156924: Try reifying lazy imports in `ForwarRef.evaluate()` (p…

    fc345e3
12. johnslavik

    added a commit that references this issue on Sep 14, 2026

    pythongh-156924: Try reifying lazy imports in `ForwarRef.evaluate()` (p…

    5c64994
13. Kronuz

    added a commit that references this issue on Oct 5, 2026

    [3.15] pythongh-156924: Try reifying lazy imports in `ForwarRef.evalu…

    7263e28

Issue actions