Add backport of evaluate_forward_ref

CHANGELOG.md

@@ -26,6 +26,9 @@ aliases that have a `Concatenate` special form as their argument.
 - Backport CPython PR [#124795](https://github.com/python/cpython/pull/124795):
   fix `TypeAliasType` not raising an error on non-tuple inputs for `type_params`.
   Patch by [Daraan](https://github.com/Daraan).
+- Backport `evaluate_forward_ref` from CPython PR
+  [#119891](https://github.com/python/cpython/pull/119891) to evaluate `ForwardRef`s.
+  Patch by [Daraan](https://github.com/Daraan), backporting a CPython PR by Jelle Zijlstra.
 - Fix that lists and ... could not be used for parameter expressions for `TypeAliasType`
   instances before Python 3.11.
   Patch by [Daraan](https://github.com/Daraan).

doc/index.rst

@@ -753,6 +753,37 @@ Functions
 
    .. versionadded:: 4.2.0
 
+.. function:: evaluate_forward_ref(forward_ref, *, owner=None, globals=None, locals=None, type_params=None, format=Format.VALUE)
+
+   Evaluate an :py:class:`typing.ForwardRef` as a :py:term:`type hint`.
+
+   This is similar to calling :py:meth:`annotationlib.ForwardRef.evaluate`,
+   but unlike that method, :func:`!evaluate_forward_ref` also:
+
+   * Recursively evaluates forward references nested within the type hint.
+     However, the amount of recursion is limited in Python 3.8 and 3.10.
+   * Raises :exc:`TypeError` when it encounters certain objects that are
+     not valid type hints.
+   * Replaces type hints that evaluate to :const:`!None` with
+     :class:`types.NoneType`.
+   * Supports the :attr:`Format.FORWARDREF` and
+     :attr:`Format.STRING` formats.
+
+   *forward_ref* must be an instance of :py:class:`typing.ForwardRef`.
+   *owner*, if given, should be the object that holds the annotations that
+   the forward reference derived from, such as a module, class object, or function.
+   It is used to infer the namespaces to use for looking up names.
+   *globals* and *locals* can also be explicitly given to provide
+   the global and local namespaces.
+   *type_params* is a tuple of :py:ref:`type parameters <type-params>` that
+   are in scope when evaluating the forward reference.
+   This parameter must be provided (though it may be an empty tuple) if *owner*
+   is not given and the forward reference does not already have an owner set.
+   *format* specifies the format of the annotation and is a member of
+   the :class:`Format` enum.
+
+   .. versionadded:: 4.13.0
+
 .. function:: get_annotations(obj, *, globals=None, locals=None, eval_str=False, format=Format.VALUE)
 
    See :py:func:`inspect.get_annotations`. In the standard library since Python 3.10.
@@ -764,7 +795,7 @@ Functions
    of the :pep:`649` behavior on versions of Python that do not support it.
 
    The purpose of this backport is to allow users who would like to use
-   :attr:`Format.FORWARDREF` or :attr:`Format.SOURCE` semantics once
+   :attr:`Format.FORWARDREF` or :attr:`Format.STRING` semantics once
    :pep:`649` is implemented, but who also
    want to support earlier Python versions, to simply write::
 
@@ -911,7 +942,7 @@ Enums
       ``typing_extensions`` emulates this value on versions of Python which do
       not support :pep:`649` by returning the same value as for ``VALUE`` semantics.
 
-   .. attribute:: SOURCE
+   .. attribute:: STRING
 
       Equal to 3. When :pep:`649` is implemented, this format will produce an annotation
       dictionary where the values have been replaced by strings containing