Skip to content

refs

Utilities for working with typing.ForwardRef.

This module allows the developer to create and evaluate typing.ForwardRef instances with additional logic to support forwards compatibility.

Typical Usage

>>> from typelib.py import refs
>>> ref = refs.forwardref("str")
>>> cls = refs.evaluate(ref)
>>> cls is str
True

Functions:

evaluate 

evaluate(ref: ForwardRef, *, globalns: Mapping[str, Any] | None = None, localns: Mapping[str, Any] | None = None, recursive_guard: set | None = None) -> Any

Evaluate the typing.ForwardRef instance into a proper type.

Note

Most of the time you will not need to provide anything but ref.

Parameters:

  • ref

    (ForwardRef) –

    The typing.ForwardRef instance to evaluate.

  • globalns

    (Mapping[str, Any] | None, default: None ) –

    A mapping of global variable names to values (optional).

  • localns

    (Mapping[str, Any] | None, default: None ) –

    A mapping of local variable names to values (optional).

  • recursive_guard

    (set | None, default: None ) –

    A set instance to prevent recursion during evaluation (optional). Ignored on Python 3.14+.

Source code in src/typelib/py/refs.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
def evaluate(
    ref: ForwardRef,
    *,
    globalns: typing.Mapping[str, typing.Any] | None = None,
    localns: typing.Mapping[str, typing.Any] | None = None,
    recursive_guard: set | None = None,
) -> typing.Any:
    """Evaluate the [`typing.ForwardRef`][] instance into a proper type.

    Note:
        Most of the time you will not need to provide anything but `ref`.

    Args:
        ref: The [`typing.ForwardRef`][] instance to evaluate.
        globalns: A mapping of global variable names to values (optional).
        localns: A mapping of local variable names to values (optional).
        recursive_guard:
            A set instance to prevent recursion during evaluation (optional).
            Ignored on Python 3.14+.
    """
    if type(ref) is not ForwardRef:
        return ref
    if ref.__forward_evaluated__:
        return ref.__forward_value__

    return ref._evaluate(
        dict(globalns) if globalns is not None else None,
        localns,
        type_params=(),
        recursive_guard=frozenset(recursive_guard or ()),
    )

forwardref 

forwardref(ref: str | type, *, is_argument: bool = False, module: Any | None = None, is_class: bool = True) -> ForwardRef

Create a typing.ForwardRef instance from a ref string.

This wrapper function will attempt to determine the module name ahead of instantiation if not provided. This is important when resolving the reference to an actual type.

Parameters:

  • ref

    (str | type) –

    The type reference string.

  • is_argument

    (bool, default: False ) –

    Whether the reference string was an argument to a function (default False).

  • module

    (Any | None, default: None ) –

    The python module in which the reference string is defined (optional)

  • is_class

    (bool, default: True ) –

    Whether the reference string is a class (default True).

Source code in src/typelib/py/refs.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
def forwardref(
    ref: str | type,
    *,
    is_argument: bool = False,
    module: typing.Any | None = None,
    is_class: bool = True,
) -> ForwardRef:
    """Create a [`typing.ForwardRef`][] instance from a `ref` string.

    This wrapper function will attempt to determine the module name ahead of instantiation
    if not provided. This is important when resolving the reference to an actual type.

    Args:
        ref: The type reference string.
        is_argument: Whether the reference string was an argument to a function (default False).
        module: The python module in which the reference string is defined (optional)
        is_class: Whether the reference string is a class (default True).
    """
    if not isinstance(ref, str):
        name = inspection.qualname(ref)
        module = module or getattr(ref, "__module__", None)
    else:
        name = ref

    module = _resolve_module_name(ref, module)
    if module is not None:
        name = name.replace(f"{module}.", "")

    return ForwardRef(
        name,
        is_argument=is_argument,
        module=module,
        is_class=is_class,
    )