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

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()

pyglove/core/utils/json_conversion.py

@@ -685,7 +685,7 @@ def from_json(
     *,
     context: Optional[JSONConversionContext] = None,
     auto_import: bool = True,
-    auto_dict: bool = False,
+    convert_unknown: bool = False,
     **kwargs
 ) -> Any:
   """Deserializes a (maybe) JSONConvertible value from JSON value.
@@ -697,8 +697,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.
     **kwargs: Keyword arguments that will be passed to JSONConvertible.__init__.
 
   Returns:
@@ -707,14 +712,21 @@ def from_json(
   if context is None:
     if (isinstance(json_value, dict)
         and (context_node := json_value.get(JSONConvertible.CONTEXT_KEY))):
-      context = JSONConversionContext.from_json(context_node, **kwargs)
+      context = JSONConversionContext.from_json(
+          context_node,
+          auto_import=auto_import,
+          convert_unknown=convert_unknown,
+          **kwargs
+      )
       json_value = json_value[JSONConvertible.ROOT_VALUE_KEY]
     else:
       context = JSONConversionContext()
 
   typename_resolved = kwargs.pop('_typename_resolved', False)
   if not typename_resolved:
-    json_value = resolve_typenames(json_value, auto_import, auto_dict)
+    json_value = resolve_typenames(
+        json_value, auto_import=auto_import, convert_unknown=convert_unknown
+    )
 
   def child_from(v):
     return from_json(v, context=context, _typename_resolved=True, **kwargs)
@@ -743,7 +755,7 @@ def from_json(
 def resolve_typenames(
     json_value: JSONValueType,
     auto_import: bool = True,
-    auto_dict: bool = False,
+    convert_unknown: bool = False,
 ) -> JSONValueType:
   """Inplace resolves the "_type" keys with their factories in a JSON tree."""
 
@@ -755,11 +767,11 @@ def resolve_typenames(
       return False
     type_name = v[JSONConvertible.TYPE_NAME_KEY]
     if type_name == 'type':
-      factory_fn = _type_from_json
+      factory_fn = _type_from_json(convert_unknown)
     elif type_name == 'function':
-      factory_fn = _function_from_json
+      factory_fn = _function_from_json(convert_unknown)
     elif type_name == 'method':
-      factory_fn = _method_from_json
+      factory_fn = _method_from_json(convert_unknown)
     else:
       cls = JSONConvertible.class_from_typename(type_name)
       if cls is None:
@@ -768,32 +780,38 @@ def resolve_typenames(
             cls = _load_symbol(type_name)
             assert inspect.isclass(cls), cls
           except (ModuleNotFoundError, AttributeError) as e:
-            if not auto_dict:
+            if not convert_unknown:
               raise TypeError(
                   f'Cannot load class {type_name!r}.\n'
-                  'Try pass `auto_dict=True` to load the object into a dict '
-                  'without depending on the type.'
+                  'Try pass `convert_unknown=True` to load the object into '
+                  '`pg.symbolic.UnknownObject` without depending on the type.'
               ) from e
-        elif not auto_dict:
+        elif not convert_unknown:
           raise TypeError(
               f'Type name \'{type_name}\' is not registered '
               'with a `pg.JSONConvertible` subclass.\n'
-              'Try pass `auto_import=True` to load the type from its module, '
-              'or pass `auto_dict=True` to load the object into a dict '
-              'without depending on the type.'
+              'Try pass `auto_import=True` to load the type from its module.'
           )
 
       factory_fn = getattr(cls, 'from_json', None)
-      if cls is not None and factory_fn is None and not auto_dict:
+      if cls is not None and factory_fn is None and not convert_unknown:
         raise TypeError(
             f'{cls} is not a `pg.JSONConvertible` subclass.'
-            'Try pass `auto_dict=True` to load the object into a dict '
-            'without depending on the type.'
+            'Try pass `convert_unknown=True` to load the object into a '
+            '`pg.symbolic.UnknownObject` without depending on the type.'
         )
 
-      if factory_fn is None and auto_dict:
-        v['type_name'] = type_name
-        v.pop(JSONConvertible.TYPE_NAME_KEY)
+      if factory_fn is None and convert_unknown:
+        type_name = v[JSONConvertible.TYPE_NAME_KEY]
+        def _factory_fn(json_value: Dict[str, Any], **kwargs):
+          del kwargs
+          # See `pg.symbolic.UnknownObject` for details.
+          unknown_object_cls = JSONConvertible.class_from_typename(
+              'unknown_object'
+          )
+          return unknown_object_cls(type_name=type_name, **json_value)  # pytype: disable=wrong-keyword-args
+
+        v[JSONConvertible.TYPE_NAME_KEY] = _factory_fn
         return True
       assert factory_fn is not None
 
@@ -992,39 +1010,79 @@ def _load_symbol(type_name: str) -> Any:
   return symbol
 
 
-def _type_from_json(json_value: Dict[str, str], **kwargs) -> Type[Any]:
+def _type_from_json(convert_unknown: bool) -> Callable[..., Any]:
   """Loads a type from a JSON dict."""
-  del kwargs
-  t = _load_symbol(json_value['name'])
-  if 'args' in json_value:
-    return _bind_type_args(
-        t, from_json(json_value['args'], _typename_resolved=True)
-    )
-  return t
+  def _fn(json_value: Dict[str, str], **kwargs) -> Type[Any]:
+    del kwargs
+    try:
+      t = _load_symbol(json_value['name'])
+      if 'args' in json_value:
+        return _bind_type_args(
+            t, from_json(json_value['args'], _typename_resolved=True)
+        )
+      return t
+    except (ModuleNotFoundError, AttributeError) as e:
+      if not convert_unknown:
+        raise TypeError(
+            f'Cannot load type {json_value["name"]!r}.\n'
+            'Try pass `convert_unknown=True` to load the object '
+            'into `pg.UnknownType` without depending on the type.'
+        ) from e
+      # See `pg.symbolic.UnknownType` for details.
+      json_value[JSONConvertible.TYPE_NAME_KEY] = 'unknown_type'
+      return from_json(json_value)
+  return _fn
 
 
 def _function_from_json(
-    json_value: Dict[str, str], **kwargs) -> types.FunctionType:
+    convert_unknown: bool
+) -> Callable[..., types.FunctionType]:
   """Loads a function from a JSON dict."""
-  del kwargs
-  function_name = json_value['name']
-  if 'code' in json_value:
-    code = marshal.loads(
-        base64.decodebytes(json_value['code'].encode('utf-8')))
-    defaults = from_json(json_value['defaults'], _typename_resolved=True)
-    return types.FunctionType(
-        code=code,
-        globals=globals(),
-        argdefs=defaults,
-    )
-  else:
-    return _load_symbol(function_name)
-
-
-def _method_from_json(json_value: Dict[str, str], **kwargs) -> types.MethodType:
+  def _fn(json_value: Dict[str, str], **kwargs) -> types.FunctionType:
+    del kwargs
+    function_name = json_value['name']
+    if 'code' in json_value:
+      code = marshal.loads(
+          base64.decodebytes(json_value['code'].encode('utf-8')))
+      defaults = from_json(json_value['defaults'], _typename_resolved=True)
+      return types.FunctionType(
+          code=code,
+          globals=globals(),
+          argdefs=defaults,
+      )
+    else:
+      try:
+        return _load_symbol(function_name)
+      except (ModuleNotFoundError, AttributeError) as e:
+        if not convert_unknown:
+          raise TypeError(
+              f'Cannot load function {function_name!r}.\n'
+              'Try pass `convert_unknown=True` to load the object into '
+              '`pg.UnknownFunction` without depending on the type.'
+          ) from e
+        json_value[JSONConvertible.TYPE_NAME_KEY] = 'unknown_function'
+        return from_json(json_value)
+  return _fn
+
+
+def _method_from_json(
+    convert_unknown: bool
+) -> Callable[..., types.MethodType]:
   """Loads a class method from a JSON dict."""
-  del kwargs
-  return _load_symbol(json_value['name'])
+  def _fn(json_value: Dict[str, str], **kwargs) -> types.MethodType:
+    del kwargs
+    try:
+      return _load_symbol(json_value['name'])
+    except (ModuleNotFoundError, AttributeError) as e:
+      if not convert_unknown:
+        raise TypeError(
+            f'Cannot load method {json_value["name"]!r}.\n'
+            'Try pass `convert_unknown=True` to load the object '
+            'into `pg.UnknownMethod` without depending on the type.'
+        ) from e
+      json_value[JSONConvertible.TYPE_NAME_KEY] = 'unknown_method'
+      return from_json(json_value)
+  return _fn
 
 
 def _bind_type_args(t, args):