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

pyglove/core/geno/base.py

@@ -1447,6 +1447,7 @@ class DNA(symbolic.Object):
       *,
       allow_partial: bool = False,
       root_path: Optional[utils.KeyPath] = None,
+      **kwargs,
   ) -> 'DNA':
     """Class method that load a DNA from a JSON value.
 
@@ -1454,6 +1455,7 @@ class DNA(symbolic.Object):
       json_value: Input JSON value, only JSON dict is acceptable.
       allow_partial: Whether to allow elements of the list to be partial.
       root_path: KeyPath of loaded object in its object tree.
+      **kwargs: Keyword arguments that will be passed to symbolic.from_json.
 
     Returns:
       A DNA object.
@@ -1463,16 +1465,18 @@ class DNA(symbolic.Object):
       # NOTE(daiyip): DNA.parse will validate the input. Therefore, we can
       # disable runtime type check during constructing the DNA objects.
       with symbolic.enable_type_check(False):
-        dna = DNA.parse(symbolic.from_json(json_value.get('value')))
+        dna = DNA.parse(symbolic.from_json(json_value.get('value'), **kwargs))
         if 'metadata' in json_value:
           dna.rebind(
-              metadata=symbolic.from_json(json_value.get('metadata')),
+              metadata=symbolic.from_json(json_value.get('metadata'), **kwargs),
               raise_on_no_change=False, skip_notification=True)
     else:
       dna = super(DNA, cls).from_json(
           json_value,
           allow_partial=allow_partial,
-          root_path=root_path)  # pytype: disable=bad-return-type
+          root_path=root_path,
+          **kwargs,
+      )  # pytype: disable=bad-return-type
       assert isinstance(dna, DNA)
     if cloneable_metadata_keys:
       dna._cloneable_metadata_keys = set(cloneable_metadata_keys)  # pylint: disable=protected-access

pyglove/core/symbolic/base.py

@@ -946,7 +946,7 @@ class Symbolic(
 
   def to_json(self, **kwargs) -> utils.JSONValueType:
     """Alias for `sym_jsonify`."""
-    return to_json(self, **kwargs)
+    return utils.to_json(self, **kwargs)
 
   def to_json_str(self, json_indent: Optional[int] = None, **kwargs) -> str:
     """Serializes current object into a JSON string."""
@@ -1985,10 +1985,12 @@ def is_abstract(x: Any) -> bool:
 def contains(
     x: Any,
     value: Any = None,
-    type: Optional[Union[    # pylint: disable=redefined-builtin
+    type: Union[    # pylint: disable=redefined-builtin
         Type[Any],
-        Tuple[Type[Any]]]]=None
-    ) -> bool:
+        Tuple[Type[Any], ...],
+        None,
+    ]=None,
+) -> bool:
   """Returns if a value contains values of specific type.
 
   Example::
@@ -2037,10 +2039,12 @@ def contains(
 def from_json(
     json_value: Any,
     *,
-    allow_partial: bool = False,
-    root_path: Optional[utils.KeyPath] = None,
+    context: Optional[utils.JSONConversionContext] = None,
+    auto_symbolic: bool = True,
     auto_import: bool = True,
     auto_dict: bool = False,
+    allow_partial: bool = False,
+    root_path: Optional[utils.KeyPath] = None,
     value_spec: Optional[pg_typing.ValueSpec] = None,
     **kwargs,
 ) -> Any:
@@ -2061,14 +2065,18 @@ def from_json(
 
   Args:
     json_value: Input JSON value.
-    allow_partial: Whether to allow elements of the list to be partial.
-    root_path: KeyPath of loaded object in its object tree.
+    context: JSON conversion context.
+    auto_symbolic: If True, list and dict will be automatically converted to
+      `pg.List` and `pg.Dict`. Otherwise, they will be plain lists
+      and dicts.
     auto_import: If True, when a '_type' is not registered, PyGlove will
       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'.
+    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.
     **kwargs: Allow passing through keyword arguments to from_json of specific
       types.
@@ -2084,10 +2092,18 @@ def from_json(
   if isinstance(json_value, Symbolic):
     return json_value
 
+  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)
+      json_value = json_value[utils.JSONConvertible.ROOT_VALUE_KEY]
+    else:
+      context = utils.JSONConversionContext()
+
   typename_resolved = kwargs.pop('_typename_resolved', False)
   if not typename_resolved:
     json_value = utils.json_conversion.resolve_typenames(
-        json_value, auto_import=auto_import, auto_dict=auto_dict
+        json_value, auto_import, auto_dict
     )
 
   def _load_child(k, v):
@@ -2096,6 +2112,7 @@ def from_json(
         root_path=utils.KeyPath(k, root_path),
         _typename_resolved=True,
         allow_partial=allow_partial,
+        context=context,
         **kwargs,
     )
 
@@ -2111,24 +2128,42 @@ def from_json(
             )
         )
       return tuple(_load_child(i, v) for i, v in enumerate(json_value[1:]))
-    return Symbolic.ListType.from_json(    # pytype: disable=attribute-error
+    if json_value and json_value[0] == utils.JSONConvertible.SYMBOLIC_MARKER:
+      auto_symbolic = True
+    if auto_symbolic:
+      from_json_fn = Symbolic.ListType.from_json  # pytype: disable=attribute-error
+    else:
+      from_json_fn = utils.from_json
+    return from_json_fn(
         json_value,
+        context=context,
         value_spec=value_spec,
         root_path=root_path,
         allow_partial=allow_partial,
         **kwargs,
     )
   elif isinstance(json_value, dict):
+    if utils.JSONConvertible.REF_KEY in json_value:
+      x = context.get_shared(
+          json_value[utils.JSONConvertible.REF_KEY]
+      ).value
+      return x
     if utils.JSONConvertible.TYPE_NAME_KEY not in json_value:
-      return Symbolic.DictType.from_json(   # pytype: disable=attribute-error
-          json_value,
-          value_spec=value_spec,
-          root_path=root_path,
-          allow_partial=allow_partial,
-          **kwargs,
+      auto_symbolic = json_value.get(
+          utils.JSONConvertible.SYMBOLIC_MARKER, auto_symbolic
       )
+      if auto_symbolic:
+        return Symbolic.DictType.from_json(   # pytype: disable=attribute-error
+            json_value,
+            context=context,
+            value_spec=value_spec,
+            root_path=root_path,
+            allow_partial=allow_partial,
+            **kwargs,
+        )
     return utils.from_json(
         json_value,
+        context=context,
         _typename_resolved=True,
         root_path=root_path,
         allow_partial=allow_partial,
@@ -2140,10 +2175,12 @@ def from_json(
 def from_json_str(
     json_str: str,
     *,
-    allow_partial: bool = False,
-    root_path: Optional[utils.KeyPath] = None,
+    context: Optional[utils.JSONConversionContext] = None,
     auto_import: bool = True,
     auto_dict: bool = False,
+    allow_partial: bool = False,
+    root_path: Optional[utils.KeyPath] = None,
+    value_spec: Optional[pg_typing.ValueSpec] = None,
     **kwargs,
 ) -> Any:
   """Deserialize (maybe) symbolic object from JSON string.
@@ -2163,15 +2200,17 @@ def from_json_str(
 
   Args:
     json_str: JSON string.
-    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.
+    context: JSON conversion context.
     auto_import: If True, when a '_type' is not registered, PyGlove will
       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'.
+    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.
+    value_spec: The value spec for the symbolic list or dict.
     **kwargs: Additional keyword arguments that will be passed to
       ``pg.from_json``.
 
@@ -2195,10 +2234,12 @@ def from_json_str(
 
   return from_json(
       _decode_int_keys(json.loads(json_str)),
-      allow_partial=allow_partial,
-      root_path=root_path,
+      context=context,
       auto_import=auto_import,
       auto_dict=auto_dict,
+      allow_partial=allow_partial,
+      root_path=root_path,
+      value_spec=value_spec,
       **kwargs
   )
 
@@ -2234,10 +2275,6 @@ def to_json(value: Any, **kwargs) -> Any:
   Returns:
     JSON value.
   """
-  # NOTE(daiyip): special handling `sym_jsonify` since symbolized
-  # classes may have conflicting `to_json` method in their existing classes.
-  if isinstance(value, Symbolic):
-    return value.sym_jsonify(**kwargs)
   return utils.to_json(value, **kwargs)
 
 

pyglove/core/symbolic/base_test.py

@@ -20,9 +20,9 @@ from pyglove.core import typing as pg_typing
 from pyglove.core import utils
 from pyglove.core import views
 from pyglove.core.symbolic import base
-from pyglove.core.symbolic.dict import Dict
-from pyglove.core.symbolic.inferred import ValueFromParentChain
-from pyglove.core.symbolic.object import Object
+from pyglove.core.symbolic.dict import Dict                      # pylint: disable=g-importing-member
+from pyglove.core.symbolic.inferred import ValueFromParentChain  # pylint: disable=g-importing-member
+from pyglove.core.symbolic.object import Object                  # pylint: disable=g-importing-member
 
 
 class FieldUpdateTest(unittest.TestCase):

pyglove/core/symbolic/dict.py

@@ -156,6 +156,8 @@ class Dict(dict, base.Symbolic, pg_typing.CustomTyping):
         # Not okay:
         d.a.f2.abc = 1
     """
+    # Remove symbolic marker if present.
+    json_value.pop(utils.JSONConvertible.SYMBOLIC_MARKER, None)
     return cls(
         {
             k: base.from_json(
@@ -835,12 +837,15 @@ class Dict(dict, base.Symbolic, pg_typing.CustomTyping):
       hide_default_values: bool = False,
       exclude_keys: Optional[Sequence[Union[str, int]]] = None,
       use_inferred: bool = False,
+      omit_symbolic_marker: bool = True,
       **kwargs,
   ) -> utils.JSONValueType:
     """Converts current object to a dict with plain Python objects."""
     exclude_keys = set(exclude_keys or [])
+    json_repr = {}
+    if not omit_symbolic_marker:
+      json_repr[utils.JSONConvertible.SYMBOLIC_MARKER] = True
     if self._value_spec and self._value_spec.schema:
-      json_repr = dict()
       matched_keys, _ = self._value_spec.schema.resolve(self.keys())  # pytype: disable=attribute-error
       for key_spec, keys in matched_keys.items():
         # NOTE(daiyip): The key values of frozen field can safely be excluded
@@ -862,20 +867,23 @@ class Dict(dict, base.Symbolic, pg_typing.CustomTyping):
                 hide_frozen=hide_frozen,
                 hide_default_values=hide_default_values,
                 use_inferred=use_inferred,
-                **kwargs)
-      return json_repr
+                omit_symbolic_marker=omit_symbolic_marker,
+                **kwargs
+            )
     else:
-      return {
+      json_repr.update({
           k: base.to_json(
               self.sym_inferred(k, default=v) if (
                   use_inferred and isinstance(v, base.Inferential)) else v,
               hide_frozen=hide_frozen,
               hide_default_values=hide_default_values,
               use_inferred=use_inferred,
+              omit_symbolic_marker=omit_symbolic_marker,
               **kwargs)
           for k, v in self.sym_items()
           if k not in exclude_keys
-      }
+      })
+    return json_repr
 
   def custom_apply(
       self,

pyglove/core/symbolic/dict_test.py

@@ -946,6 +946,14 @@ class DictTest(unittest.TestCase):
         sd.sym_jsonify(),
         {'x': 1, 'y': inferred.ValueFromParentChain().to_json()},
     )
+    self.assertEqual(
+        sd.sym_jsonify(omit_symbolic_marker=False),
+        {
+            '__symbolic__': True,
+            'x': 1,
+            'y': inferred.ValueFromParentChain().to_json()
+        },
+    )
 
   def test_sym_rebind(self):
     # Refer to RebindTest for more detailed tests.
@@ -1964,6 +1972,24 @@ class SerializationTest(unittest.TestCase):
     self.assertEqual(sd.to_json_str(), '{"x": 1, "y": 2.0}')
     self.assertEqual(base.from_json_str(sd.to_json_str(), value_spec=spec), sd)
 
+  def test_auto_symbolic(self):
+    value = base.from_json({'x': 1}, auto_symbolic=True)
+    self.assertIsInstance(value, Dict)
+
+    value = base.from_json({'x': 1}, auto_symbolic=False)
+    self.assertNotIsInstance(value, Dict)
+
+  def test_omit_symbolic_marker(self):
+    sd = Dict(x=1)
+    self.assertEqual(sd.to_json(omit_symbolic_marker=True), {'x': 1})
+    self.assertEqual(
+        sd.to_json(omit_symbolic_marker=False),
+        {'__symbolic__': True, 'x': 1}
+    )
+    sd = base.from_json({'__symbolic__': True, 'x': 1}, auto_symbolic=False)
+    self.assertIsInstance(sd, Dict)
+    self.assertEqual(sd, {'x': 1})
+
   def test_hide_frozen(self):
 
     class A(pg_object.Object):

pyglove/core/symbolic/list.py

@@ -137,6 +137,9 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
     Returns:
       A schema-less symbolic list, but its items maybe symbolic.
     """
+    # Remove symbolic marker if present.
+    if json_value and json_value[0] == utils.JSONConvertible.SYMBOLIC_MARKER:
+      json_value.pop(0)
     return cls(
         [
             base.from_json(
@@ -770,15 +773,26 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
     return (proceed_with_standard_apply, self)
 
   def sym_jsonify(
-      self, use_inferred: bool = False, **kwargs
+      self,
+      use_inferred: bool = False,
+      omit_symbolic_marker: bool = True,
+      **kwargs
   ) -> utils.JSONValueType:
     """Converts current list to a list of plain Python objects."""
     def json_item(idx):
       v = self.sym_getattr(idx)
       if use_inferred and isinstance(v, base.Inferential):
         v = self.sym_inferred(idx, default=v)
-      return base.to_json(v, use_inferred=use_inferred, **kwargs)
-    return [json_item(i) for i in range(len(self))]
+      return base.to_json(
+          v,
+          use_inferred=use_inferred,
+          omit_symbolic_marker=omit_symbolic_marker,
+          **kwargs
+      )
+    json_value = [json_item(i) for i in range(len(self))]
+    if not omit_symbolic_marker:
+      json_value.insert(0, utils.JSONConvertible.SYMBOLIC_MARKER)
+    return json_value
 
   def format(
       self,

pyglove/core/symbolic/list_test.py

@@ -799,6 +799,10 @@ class ListTest(unittest.TestCase):
     self.assertEqual(
         sl.sym_jsonify(), [0, inferred.ValueFromParentChain().to_json()]
     )
+    self.assertEqual(
+        sl.sym_jsonify(omit_symbolic_marker=False),
+        ['__symbolic__', 0, inferred.ValueFromParentChain().to_json()]
+    )
 
   def test_sym_rebind(self):
     # Refer to RebindTest for more detailed tests.
@@ -1633,6 +1637,25 @@ class SerializationTest(unittest.TestCase):
         'Tuple should have at least one element besides \'__tuple__\'.'):
       base.from_json_str('["__tuple__"]')
 
+  def test_auto_symbolic(self):
+    value = base.from_json([1, 2, 3], auto_symbolic=True)
+    self.assertIsInstance(value, List)
+
+    value = base.from_json([1, 2, 3], auto_symbolic=False)
+    self.assertNotIsInstance(value, List)
+
+  def test_omit_symbolic_marker(self):
+    sl = List([0])
+    self.assertEqual(sl.to_json(omit_symbolic_marker=True), [0])
+    self.assertEqual(
+        sl.to_json(omit_symbolic_marker=False),
+        ['__symbolic__', 0]
+    )
+    sl = base.from_json(['__symbolic__', 0], auto_symbolic=False)
+    self.assertEqual(sl.to_json(omit_symbolic_marker=True), [0])
+    self.assertIsInstance(sl, List)
+    self.assertEqual(sl, [0])
+
   def test_hide_default_values(self):
     sl = List.partial(
         [dict(x=1)],

pyglove/core/symbolic/object.py

@@ -994,6 +994,7 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
             self.__class__.__serialization_key__
         )
     }
+    kwargs['omit_symbolic_marker'] = True
     json_dict.update(self._sym_attributes.to_json(**kwargs))
     return json_dict
 

pyglove/core/symbolic/ref.py

@@ -138,9 +138,7 @@ class Ref(
     del child_transform
     # Check if the field being assigned could accept the referenced value.
     # We do not do any transformation, thus not passing the child transform.
-    value_spec.apply(
-        self._value,
-        allow_partial=allow_partial)
+    value_spec.apply(self._value, allow_partial=allow_partial)
     return (False, self)
 
   def _sym_clone(self, deep: bool, memo: Any = None) -> 'Ref':
@@ -152,10 +150,24 @@ class Ref(
   def sym_eq(self, other: Any) -> bool:
     return isinstance(other, Ref) and self.value is other.value
 
-  def sym_jsonify(self, *, save_ref_value: bool = False, **kwargs: Any) -> Any:
-    if save_ref_value:
-      return base.to_json(self._value, save_ref_value=save_ref_value, **kwargs)
-    raise TypeError(f'{self!r} cannot be serialized at the moment.')
+  def sym_jsonify(
+      self,
+      *,
+      context: utils.JSONConversionContext,
+      **kwargs: Any
+  ) -> Any:
+    # Disable auto_symbolic for Ref value. This allows Ref to create a sub-tree
+    # for reference sharing.
+    kwargs['omit_symbolic_marker'] = False
+    return {
+        utils.JSONConvertible.TYPE_NAME_KEY: self.__class__.__type_name__,
+        'value': context.serialize_maybe_shared(self._value, **kwargs)
+    }
+
+  @classmethod
+  def from_json(cls, json: Any, **kwargs):
+    kwargs['auto_symbolic'] = False
+    return super().from_json(json, **kwargs)
 
   def __getstate__(self):
     raise TypeError(f'{self!r} cannot be pickled at the moment.')

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/typing/annotation_conversion.py

@@ -318,6 +318,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 +457,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

@@ -396,6 +396,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/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

pyglove/core/utils/json_conversion.py

@@ -17,6 +17,7 @@ import abc
 import base64
 import collections
 import contextlib
+import dataclasses
 import importlib
 import inspect
 import marshal
@@ -25,6 +26,7 @@ import types
 import typing
 from typing import Any, Callable, ContextManager, Dict, Iterable, Iterator, List, Optional, Sequence, Set, Tuple, Type, TypeVar, Union
 
+
 # Nestable[T] is a (maybe) nested structure of T, which could be T, a Dict
 # a List or a Tuple of Nestable[T]. We use a Union to fool PyType checker to
 # make Nestable[T] a valid type annotation without type check.
@@ -186,6 +188,19 @@ class JSONConvertible(metaclass=abc.ABCMeta):
   # Marker (as the first element of a list) for serializing tuples.
   TUPLE_MARKER = '__tuple__'
 
+  # Marker (as the first element of a list or key of a dict) for symbolic
+  # lists and dicts.
+  SYMBOLIC_MARKER = '__symbolic__'
+
+  # Marker for references to shared objects.
+  REF_KEY = '__ref__'
+
+  # Marker for root value when JSONConversionContext is used.
+  ROOT_VALUE_KEY = '__root__'
+
+  # Marker for JSONConversionContext.
+  CONTEXT_KEY = '__context__'
+
   # Type converter that converts a complex type to basic JSON value type.
   # When this field is set by users, the converter will be invoked when a
   # complex value cannot be serialized by existing methods.
@@ -215,7 +230,12 @@ class JSONConvertible(metaclass=abc.ABCMeta):
     return cls(**init_args)
 
   @abc.abstractmethod
-  def to_json(self, **kwargs) -> JSONValueType:
+  def to_json(
+      self,
+      *,
+      context: Optional['JSONConversionContext'] = None,
+      **kwargs
+  ) -> JSONValueType:
     """Returns a plain Python value as a representation for this object.
 
     A plain Python value are basic python types that can be serialized into
@@ -224,6 +244,7 @@ class JSONConvertible(metaclass=abc.ABCMeta):
     Python values as their values.
 
     Args:
+      context: JSON conversion context.
       **kwargs: Keyword arguments as flags to control JSON conversion.
 
     Returns:
@@ -389,8 +410,14 @@ class _OpaqueObject(JSONConvertible):
     }, **kwargs)
 
   @classmethod
-  def from_json(cls, json_value: JSONValueType, *args, **kwargs) -> Any:
-    del args, kwargs
+  def from_json(
+      cls,
+      json_value: JSONValueType,
+      *args,
+      context: Optional['JSONConversionContext'] = None,
+      **kwargs
+  ) -> Any:
+    del args, context, kwargs
     assert isinstance(json_value, dict) and 'value' in json_value, json_value
     encoder = cls(json_value['value'], encoded=True)
     return encoder.value
@@ -401,7 +428,169 @@ def registered_types() -> Iterable[Tuple[str, Type[JSONConvertible]]]:
   return JSONConvertible.registered_types()
 
 
-def to_json(value: Any, **kwargs) -> Any:
+class JSONConversionContext(JSONConvertible):
+  """JSON conversion context.
+
+  JSONConversionContext is introduced to handle serialization scenarios where
+  operations cannot be performed in a single pass. For example: Serialization
+  and deserialization of shared objects across different locations.
+
+  # Shared object serialization/deserialization.
+
+  In PyGlove, only values referenced by `pg.Ref` and non-PyGlove managed objects
+  are sharable. This ensures that multiple references to the same object are
+  serialized only once. During deserialization, the object is created just once
+  and shared among all references.
+  """
+
+  @dataclasses.dataclass
+  class ObjectEntry:
+    value: Any
+    serialized: Optional[JSONValueType]
+    ref_index: int
+    ref_count: int
+
+  def __init__(self,) -> None:
+    self._shared_objects: list[JSONConversionContext.ObjectEntry] = []
+    self._id_to_shared_object = {}
+
+  def get_shared(self, ref_index: int) -> ObjectEntry:
+    """Gets the shared object of a ref index."""
+    return self._shared_objects[ref_index]
+
+  def add_shared(self, shared: ObjectEntry) -> None:
+    self._shared_objects.append(shared)
+    self._id_to_shared_object[id(shared.value)] = shared
+
+  def next_shared_index(self) -> int:
+    """Returns the next shared index."""
+    return len(self._shared_objects)
+
+  def serialize_maybe_shared(
+      self,
+      value: Any,
+      json_fn: Optional[Callable[..., JSONValueType]] = None,
+      **kwargs
+  ) -> JSONValueType:
+    """Track maybe shared objects and returns their JSON representation."""
+    if json_fn is None:
+      json_fn = lambda **kwargs: to_json(value, **kwargs)
+    kwargs.pop('context', None)
+    value_id = id(value)
+    shared_object = self._id_to_shared_object.get(value_id)
+    if shared_object is None:
+      serialized = json_fn(context=self, **kwargs)
+
+      # It's possible that maybe_shared_json is called recursively on the same
+      # object, thus we need to check for self-references explicitly.
+      if (isinstance(serialized, dict)
+          and JSONConvertible.REF_KEY in serialized
+          and len(serialized) == 1):
+        return serialized
+
+      shared_object = self.ObjectEntry(
+          value=value,
+          serialized=serialized,
+          ref_index=self.next_shared_index(),
+          ref_count=0,
+      )
+      self._shared_objects.append(shared_object)
+      self._id_to_shared_object[value_id] = shared_object
+    shared_object.ref_count += 1
+    return {
+        JSONConvertible.REF_KEY: shared_object.ref_index
+    }
+
+  def _maybe_deref(self, serialized: Any, ref_index_map: dict[int, int]) -> Any:
+    """In-place dereference ref-1 shared objects in an object tree.
+
+    Args:
+      serialized: The object tree to dereference.
+      ref_index_map: A map from the original index of shared objects to their
+        indices after the ref-1 shared objects are trimmed.
+
+    Returns:
+      The (maybe) dereferenced object tree.
+    """
+    if isinstance(serialized, dict):
+      ref_index = serialized.get(JSONConvertible.REF_KEY)
+      if ref_index is None:
+        for k, x in serialized.items():
+          serialized[k] = self._maybe_deref(x, ref_index_map)
+      else:
+        shared = self.get_shared(ref_index)
+        if shared.ref_count == 1:
+          ref_serialized = self._maybe_deref(shared.serialized, ref_index_map)
+          if isinstance(ref_serialized, dict):
+            serialized.pop(JSONConvertible.REF_KEY)
+            serialized.update(ref_serialized)
+            return serialized
+          return ref_serialized
+        else:
+          serialized[JSONConvertible.REF_KEY] = ref_index_map[shared.ref_index]
+    elif isinstance(serialized, list):
+      for i, x in enumerate(serialized):
+        serialized[i] = self._maybe_deref(x, ref_index_map)
+    return serialized
+
+  def to_json(self, *, root: Any, **kwargs) -> JSONValueType:
+    """Serializes a root node with the context to JSON value."""
+    # `ref_index_map` stores the original index of shared objects to their
+    # indices after the ref-1 shared objects are trimmed.
+    ref_index_map = {}
+
+    shared_objects = []
+    for i, v in enumerate(self._shared_objects):
+      ref_index_map[i] = len(shared_objects)
+      if v.ref_count != 1:
+        shared_objects.append(v.value)
+
+    root = self._maybe_deref(root, ref_index_map)
+
+    serialized_shared_objects = [
+        v.serialized for v in self._shared_objects if v.ref_count != 1
+    ]
+    if not shared_objects:
+      return root
+    serialized = {}
+    if shared_objects:
+      serialized[JSONConvertible.CONTEXT_KEY] = {
+          'shared_objects': [
+              self._maybe_deref(x, ref_index_map)
+              for x in serialized_shared_objects
+          ],
+      }
+    serialized[JSONConvertible.ROOT_VALUE_KEY] = root
+    return serialized
+
+  @classmethod
+  def from_json(
+      cls, json_value: JSONValueType, **kwargs
+  ) -> 'JSONConversionContext':
+    """Deserializes a JSONConvertible value from JSON value."""
+    context = cls()
+    if isinstance(json_value, dict):
+      # Shared objects are serialized in a bottom-up order, thus dependent
+      # shared objects must be deserialized first.
+      if shared_objects_json := json_value.get('shared_objects'):
+        for v in shared_objects_json:
+          context.add_shared(
+              cls.ObjectEntry(
+                  value=from_json(v, context=context, **kwargs),
+                  serialized=v,
+                  ref_index=context.next_shared_index(),
+                  ref_count=0,
+              )
+          )
+    return context
+
+
+def to_json(
+    value: Any,
+    *,
+    context: Optional[JSONConversionContext] = None,
+    **kwargs
+) -> Any:
   """Serializes a (maybe) JSONConvertible value into a plain Python object.
 
   Args:
@@ -413,22 +602,50 @@ def to_json(value: Any, **kwargs) -> Any:
       * Tuple types;
       * Dict types.
 
+    context: JSON conversion context.
     **kwargs: Keyword arguments to pass to value.to_json if value is
       JSONConvertible.
 
   Returns:
     JSON value.
   """
+  if context is None:
+    is_root = True
+    context = JSONConversionContext()
+  else:
+    is_root = False
+
   if isinstance(value, (type(None), bool, int, float, str)):
+    # Primitive types serialize by values.
     v = value
   elif isinstance(value, JSONConvertible):
-    v = value.to_json(**kwargs)
-  elif isinstance(value, tuple):
-    v = [JSONConvertible.TUPLE_MARKER] + to_json(list(value), **kwargs)
+    # Non-symbolic objects serialize by references.
+    v = context.serialize_maybe_shared(
+        value,
+        json_fn=getattr(value, 'sym_jsonify', value.to_json),
+        **kwargs
+    )
   elif isinstance(value, list):
-    v = [to_json(item, **kwargs) for item in value]
+    # Standard lists serialize by references.
+    v = context.serialize_maybe_shared(
+        value,
+        json_fn=lambda **kwargs: [to_json(x, **kwargs) for x in value],
+        **kwargs
+    )
   elif isinstance(value, dict):
-    v = {k: to_json(v, **kwargs) for k, v in value.items()}
+    # Standard dicts serialize by references.
+    v = context.serialize_maybe_shared(
+        value,
+        json_fn=lambda **kwargs: {
+            k: to_json(v, **kwargs) for k, v in value.items()   # pytype: disable=attribute-error
+        },
+        **kwargs
+    )
+  elif isinstance(value, tuple):
+    # Tuples serialize by values.
+    v = [JSONConvertible.TUPLE_MARKER] + [
+        to_json(item, context=context, **kwargs) for item in value
+    ]
   elif isinstance(value, (type, typing.GenericAlias)):  # pytype: disable=module-attr
     v = _type_to_json(value)
   elif inspect.isbuiltin(value):
@@ -448,23 +665,34 @@ def to_json(value: Any, **kwargs) -> Any:
     if JSONConvertible.TYPE_CONVERTER is not None:
       converter = JSONConvertible.TYPE_CONVERTER(type(value))   # pylint: disable=not-callable
       if converter:
-        v = to_json(converter(value))
+        v = to_json(converter(value), context=context, **kwargs)
         converted = True
     if not converted:
-      v = _OpaqueObject(value).to_json(**kwargs)
+      # Opaque objects serialize by references.
+      v = context.serialize_maybe_shared(
+          value,
+          json_fn=lambda **kwargs: _OpaqueObject(value).to_json(**kwargs),
+          **kwargs
+      )
+
+  if is_root:
+    return context.to_json(root=v, **kwargs)
   return v
 
 
 def from_json(
     json_value: JSONValueType,
     *,
+    context: Optional[JSONConversionContext] = None,
     auto_import: bool = True,
     auto_dict: bool = False,
-    **kwargs) -> Any:
+    **kwargs
+) -> Any:
   """Deserializes a (maybe) JSONConvertible value from JSON value.
 
   Args:
     json_value: Input JSON value.
+    context: Serialization context.
     auto_import: If True, when a '_type' is not registered, PyGlove will
       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
@@ -476,12 +704,20 @@ def from_json(
   Returns:
     Deserialized value.
   """
+  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)
+      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)
 
   def child_from(v):
-    return from_json(v, _typename_resolved=True, **kwargs)
+    return from_json(v, context=context, _typename_resolved=True, **kwargs)
 
   if isinstance(json_value, list):
     if json_value and json_value[0] == JSONConvertible.TUPLE_MARKER:
@@ -493,18 +729,21 @@ def from_json(
       return tuple([child_from(v) for v in json_value[1:]])
     return [child_from(v) for v in json_value]
   elif isinstance(json_value, dict):
+    if JSONConvertible.REF_KEY in json_value:
+      v = context.get_shared(json_value[JSONConvertible.REF_KEY]).value
+      return v
     if JSONConvertible.TYPE_NAME_KEY not in json_value:
       return {k: child_from(v) for k, v in json_value.items()}
     factory_fn = json_value.pop(JSONConvertible.TYPE_NAME_KEY)
     assert factory_fn is not None
-    return factory_fn(json_value, **kwargs)
+    return factory_fn(json_value, context=context, **kwargs)
   return json_value
 
 
 def resolve_typenames(
     json_value: JSONValueType,
     auto_import: bool = True,
-    auto_dict: bool = False
+    auto_dict: bool = False,
 ) -> JSONValueType:
   """Inplace resolves the "_type" keys with their factories in a JSON tree."""
 

pyglove/core/utils/json_conversion_test.py

@@ -156,7 +156,7 @@ class JSONConvertibleTest(unittest.TestCase):
       def __init__(self, x=None):
         self.x = x
 
-      def to_json(self):
+      def to_json(self, **kwargs):
         return T.to_json_dict(dict(x=(self.x, None)), exclude_default=True)
 
       def __eq__(self, other):
@@ -202,7 +202,7 @@ class JSONConvertibleTest(unittest.TestCase):
     def __init__(self, x=None):
       self.x = x
 
-    def to_json(self):
+    def to_json(self, **kwargs):
       return self.to_json_dict(
           dict(x=(self.x, None)), exclude_default=True
       )
@@ -215,7 +215,6 @@ class JSONConvertibleTest(unittest.TestCase):
 
   def test_json_conversion_with_auto_import(self):
     json_dict = json_conversion.to_json(self.CustomJsonConvertible(1))
-
     with self.assertRaisesRegex(
         TypeError, 'Type name .* is not registered'):
       json_conversion.from_json(json_dict, auto_import=False)
@@ -393,6 +392,65 @@ class JSONConvertibleTest(unittest.TestCase):
         TypeError, '.* is not a `pg.JSONConvertible` subclass'):
       json_conversion.from_json({'_type': '__main__.A'})
 
+  def test_json_conversion_with_sharing(self):
+
+    class T(json_conversion.JSONConvertible):
+
+      def __init__(self, x=None):
+        self.x = x
+
+      def to_json(self, **kwargs):
+        return T.to_json_dict(dict(x=(self.x, None)), exclude_default=True)
+
+    t = T(1)
+    x = X(1)
+    u = {'x': x}
+    v = [u, t]
+    y = dict(t=t, x=x, u=u, v=v)
+    y_json = json_conversion.to_json(y)
+    x_serialized = json_conversion._OpaqueObject(x).to_json()
+    self.assertEqual(
+        y_json,
+        {
+            '__context__': {
+                'shared_objects': [
+                    {
+                        '_type': json_conversion._type_name(T),
+                        'x': 1
+                    },
+                    x_serialized,
+                    {
+                        'x': {
+                            '__ref__': 1
+                        }
+                    }
+                ]
+            },
+            '__root__': {
+                't': {
+                    '__ref__': 0
+                },
+                'x': {
+                    '__ref__': 1
+                },
+                'u': {
+                    '__ref__': 2
+                },
+                'v': [
+                    {
+                        '__ref__': 2
+                    },
+                    {
+                        '__ref__': 0
+                    }
+                ]
+            }
+        }
+    )
+    y_prime = json_conversion.from_json(y_json)
+    self.assertIs(y_prime['t'], y_prime['v'][1])
+    self.assertIs(y_prime['u'], y_prime['v'][0])
+
 
 if __name__ == '__main__':
   unittest.main()

{pyglove-0.5.0.dev202510210811.dist-info → pyglove-0.5.0.dev202510230131.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyglove
-Version: 0.5.0.dev202510210811
+Version: 0.5.0.dev202510230131
 Summary: PyGlove: A library for manipulating Python objects.
 Home-page: https://github.com/google/pyglove
 Author: PyGlove Authors

{pyglove-0.5.0.dev202510210811.dist-info → pyglove-0.5.0.dev202510230131.dist-info}/RECORD

@@ -19,7 +19,7 @@ pyglove/core/detouring/__init__.py,sha256=ck_n2VSuU31HNVYQkbG4Zvnx90mNYtSVc2StN3
 pyglove/core/detouring/class_detour.py,sha256=ejuUr7UfRU3l9PrDxD0dpKmt2iqdDU6liHdebA1jEfQ,13312
 pyglove/core/detouring/class_detour_test.py,sha256=9aAK6qPiT0_HJe5oUpqMVTpoHv0wr_h6c4gWYKMTJoM,5507
 pyglove/core/geno/__init__.py,sha256=cWA583n7JpsGUkGtoTlMMX83tNS7geRBKFsoPEvFZ4A,4767
-pyglove/core/geno/base.py,sha256=4CjZ1j-LGd6q2qootGcLMVuX8nTDxH0LvA1KVSI9qbE,64498
+pyglove/core/geno/base.py,sha256=fZaTmmCJaiIm2ACU8EgEUHQLr9iF0f6yBNdYWIwYKWg,64639
 pyglove/core/geno/base_test.py,sha256=f0pMpfXsjAqFOBtlOxof3jRX0jLvXpzowk9szcr6bgY,38512
 pyglove/core/geno/categorical.py,sha256=t1bS129D5iF4CZ0yVHaFDXy2T6ujv5F5HHDc_0X36z8,28015
 pyglove/core/geno/categorical_test.py,sha256=23UkOPhDSvonxxM_1YoBYp723Xim-BmBzywl612CRyg,18444
@@ -68,8 +68,8 @@ pyglove/core/patching/pattern_based_test.py,sha256=PW1EcVfsFPB6wtgwg3s4dzvigWn3b
 pyglove/core/patching/rule_based.py,sha256=JAQp8mWeIOxwIdqusA3GmXia-fxQhQsxbUTmE329wF8,17038
 pyglove/core/patching/rule_based_test.py,sha256=qfy0ILmczV_LMHWEnwo2y079OrJsGYO0nKxSZdmIUcI,18782
 pyglove/core/symbolic/__init__.py,sha256=VMQj8oW2hGaJwqgchBJbu5qXoJKaNizxv__vsYL4b7U,6057
-pyglove/core/symbolic/base.py,sha256=l344Ajup-nYk3Rmn0E9VsuWTtMSVgnI58YiCqNx-N5M,77802
-pyglove/core/symbolic/base_test.py,sha256=yASIHIuWiUB1jf4nN-Y4XOjyvr8eQfRpr7s_1LZsu78,7188
+pyglove/core/symbolic/base.py,sha256=aRo-v1w1kGHPhJNddaGA-SZMeLSQs4dNyRPEjHH4Phg,79102
+pyglove/core/symbolic/base_test.py,sha256=OHEexXI7uE2bixT-trfR3j-dfiAJsbY7pFyAA6XEPqA,7338
 pyglove/core/symbolic/boilerplate.py,sha256=sQ3G25r5bo_UmIdjreL4jkAuQCXIHVlvUfGjjkNod6Y,5955
 pyglove/core/symbolic/boilerplate_test.py,sha256=1CZ1W6kq3l-3tpaknhGFa04V18bO7vPzis5qzWnxHEs,5252
 pyglove/core/symbolic/class_wrapper.py,sha256=xQiMh5vFlOQ76tbqsF5UWEghvU4d9UmvbNqIyBccNHg,22869
@@ -78,8 +78,8 @@ pyglove/core/symbolic/compounding.py,sha256=gvOodZ2gWHA0jNdwt8yvnRsPkHQDXDb5s88U
 pyglove/core/symbolic/compounding_test.py,sha256=hOzrIROvajUTtPm0SUbEsEV4C1bXanhAoHinHrjZoXw,8320
 pyglove/core/symbolic/contextual_object.py,sha256=ar9Q_0P0HHbDf8kLHpS8GFZEMCRuCCB6DP18iGItiiw,9146
 pyglove/core/symbolic/contextual_object_test.py,sha256=wA5xfIhEHOC9qE3bbiA59CAPxWs9AVPaNiKEoprkWpQ,10209
-pyglove/core/symbolic/dict.py,sha256=mgukJUvw1FxdozoRzUzMnqsIm_WZZae-rTskh9pzLWk,37284
-pyglove/core/symbolic/dict_test.py,sha256=sRTpdb1xWAOl87GoUn8GIh-oRhMlrj_EmJ7hkLZCH4Y,73593
+pyglove/core/symbolic/dict.py,sha256=ELM-5XSxChNZNTaDxRDm_rCpMkuJ2nBASMOMxVjB07g,37657
+pyglove/core/symbolic/dict_test.py,sha256=XPOe5DV_opYMkzSJZEl7rTvBBN-H9NvKe8zC7tQf7EE,74429
 pyglove/core/symbolic/diff.py,sha256=zHfED0Bbq8G_HWNPj3vrOCWzt_062rFhx3BMlpCb9oo,16282
 pyglove/core/symbolic/diff_test.py,sha256=EDiGHqqKhi-NeMxr-bgjBEqlquee_4l_0IM6hgAb9Mg,29400
 pyglove/core/symbolic/error_info.py,sha256=rqRwfmnEibMixaS2G-P0VhKjkZl79qjO6EUItnATHlQ,3675
@@ -90,15 +90,15 @@ pyglove/core/symbolic/functor.py,sha256=AwE9GX2cO3QNihac1_ZN0sdG-TrWAJ5lXO2ZQ5Gs
 pyglove/core/symbolic/functor_test.py,sha256=9c5_7OBKNVNbYC7IaVQB6c5ks2v00qQ36oivyWiBbKA,31798
 pyglove/core/symbolic/inferred.py,sha256=E4zgphg6NNZad9Fl3jdHQOMZeqEp9XHq5OUYqXEmwZQ,3178
 pyglove/core/symbolic/inferred_test.py,sha256=G6uPykONcChvs6vZujXHSWaYfjewLTVBscMqzzKNty0,1270
-pyglove/core/symbolic/list.py,sha256=z8goU0ntd-Q5ADaCGiKsJwPhdRdQb0Kd_p-ZekXaLy4,30303
-pyglove/core/symbolic/list_test.py,sha256=IAyFQ48nyczKUcPNZFKHBkX5oh7Xuxbnv3rRkONhbHw,61146
-pyglove/core/symbolic/object.py,sha256=OZ6eK8qyaLsUKxFiV2GWL5Ol6FDzMrrkpWSRKRwIKAA,42726
+pyglove/core/symbolic/list.py,sha256=CRDoBxYJsmNly1MxhY5vO0wp6EUTnxze6-2O9vXHna4,30717
+pyglove/core/symbolic/list_test.py,sha256=Q3kqQ6aaQ40Nw6osSxrGk4N_E1lGZyvwdvxZgLRwMS0,61954
+pyglove/core/symbolic/object.py,sha256=UgDgKdcYDYX3J51EMQamdwaXHkG4SHPunAGkSuHuTa0,42768
 pyglove/core/symbolic/object_test.py,sha256=rDP7lcQZTFdQCqeaNYs7ZfwvGanzHz7CHM33NCmRIFk,94391
 pyglove/core/symbolic/origin.py,sha256=OSWMKjvPcISOXrzuX3lCQC8m_qaGl-9INsIB81erUnU,6124
 pyglove/core/symbolic/origin_test.py,sha256=dU_ZGrGDetM_lYVMn3wQO0d367_t_t8eESe3NrKPBNE,3159
 pyglove/core/symbolic/pure_symbolic.py,sha256=pvo15gn35_KLiGW_XrTjlx5ddmHbwpLr93VgbQ59uQ8,3231
-pyglove/core/symbolic/ref.py,sha256=qRN-0xm9pWlszel5qE-HAhQCkgB0umi_pDlzDhBWPUA,8513
-pyglove/core/symbolic/ref_test.py,sha256=0687hClfR5G5_VKuRlwjJGVQ2MC74ADFWklDaZ3aEVI,6294
+pyglove/core/symbolic/ref.py,sha256=gIu02b8BfKspH1XejXhEFh_Iil3jvfGHdpaCRq6qor0,8817
+pyglove/core/symbolic/ref_test.py,sha256=-rCA1AaLZnyuKOh0cJzS5UaQ_9Kp4p7xexZ_e3IwpOg,8974
 pyglove/core/symbolic/symbolize.py,sha256=ohID9-V8QiFe7OMpPlRomiqUnKBVMpypd8ZuMuHaa4s,6582
 pyglove/core/symbolic/symbolize_test.py,sha256=o7bRfMhGc6uw2FIH8arE99-bPb3i0YixcHYyiP-QqeQ,6487
 pyglove/core/tuning/__init__.py,sha256=JtXpjsBto01fLf55hZ1dSx-CEZUyVQeyRP9AMH_hw8c,2229
@@ -113,8 +113,8 @@ pyglove/core/tuning/sample_test.py,sha256=JqwDPy3EPC_VjU9dipk90jj1kovZB3Zb9hAjAl
 pyglove/core/typing/__init__.py,sha256=u2YSrSi8diTkQn8_1J2hEpk5o7zDhx2tU_oRuS-k1XU,14580
 pyglove/core/typing/annotated.py,sha256=llaajIDj9GK-4kUGJoO4JsHU6ESPOra2SZ-jG6xmsOQ,3203
 pyglove/core/typing/annotated_test.py,sha256=p1qid3R-jeiOTTxOVq6hXW8XFvn-h1cUzJWISPst2l8,2484
-pyglove/core/typing/annotation_conversion.py,sha256=txUrChAhMNeaukV-PSQEA9BCjtonUQDWFHxnpTE0_K8,15582
-pyglove/core/typing/annotation_conversion_test.py,sha256=GW7e3e00jcYJjJGRvCvMtW4QBHyVwFtZVcETdh1yBS8,17540
+pyglove/core/typing/annotation_conversion.py,sha256=hi4LcRXwYzspHAKZ0rtXlq2dQyAmo9GXrm_HCJAGl34,15657
+pyglove/core/typing/annotation_conversion_test.py,sha256=g66iyt3ti_pskIXndk4DiKgO8j8aMYOe2nPKXszlXmw,17675
 pyglove/core/typing/annotation_future_test.py,sha256=tAVuzWNfW8R4e4l7fx88Q4nJDM2LPUogNKNAIIPAEWQ,3959
 pyglove/core/typing/callable_ext.py,sha256=PiBQWPeUAH7Lgmf2xKCZqgK7N0OSrTdbnEkV8Ph31OA,9127
 pyglove/core/typing/callable_ext_test.py,sha256=TnWKU4_ZjvpbHZFtFHgFvCMDiCos8VmLlODcM_7Xg8M,10156
@@ -136,7 +136,7 @@ pyglove/core/typing/typed_missing.py,sha256=-l1omAu0jBZv5BnsFYXBqfvQwVBnmPh_X1wc
 pyglove/core/typing/typed_missing_test.py,sha256=TCNsb1SRpFaVdxYn2mB_yaLuja8w5Qn5NP7uGiZVBWs,2301
 pyglove/core/typing/value_specs.py,sha256=8E83QDZMb3lMXhgzfVNt9u6Bg3NPkvpjLXetjkps8UU,103263
 pyglove/core/typing/value_specs_test.py,sha256=eGXVxdduIM-oEaapJS9Kh7WSQHRUFegLIJ1GEzQkKHA,131017
-pyglove/core/utils/__init__.py,sha256=2aw4n1kYG9xlX2tWI-H5i25cBuK1ME9Lmf-F31VlKEk,8657
+pyglove/core/utils/__init__.py,sha256=6P2VcGkjDsOFG640Jqu-jd1K3pfAK5NkcK3NBPLI6RY,8726
 pyglove/core/utils/common_traits.py,sha256=PWxOgPhG5H60ZwfO8xNAEGRjFUqqDZQBWQYomOfvdy8,3640
 pyglove/core/utils/common_traits_test.py,sha256=DIuZB_1xfmeTVfWnGOguDQcDAM_iGgBOe8C-5CsIqBc,1122
 pyglove/core/utils/contextual.py,sha256=_EO_ubCcmI81QyYyyucm3QcH1asQWSeXvT2Xa4KONs8,5355
@@ -149,8 +149,8 @@ pyglove/core/utils/formatting.py,sha256=Wn4d933LQLhuMIfjdRJgpxOThCxBxQrkRBa6Z1-h
 pyglove/core/utils/formatting_test.py,sha256=hhg-nL6DyE5A2QA92ALHK5QtfAYKfPpTbBARF-IT1j0,14241
 pyglove/core/utils/hierarchical.py,sha256=jwB-0FhqOspAymAkvJphRhPTQEsoShmKupCZpU3Vip4,19690
 pyglove/core/utils/hierarchical_test.py,sha256=f382DMJPa_bavJGGQDjuw-hWcafUg5bkQCPX-nbzeiI,21077
-pyglove/core/utils/json_conversion.py,sha256=O0Wz94WE3UkjQLFYqiuF3Zw9Q9vfMAaBPF2soREOaYs,26811
-pyglove/core/utils/json_conversion_test.py,sha256=zA_cy7ixVL3sTf6i9BCXMlSH56Aa3JnjHnjyqYJ_9XU,11845
+pyglove/core/utils/json_conversion.py,sha256=V7wUviGKhEPWi1gtCGSDXXvBzV6cO7CvmEiGDZ2jWFY,34643
+pyglove/core/utils/json_conversion_test.py,sha256=6afuPJxBXIO-OxFzJBkv1MZqNX-44HIBD6YJjwxXSbs,13412
 pyglove/core/utils/missing.py,sha256=9gslt1lXd1qSEIuAFxUWu30oD-YdYcnm13eau1S9uqY,1445
 pyglove/core/utils/missing_test.py,sha256=D6-FuVEwCyJemUiPLcwLmwyptqI5Bx0Pfipc2juhKSE,1335
 pyglove/core/utils/text_color.py,sha256=xcCTCxY2qFNZs_jismMGus8scEXKBpYGAhpAgnz-MHk,4112
@@ -218,8 +218,8 @@ pyglove/ext/scalars/randoms.py,sha256=LkMIIx7lOq_lvJvVS3BrgWGuWl7Pi91-lA-O8x_gZs
 pyglove/ext/scalars/randoms_test.py,sha256=nEhiqarg8l_5EOucp59CYrpO2uKxS1pe0hmBdZUzRNM,2000
 pyglove/ext/scalars/step_wise.py,sha256=IDw3tuTpv0KVh7AN44W43zqm1-E0HWPUlytWOQC9w3Y,3789
 pyglove/ext/scalars/step_wise_test.py,sha256=TL1vJ19xVx2t5HKuyIzGoogF7N3Rm8YhLE6JF7i0iy8,2540
-pyglove-0.5.0.dev202510210811.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
-pyglove-0.5.0.dev202510210811.dist-info/METADATA,sha256=1cC3lbVDOKKDqji7Tb-7xvdmyYqzV4vAOfVp_I5_jos,7089
-pyglove-0.5.0.dev202510210811.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pyglove-0.5.0.dev202510210811.dist-info/top_level.txt,sha256=wITzJSKcj8GZUkbq-MvUQnFadkiuAv_qv5qQMw0fIow,8
-pyglove-0.5.0.dev202510210811.dist-info/RECORD,,
+pyglove-0.5.0.dev202510230131.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+pyglove-0.5.0.dev202510230131.dist-info/METADATA,sha256=ym-feRv6WNcWJcHwyu0hlpledVeQZznTxZpGyI62kog,7089
+pyglove-0.5.0.dev202510230131.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyglove-0.5.0.dev202510230131.dist-info/top_level.txt,sha256=wITzJSKcj8GZUkbq-MvUQnFadkiuAv_qv5qQMw0fIow,8
+pyglove-0.5.0.dev202510230131.dist-info/RECORD,,