pyglove 0.5.0.dev202510200810__py3-none-any.whl → 0.5.0.dev202512280810__py3-none-any.whl

pyglove/core/symbolic/ref_test.py

@@ -21,8 +21,11 @@ from typing import Any
 import unittest
 
 from pyglove.core import typing as pg_typing
+from pyglove.core.symbolic import list as pg_list  # pylint: disable=unused-import
 from pyglove.core.symbolic import ref
 from pyglove.core.symbolic.base import contains
+from pyglove.core.symbolic.base import from_json
+from pyglove.core.symbolic.base import to_json
 from pyglove.core.symbolic.dict import Dict
 from pyglove.core.symbolic.object import Object
 
@@ -33,6 +36,10 @@ class A(Object):
 
 class RefTest(unittest.TestCase):
 
+  def setUp(self):
+    super().setUp()
+    self.maxDiff = None
+
   def test_basics(self):
 
     a = A(1)
@@ -109,14 +116,94 @@ class RefTest(unittest.TestCase):
         """))
 
   def test_to_json(self):
-    with self.assertRaisesRegex(
-        TypeError, '.* cannot be serialized at the moment'):
-      ref.Ref(A(1)).to_json()
+    class B(Object):
+      y: Any
 
-    self.assertEqual(
-        ref.Ref(A(1)).to_json(save_ref_value=True),
-        A(1).to_json()
-    )
+    a = A(1)
+    r1 = ref.Ref(a)
+    r2 = ref.Ref({'z': a})
+    r3 = ref.Ref(Dict(t=r1, p=r2))
+    v = Dict(a=r1, b=[B(r2), [r3], r1])
+    self.assertIs(v.a, v.b[0].y['z'])
+    self.assertIs(v.a, v.b[1][0].t)
+    self.assertIs(v.b[0].y, v.b[1][0].p)
+    self.assertIs(v.a, v.b[2])
+    self.assertIsInstance(v, dict)
+    self.assertIsInstance(v.b[0].y, dict)
+    self.assertNotIsInstance(v.b[0].y, Dict)
+    self.assertIsInstance(v.b[1][0], Dict)
+
+    json = to_json(v)
+    expected = {
+        '__context__': {
+            'shared_objects': [
+                {
+                    '_type': A.__type_name__,
+                    'x': 1
+                },
+                {
+                    'z': {
+                        '__ref__': 0
+                    }
+                }
+            ]
+        },
+        '__root__': {
+            'a': {
+                '_type': ref.Ref.__type_name__,
+                'value': {
+                    '__ref__': 0
+                }
+            },
+            'b': [
+                {
+                    '_type': B.__type_name__,
+                    'y': {
+                        '_type': ref.Ref.__type_name__,
+                        'value': {
+                            '__ref__': 1
+                        }
+                    }
+                },
+                [
+                    {
+                        '_type': ref.Ref.__type_name__,
+                        'value': {
+                            '__symbolic__': True,
+                            't': {
+                                '_type': ref.Ref.__type_name__,
+                                'value': {
+                                    '__ref__': 0
+                                }
+                            },
+                            'p': {
+                                '_type': ref.Ref.__type_name__,
+                                'value': {
+                                    '__ref__': 1
+                                }
+                            }
+                        }
+                    }
+                ],
+                {
+                    '_type': ref.Ref.__type_name__,
+                    'value': {
+                        '__ref__': 0
+                    }
+                }
+            ]
+        }
+    }
+    self.assertEqual(json, expected)
+    v = from_json(json)
+    self.assertIs(v.a, v.b[0].y['z'])
+    self.assertIs(v.a, v.b[1][0].t)
+    self.assertIs(v.b[0].y, v.b[1][0].p)
+    self.assertIs(v.a, v.b[2])
+    self.assertIsInstance(v, dict)
+    self.assertIsInstance(v.b[0].y, dict)
+    self.assertNotIsInstance(v.b[0].y, Dict)
+    self.assertIsInstance(v.b[1][0], Dict)
 
   def test_pickle(self):
     with self.assertRaisesRegex(

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):
@@ -318,6 +321,9 @@ def _value_spec_from_type_annotation(
     parent_module: typing.Optional[types.ModuleType] = None
 ) -> class_schema.ValueSpec:
   """Creates a value spec from type annotation."""
+  if isinstance(annotation, class_schema.ValueSpec):
+    return annotation
+
   if isinstance(annotation, str) and not accept_value_as_annotation:
     annotation = annotation_from_str(annotation, parent_module)
 
@@ -454,7 +460,8 @@ def _value_spec_from_annotation(
   """Creates a value spec from annotation."""
   if isinstance(annotation, class_schema.ValueSpec):
     return annotation
-  elif annotation == inspect.Parameter.empty:
+
+  if annotation == inspect.Parameter.empty:
     return vs.Any()
 
   if annotation is None:

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__')
 
@@ -396,6 +388,9 @@ class ValueSpecFromAnnotationTest(unittest.TestCase):
     self.assertEqual(
         ValueSpec.from_annotation(typing.Dict[str, int], True),
         vs.Dict([(ks.StrKey(), vs.Int())]))
+    self.assertEqual(
+        ValueSpec.from_annotation(typing.Dict[str, vs.Int()], True),
+        vs.Dict([(ks.StrKey(), vs.Int())]))
     self.assertEqual(
         ValueSpec.from_annotation(typing.Mapping[str, int], True),
         vs.Dict([(ks.StrKey(), vs.Int())]))

pyglove/core/typing/class_schema.py

@@ -1229,6 +1229,9 @@ class Schema(utils.Formattable, utils.JSONConvertible):
           f'(parent=\'{root_path}\')'
       )
 
+    # Symbolic.Dict uses `sym_getattr` to support getting symbolic attributes.
+    get_value = getattr(dict_obj, 'sym_getattr', dict_obj.get)
+
     for key_spec, keys in matched_keys.items():
       field = self._fields[key_spec]
       # For missing const keys, we add to keys collection to add missing value.
@@ -1236,7 +1239,7 @@ class Schema(utils.Formattable, utils.JSONConvertible):
         keys.append(str(key_spec))
       for key in keys:
         if dict_obj:
-          value = dict_obj.get(key, utils.MISSING_VALUE)
+          value = get_value(key, utils.MISSING_VALUE)
         else:
           value = utils.MISSING_VALUE
         # NOTE(daiyip): field.default_value may be MISSING_VALUE too

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/__init__.py

@@ -74,6 +74,7 @@ modules with the following features:
 from pyglove.core.utils.json_conversion import Nestable
 from pyglove.core.utils.json_conversion import JSONValueType
 
+from pyglove.core.utils.json_conversion import JSONConversionContext
 from pyglove.core.utils.json_conversion import JSONConvertible
 from pyglove.core.utils.json_conversion import from_json
 from pyglove.core.utils.json_conversion import to_json