gh-138764: annotationlib - Make call_annotate_function fallback to using VALUE annotations if both the requested format and VALUE_WITH_FAKE_GLOBALS are not implemented

[DavidCEllis]

Alternative to #138788 - instead of raising the NotImplementedError this falls back to calling an annotate function with Format.VALUE if both the specified format and Format.VALUE_WITH_FAKE_GLOBALS are both not implemented.

I think this may be more useful behaviour than #138788 ?

If VALUE also fails, then the only option was failure from the start. I think it's more consistent to raise the error from VALUE annotations in that case.

Using the examples from the other PR:

from annotationlib import Format, call_annotate_function

def annotate(format, /):
    if format == Format.VALUE:
        return {'x': str}
    else:
        raise NotImplementedError(format)

print(call_annotate_function(annotate, Format.STRING))

On main, and with this patch:

{'x': 'str'}

from annotationlib import Format, call_annotate_function

def annotate(format, /):
    if format in {Format.VALUE}:
        return {'x': str}
    else:
        raise NotImplementedError(format)

print(call_annotate_function(annotate, Format.STRING))

Main:

TypeError: exceptions must derive from BaseException

Patch:

{'x': 'str'}

• Issue: annotationlib - call_annotate_function should check VALUE_WITH_FAKE_GLOBALS is implemented before calling in a namespace with empty fake globals #138764

[DavidCEllis]

I also prefer this over #138788 because I think FORWARDREF and STRING annotations should always work if VALUE annotations work.

[JelleZijlstra]

I like this too. We might need to extend the listing under https://docs.python.org/3.14/library/annotationlib.html#annotationlib.get_annotations explaining how the different formats work (and in any case, this needs a NEWS entry).

[DavidCEllis]

I had a go at extending the descriptions of the formats. This made me realise I was describing behaviour that there wasn't a test for as a fall back so added some extra tests.

[JelleZijlstra]

Looks good, left some small tweaks.

[miss-islington-app]

Thanks @DavidCEllis for the PR, and @JelleZijlstra for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[bedevere-app]

GH-140426 is a backport of this pull request to the 3.14 branch.