Python 3.14+annotationlibпонятие

annotationlib.ForwardRef

форматы аннотаций

Заглушка для имени в аннотации, которое пока нельзя вычислить. Хранит текст ссылки и умеет вычислить её позже методом evaluate().

Синтаксис

ref.evaluate(*, owner=None, globals=None, locals=None, type_params=None, format=Format.VALUE)

ForwardRef из get_annotations(format=FORWARDREF) помнит владельца, поэтому после объявления класса хватает ref.evaluate() без аргументов. А созданный руками ForwardRef('Point') владельца не знает: evaluate() ищет имя в пустых globals (видны только встроенные) и падает NameError, даже если Point объявлен рядом, — нужно передать owner= или globals=. evaluate(format=Format.STRING) просто отдаёт __forward_arg__. Это тот же класс, что typing.ForwardRef: в 3.14 typing его реэкспортирует.

Примеры

# Python 3.14+
from annotationlib import get_annotations, Format
def area(s: Square) -> float: ...
ref = get_annotations(area, format=Format.FORWARDREF)['s']
print(ref.__forward_arg__)  # → Square
class Square: ...
print(ref.evaluate())  # → <class '__main__.Square'> — владелец запомнен

# Python 3.14+
from annotationlib import ForwardRef
class Point: ...
try:
    ForwardRef('Point').evaluate()  # владельца нет — globals пусты
except NameError as e:
    print(e)  # → name 'Point' is not defined
print(ForwardRef('Point').evaluate(globals={'Point': Point}))  # → <class '__main__.Point'>
print(ForwardRef('list[int]').evaluate())  # → list[int] — встроенные видны

См. также

Частые ошибки

Открыть в полном глоссарииdocs.python.orgСообщить о неточности