Fix unmarshalling of forward references on Python ≥ 3.12.4 (#252)

Fixes the need for specifing recursive_guard as named arg from kwarg
_evaluate from python 3.12.4+

---------

Co-authored-by: Andrew Snare <[email protected]>

Author: sundarshankar89

src/databricks/labs/blueprint/installation.py

@@ -9,6 +9,7 @@
 import logging
 import os.path
 import re
+import sys
 import threading
 import types
 import typing
@@ -668,13 +669,30 @@ class _FromDict(Protocol):
         def from_dict(cls, raw: dict):
             pass
 
+    # Internal utility for evaluating forward references; mypy handles version checks, but only top-level.
+    if sys.version_info >= (3, 12, 4):
+        # Since Python 3.12.4, `ForwardRef._evaluate` requires recursive_guard as a keyword, and has an additional
+        # parameter for type information.
+        @staticmethod
+        def _evaluate_forward_ref(type_ref: typing.ForwardRef) -> type:
+            """Evaluate a forward reference to a type."""
+            # pylint: disable-next=protected-access
+            return type_ref._evaluate(globals(), locals(), (), recursive_guard=frozenset())  # type: ignore[arg-type,misc,return-value]
+    else:
+        # Older versions of Python do
+        @staticmethod
+        def _evaluate_forward_ref(type_ref: typing.ForwardRef) -> type:
+            """Evaluate a forward reference to a type."""
+            # pylint: disable-next=protected-access
+            return type_ref._evaluate(globals(), locals(), recursive_guard=frozenset())  # type: ignore[return-value]
+
     @classmethod
     def _unmarshal(cls, inst: Any, path: list[str], type_ref: type[T]) -> T | None:
         """The `_unmarshal` method is a private method that is used to deserialize a dictionary to an object of type
         `type_ref`. This method is called by the `load` method."""
         # Forward-references aren't always resolved, so we need to handle them. (Assumes reference is visible here.)
         if isinstance(type_ref, typing.ForwardRef):
-            type_ref = type_ref._evaluate(globals(), locals(), frozenset())  # pylint: disable=protected-access
+            type_ref = cls._evaluate_forward_ref(type_ref)
         if dataclasses.is_dataclass(type_ref):
             return cls._unmarshal_dataclass(inst, path, type_ref)
         if isinstance(type_ref, enum.EnumMeta):

tests/unit/test_installation.py

@@ -732,3 +732,26 @@ class SampleClass:
     installation = MockInstallation({"something.json": raw_data})
     loaded = installation.load(SampleClass, filename="something.json")
     assert loaded == expected
+
+
+def test_forward_referencing_class() -> None:
+    """Test that a class with forward-referenced fields. This simulates the behavior of future annotations."""
+
+    @dataclass
+    class ForwardReferencingClass:
+        field_str: "str" = "foo"
+        field_int: "int" = 20
+        field_bool: "bool" = False
+        field_float: "float" = 2.3
+        field_dict: "dict[str, int]" = dataclasses.field(default_factory=dict)
+        field_list: "list[str]" = dataclasses.field(default_factory=list)
+        field_optional: "str | None" = None
+        field_json: "JsonValue" = None
+
+    instance = ForwardReferencingClass(field_dict={"a": 1, "b": 2}, field_list=["x", "y"], field_json={"key": "value"})
+
+    installation = MockInstallation()
+    installation.save(instance, filename="saved.yml")
+
+    loaded = installation.load(ForwardReferencingClass, filename="saved.yml")
+    assert instance == loaded