Annotations: Nested generics containing forward references can evade evaluation in ForwardRef.evaluate #160766

Bug report

If an annotation has a subscripted object that is not yet defined which contains a GenericAlias or Annotated alias that is defined that itself contains a reference that is not yet defined, this final reference can evade being evaluated in ForwardRef.evaluate.

It's a bit easier with an example, this shows the issues with Format.STRING and Format.VALUE:

from annotationlib import get_annotations, Format

class X:
    a: Y[list[Z]]

# Get annotations here to get the ForwardRef
anno = get_annotations(X, format=Format.FORWARDREF)['a']

class Y[T]:
    pass

print(anno.evaluate(format=Format.STRING))
print(anno.evaluate(format=Format.VALUE))

Output:

Y[list[ForwardRef('Z', is_class=True, owner=<class '__main__.X'>)]]
__main__.Y[list[ForwardRef('Z', is_class=True, owner=<class '__main__.X'>)]]

Expected:

Y[list[Z]]
...
NameError: name 'Z' is not defined

This is due to the containing alias that can be evaluated being collected as one object in __extra_names__. When .evaluate is then called, this object is retrieved and still contains the second ForwardRef which is never evaluated.

Even if Z is defined, the result of the evaluate call does not change. I stumbled upon this while writing some heavily nested annotations for tests for another issue.

I have a PR prepared with one approach to this.

CPython versions tested on:

CPython main branch, 3.15, 3.14

Operating systems tested on:

No response

Linked PRs

• gh-160766: Handle nested annotated and generic aliases that contain forward references in annotations #160769