pyglove 0.5.0.dev202510230131__py3-none-any.whl → 0.5.0.dev202511300809__py3-none-any.whl

pyglove/core/symbolic/__init__.py

@@ -147,4 +147,11 @@ from pyglove.core.symbolic.list import mark_as_insertion
 from pyglove.core.symbolic.base import WritePermissionError
 from pyglove.core.symbolic.error_info import ErrorInfo
 
+# Unknown symbols.
+from pyglove.core.symbolic.unknown_symbols import UnknownSymbol
+from pyglove.core.symbolic.unknown_symbols import UnknownType
+from pyglove.core.symbolic.unknown_symbols import UnknownFunction
+from pyglove.core.symbolic.unknown_symbols import UnknownMethod
+from pyglove.core.symbolic.unknown_symbols import UnknownTypedObject
+
 # pylint: enable=g-bad-import-order

pyglove/core/symbolic/base.py

@@ -2042,7 +2042,7 @@ def from_json(
     context: Optional[utils.JSONConversionContext] = None,
     auto_symbolic: bool = True,
     auto_import: bool = True,
-    auto_dict: bool = False,
+    convert_unknown: bool = False,
     allow_partial: bool = False,
     root_path: Optional[utils.KeyPath] = None,
     value_spec: Optional[pg_typing.ValueSpec] = None,
@@ -2073,8 +2073,13 @@ def from_json(
       identify its parent module and automatically import it. For example,
       if the type is 'foo.bar.A', PyGlove will try to import 'foo.bar' and
       find the class 'A' within the imported module.
-    auto_dict: If True, dict with '_type' that cannot be loaded will remain
-      as dict, with '_type' renamed to 'type_name'.
+    convert_unknown: If True, when a '_type' is not registered and cannot
+      be imported, PyGlove will create objects of:
+        - `pg.symbolic.UnknownType` for unknown types;
+        - `pg.symbolic.UnknownTypedObject` for objects of unknown types;
+        - `pg.symbolic.UnknownFunction` for unknown functions;
+        - `pg.symbolic.UnknownMethod` for unknown methods.
+      If False, TypeError will be raised.
     allow_partial: Whether to allow elements of the list to be partial.
     root_path: KeyPath of loaded object in its object tree.
     value_spec: The value spec for the symbolic list or dict.
@@ -2095,7 +2100,12 @@ def from_json(
   if context is None:
     if (isinstance(json_value, dict) and (
         context_node := json_value.get(utils.JSONConvertible.CONTEXT_KEY))):
-      context = utils.JSONConversionContext.from_json(context_node, **kwargs)
+      context = utils.JSONConversionContext.from_json(
+          context_node,
+          auto_import=auto_import,
+          convert_unknown=convert_unknown,
+          **kwargs
+      )
       json_value = json_value[utils.JSONConvertible.ROOT_VALUE_KEY]
     else:
       context = utils.JSONConversionContext()
@@ -2103,7 +2113,7 @@ def from_json(
   typename_resolved = kwargs.pop('_typename_resolved', False)
   if not typename_resolved:
     json_value = utils.json_conversion.resolve_typenames(
-        json_value, auto_import, auto_dict
+        json_value, auto_import, convert_unknown
     )
 
   def _load_child(k, v):
@@ -2177,7 +2187,7 @@ def from_json_str(
     *,
     context: Optional[utils.JSONConversionContext] = None,
     auto_import: bool = True,
-    auto_dict: bool = False,
+    convert_unknown: bool = False,
     allow_partial: bool = False,
     root_path: Optional[utils.KeyPath] = None,
     value_spec: Optional[pg_typing.ValueSpec] = None,
@@ -2205,8 +2215,13 @@ def from_json_str(
       identify its parent module and automatically import it. For example,
       if the type is 'foo.bar.A', PyGlove will try to import 'foo.bar' and
       find the class 'A' within the imported module.
-    auto_dict: If True, dict with '_type' that cannot be loaded will remain
-      as dict, with '_type' renamed to 'type_name'.
+    convert_unknown: If True, when a '_type' is not registered and cannot
+      be imported, PyGlove will create objects of:
+        - `pg.symbolic.UnknownType` for unknown types;
+        - `pg.symbolic.UnknownTypedObject` for objects of unknown types;
+        - `pg.symbolic.UnknownFunction` for unknown functions;
+        - `pg.symbolic.UnknownMethod` for unknown methods.
+      If False, TypeError will be raised.
     allow_partial: If True, allow a partial symbolic object to be created.
       Otherwise error will be raised on partial value.
     root_path: The symbolic path used for the deserialized root object.
@@ -2236,7 +2251,7 @@ def from_json_str(
       _decode_int_keys(json.loads(json_str)),
       context=context,
       auto_import=auto_import,
-      auto_dict=auto_dict,
+      convert_unknown=convert_unknown,
       allow_partial=allow_partial,
       root_path=root_path,
       value_spec=value_spec,

pyglove/core/symbolic/list_test.py

@@ -506,8 +506,7 @@ class ListTest(unittest.TestCase):
   def test_index(self):
     sl = List([0, 1, 2, 1])
     self.assertEqual(sl.index(1), 1)
-    with self.assertRaisesRegex(
-        ValueError, '3 is not in list'):
+    with self.assertRaisesRegex(ValueError, '.* not in list'):
       _ = sl.index(3)
 
     # Index of inferred value is based on its symbolic form.

pyglove/core/symbolic/object.py

@@ -339,7 +339,8 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
 
     # Set `__serialization_key__` before JSONConvertible.__init_subclass__
     # is called.
-    setattr(cls, '__serialization_key__', cls.__type_name__)
+    if '__serialization_key__' not in cls.__dict__:
+      setattr(cls, '__serialization_key__', cls.__type_name__)
 
     super().__init_subclass__()
 

pyglove/core/symbolic/object_test.py

@@ -38,6 +38,7 @@ from pyglove.core.symbolic.object import use_init_args as pg_use_init_args
 from pyglove.core.symbolic.origin import Origin
 from pyglove.core.symbolic.pure_symbolic import NonDeterministic
 from pyglove.core.symbolic.pure_symbolic import PureSymbolic
+from pyglove.core.symbolic.unknown_symbols import UnknownTypedObject
 from pyglove.core.views.html import tree_view  # pylint: disable=unused-import
 
 
@@ -3158,7 +3159,7 @@ class SerializationTest(unittest.TestCase):
             Q.partial(P.partial()).to_json_str(), allow_partial=True),
         Q.partial(P.partial()))
 
-  def test_serialization_with_auto_dict(self):
+  def test_serialization_with_convert_unknown(self):
 
     class P(Object):
       auto_register = False
@@ -3181,15 +3182,17 @@ class SerializationTest(unittest.TestCase):
         }
     )
     self.assertEqual(
-        base.from_json_str(Q(P(1), y='foo').to_json_str(), auto_dict=True),
-        {
-            'p': {
-                'type_name': P.__type_name__,
-                'x': 1
-            },
-            'y': 'foo',
-            'type_name': Q.__type_name__,
-        }
+        base.from_json_str(
+            Q(P(1), y='foo').to_json_str(), convert_unknown=True
+        ),
+        UnknownTypedObject(
+            type_name=Q.__type_name__,
+            p=UnknownTypedObject(
+                type_name=P.__type_name__,
+                x=1
+            ),
+            y='foo'
+        )
     )
 
   def test_serialization_with_converter(self):

pyglove/core/symbolic/unknown_symbols.py

@@ -0,0 +1,147 @@
+# Copyright 2021 The PyGlove Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Symbolic types for reprenting unknown types and objects."""
+
+from typing import Annotated, Any, ClassVar, Literal
+from pyglove.core import typing as pg_typing
+from pyglove.core import utils
+from pyglove.core.symbolic import list as pg_list  # pylint: disable=unused-import
+from pyglove.core.symbolic import object as pg_object
+
+
+class UnknownSymbol(pg_object.Object, pg_typing.CustomTyping):
+  """Interface for symbolic representation of unknown symbols."""
+  auto_register = False
+
+  def custom_apply(self, *args, **kwargs) -> tuple[bool, Any]:
+    """Bypass PyGlove type check."""
+    return (False, self)
+
+
+class UnknownType(UnknownSymbol):
+  """Symbolic object for representing unknown types."""
+
+  auto_register = True
+  __serialization_key__ = 'unknown_type'
+
+  # TODO(daiyip): Revisit the design on how `pg.typing.Object()` handles
+  # UnknownType. This hacky solution should be removed in the future.
+  __no_type_check__ = True
+
+  name: str
+  args: list[Any] = []
+
+  def sym_jsonify(self, **kwargs) -> utils.JSONValueType:
+    json_dict = {'_type': 'type', 'name': self.name}
+    if self.args:
+      json_dict['args'] = utils.to_json(self.args, **kwargs)
+    return json_dict
+
+  def format(
+      self,
+      compact: bool = False,
+      verbose: bool = True,
+      root_indent: int = 0,
+      **kwargs
+  ) -> str:
+    s = f'<unknown-type {self.name}>'
+    if self.args:
+      s += f'[{", ".join(repr(x) for x in self.args)}]'
+    return s
+
+  def __call__(self, **kwargs):
+    return UnknownTypedObject(
+        type_name=self.name, **kwargs
+    )
+
+
+class UnknownCallable(UnknownSymbol):
+  """Symbolic object for representing unknown callables."""
+
+  auto_register = False
+  name: str
+  CALLABLE_TYPE: ClassVar[Literal['function', 'method']]
+
+  def sym_jsonify(self, **kwargs) -> utils.JSONValueType:
+    return {'_type': self.CALLABLE_TYPE, 'name': self.name}
+
+  def format(
+      self,
+      compact: bool = False,
+      verbose: bool = True,
+      root_indent: int = 0,
+      **kwargs
+  ) -> str:
+    return f'<unknown-{self.CALLABLE_TYPE} {self.name}>'
+
+
+class UnknownFunction(UnknownCallable):
+  """Symbolic objject for representing unknown functions."""
+
+  auto_register = True
+  __serialization_key__ = 'unknown_function'
+  CALLABLE_TYPE = 'function'
+
+
+class UnknownMethod(UnknownCallable):
+  """Symbolic object for representing unknown methods."""
+
+  auto_register = True
+  __serialization_key__ = 'unknown_method'
+  CALLABLE_TYPE = 'method'
+
+
+class UnknownTypedObject(UnknownSymbol):
+  """Symbolic object for representing objects of unknown-type."""
+
+  auto_register = True
+  __serialization_key__ = 'unknown_object'
+
+  type_name: str
+  __kwargs__: Annotated[
+      Any,
+      (
+          'Fields of the original object will be kept as symbolic attributes '
+          'of this object so they can be accessed through `__getattr__`.'
+      )
+  ]
+
+  def sym_jsonify(self, **kwargs) -> utils.JSONValueType:
+    """Converts current object to a dict of plain Python objects."""
+    json_dict = self._sym_attributes.to_json(
+        exclude_keys=set(['type_name']), **kwargs
+    )
+    assert isinstance(json_dict, dict)
+    json_dict[utils.JSONConvertible.TYPE_NAME_KEY] = self.type_name
+    return json_dict
+
+  def format(
+      self,
+      compact: bool = False,
+      verbose: bool = True,
+      root_indent: int = 0,
+      **kwargs
+  ) -> str:
+    exclude_keys = kwargs.pop('exclude_keys', set())
+    exclude_keys.add('type_name')
+    kwargs['exclude_keys'] = exclude_keys
+    return self._sym_attributes.format(
+        compact,
+        verbose,
+        root_indent,
+        cls_name=f'<unknown-type {self.type_name}>',
+        key_as_attribute=True,
+        bracket_type=utils.BracketType.ROUND,
+        **kwargs,
+    )

pyglove/core/symbolic/unknown_symbols_test.py

@@ -0,0 +1,100 @@
+# Copyright 2025 The PyGlove Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest
+from pyglove.core import utils
+from pyglove.core.symbolic import unknown_symbols
+
+
+class UnknownTypeTest(unittest.TestCase):
+
+  def test_basics(self):
+    t = unknown_symbols.UnknownType(name='__main__.ABC', args=[int, str])
+    self.assertEqual(t.name, '__main__.ABC')
+    self.assertEqual(t.args, [int, str])
+    self.assertEqual(
+        repr(t),
+        '<unknown-type __main__.ABC>[<class \'int\'>, <class \'str\'>]'
+    )
+    self.assertEqual(
+        t.to_json(),
+        {
+            '_type': 'type',
+            'name': '__main__.ABC',
+            'args': [
+                {'_type': 'type', 'name': 'builtins.int'},
+                {'_type': 'type', 'name': 'builtins.str'},
+            ]
+        }
+    )
+    self.assertEqual(utils.from_json(t.to_json(), convert_unknown=True), t)
+    self.assertEqual(
+        t(x=1, y=2),
+        unknown_symbols.UnknownTypedObject(type_name='__main__.ABC', x=1, y=2)
+    )
+
+
+class UnknownFunctionTest(unittest.TestCase):
+
+  def test_basics(self):
+    t = unknown_symbols.UnknownFunction(name='__main__.foo')
+    self.assertEqual(t.name, '__main__.foo')
+    self.assertEqual(repr(t), '<unknown-function __main__.foo>')
+    self.assertEqual(
+        t.to_json(),
+        {
+            '_type': 'function',
+            'name': '__main__.foo',
+        }
+    )
+    self.assertEqual(utils.from_json(t.to_json(), convert_unknown=True), t)
+
+
+class UnknownMethodTest(unittest.TestCase):
+
+  def test_basics(self):
+    t = unknown_symbols.UnknownMethod(name='__main__.ABC.bar')
+    self.assertEqual(t.name, '__main__.ABC.bar')
+    self.assertEqual(repr(t), '<unknown-method __main__.ABC.bar>')
+    self.assertEqual(
+        t.to_json(),
+        {
+            '_type': 'method',
+            'name': '__main__.ABC.bar',
+        }
+    )
+    self.assertEqual(utils.from_json(t.to_json(), convert_unknown=True), t)
+
+
+class UnknownObjectTest(unittest.TestCase):
+
+  def test_basics(self):
+    v = unknown_symbols.UnknownTypedObject(type_name='__main__.ABC', x=1)
+    self.assertEqual(v.type_name, '__main__.ABC')
+    self.assertEqual(v.x, 1)
+    self.assertEqual(repr(v), '<unknown-type __main__.ABC>(x=1)')
+    self.assertEqual(
+        str(v), '<unknown-type __main__.ABC>(\n  x = 1\n)')
+    self.assertEqual(
+        v.to_json(),
+        {
+            '_type': '__main__.ABC',
+            'x': 1,
+        }
+    )
+    self.assertEqual(utils.from_json(v.to_json(), convert_unknown=True), v)
+
+
+if __name__ == '__main__':
+  unittest.main()

pyglove/core/typing/annotation_conversion.py

@@ -16,6 +16,7 @@
 import builtins
 import collections
 import inspect
+import sys
 import types
 import typing
 
@@ -197,6 +198,8 @@ def annotation_from_str(
   def _resolve(type_id: str):
 
     def _as_forward_ref() -> typing.ForwardRef:
+      if sys.version_info >= (3, 14):
+        return typing.ForwardRef(type_id)  # pytype: disable=not-callable
       return typing.ForwardRef(type_id, False, parent_module)  # pytype: disable=not-callable
 
     def _resolve_name(name: str, parent_obj: typing.Any):

pyglove/core/typing/annotation_conversion_test.py

@@ -34,6 +34,12 @@ class Foo:
 _MODULE = sys.modules[__name__]
 
 
+def typing_forward_ref(name: str) -> typing.ForwardRef:
+  if sys.version_info >= (3, 14):
+    return typing.ForwardRef(name)
+  return typing.ForwardRef(name, False, _MODULE)
+
+
 class AnnotationFromStrTest(unittest.TestCase):
   """Tests for annotation_from_str."""
 
@@ -69,7 +75,7 @@ class AnnotationFromStrTest(unittest.TestCase):
     )
     self.assertEqual(
         annotation_conversion.annotation_from_str('list[Foo.Baz]', _MODULE),
-        list[typing.ForwardRef('Foo.Baz', False, _MODULE)]
+        list[typing_forward_ref('Foo.Baz')]
     )
 
   def test_generic_types(self):
@@ -138,18 +144,12 @@ class AnnotationFromStrTest(unittest.TestCase):
     self.assertEqual(
         annotation_conversion.annotation_from_str(
             'AAA', _MODULE),
-        typing.ForwardRef(
-            'AAA', False, _MODULE
-        )
+        typing_forward_ref('AAA')
     )
     self.assertEqual(
         annotation_conversion.annotation_from_str(
             'typing.List[AAA]', _MODULE),
-        typing.List[
-            typing.ForwardRef(
-                'AAA', False, _MODULE
-            )
-        ]
+        typing.List[typing_forward_ref('AAA')]
     )
 
   def test_reloading(self):
@@ -157,20 +157,12 @@ class AnnotationFromStrTest(unittest.TestCase):
     self.assertEqual(
         annotation_conversion.annotation_from_str(
             'typing.List[Foo]', _MODULE),
-        typing.List[
-            typing.ForwardRef(
-                'Foo', False, _MODULE
-            )
-        ]
+        typing.List[typing_forward_ref('Foo')]
     )
     self.assertEqual(
         annotation_conversion.annotation_from_str(
             'typing.List[Foo.Bar]', _MODULE),
-        typing.List[
-            typing.ForwardRef(
-                'Foo.Bar', False, _MODULE
-            )
-        ]
+        typing.List[typing_forward_ref('Foo.Bar')]
     )
     delattr(_MODULE, '__reloading__')
 

pyglove/core/typing/type_conversion.py

@@ -15,6 +15,7 @@
 
 import calendar
 import datetime
+import sys
 from typing import Any, Callable, Optional, Tuple, Type, Union
 
 from pyglove.core import utils
@@ -135,9 +136,22 @@ def _register_builtin_converters():
   register_converter(int, float, float)
 
   # int <=> datetime.datetime.
-  register_converter(int, datetime.datetime, datetime.datetime.utcfromtimestamp)
-  register_converter(datetime.datetime, int,
-                     lambda x: calendar.timegm(x.timetuple()))
+  if sys.version_info >= (3, 11):
+    register_converter(
+        int,
+        datetime.datetime,
+        lambda x: datetime.datetime.fromtimestamp(x, datetime.UTC)
+    )
+  else:
+    register_converter(
+        int, datetime.datetime, datetime.datetime.utcfromtimestamp
+    )
+
+  register_converter(
+      datetime.datetime,
+      int,
+      lambda x: calendar.timegm(x.timetuple())
+  )
 
   # string <=> KeyPath.
   register_converter(str, utils.KeyPath, utils.KeyPath.parse)

pyglove/core/typing/type_conversion_test.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 import calendar
 import datetime
+import sys
 import typing
 import unittest
 
@@ -130,12 +131,16 @@ class BuiltInConversionsTest(unittest.TestCase):
   def test_datetime_to_int(self):
     """Test built-in converter between int and datetime.datetime."""
     timestamp = calendar.timegm(datetime.datetime.now().timetuple())
-    now = datetime.datetime.utcfromtimestamp(timestamp)
+    if sys.version_info >= (3, 11):
+      now = datetime.datetime.fromtimestamp(timestamp, datetime.UTC)
+    else:
+      now = datetime.datetime.utcfromtimestamp(timestamp)
     self.assertEqual(vs.Object(datetime.datetime).apply(timestamp), now)
     self.assertEqual(vs.Int().apply(now), timestamp)
     self.assertEqual(
         type_conversion.get_json_value_converter(datetime.datetime)(now),
-        timestamp)
+        timestamp
+    )
 
   def test_keypath_to_str(self):
     """Test built-in converter between string and KeyPath."""

pyglove/core/typing/value_specs.py

@@ -1930,8 +1930,12 @@ class Object(Generic, ValueSpecBase):
     elif isinstance(t, type):
       if t is object:
         raise TypeError('<class \'object\'> is too general for Object spec.')
+    elif getattr(t, '__no_type_check__', False):
+      t = object
     elif not pg_inspect.is_generic(t):
-      raise TypeError('"cls" for Object spec should be a type or str.')
+      raise TypeError(
+          f'"cls" for Object spec should be a type or str. Encountered: {t!r}.'
+      )
 
     self._forward_ref = forward_ref
     self._type_args = type_args

pyglove/core/typing/value_specs_test.py

@@ -2193,6 +2193,11 @@ class ObjectTest(ValueSpecTest):
     self.assertEqual(
         vs.Object(forward_ref('Foo')).forward_refs, set([forward_ref('Foo')]))
 
+  def test_no_type_check_special_handling(self):
+    x = self.A()
+    setattr(x, '__no_type_check__', True)
+    self.assertIs(vs.Object(x).cls, object)
+
   def test_default(self):
     self.assertEqual(vs.Object(self.A).default, typed_missing.MISSING_VALUE)
     a = self.A()