pyglove 0.4.5.dev202412100720__py3-none-any.whl → 0.4.5.dev202501250807__py3-none-any.whl

pyglove/core/symbolic/functor.py

@@ -22,14 +22,14 @@ import types
 import typing
 from typing import Any, Callable, Dict, List, Optional, Set, Tuple, Type, Union
 
-from pyglove.core import object_utils
 from pyglove.core import typing as pg_typing
+from pyglove.core import utils
 from pyglove.core.symbolic import base
 from pyglove.core.symbolic import flags
 from pyglove.core.symbolic import object as pg_object
 
 
-class Functor(pg_object.Object, object_utils.Functor):
+class Functor(pg_object.Object, utils.Functor):
   """Symbolic functions (Functors).
 
   A symbolic function is a symbolic class with a ``__call__`` method, whose
@@ -124,7 +124,7 @@ class Functor(pg_object.Object, object_utils.Functor):
     if not hasattr(cls, '__orig_init__'):
       setattr(cls, '__orig_init__', cls.__init__)
 
-    @object_utils.explicit_method_override
+    @utils.explicit_method_override
     @functools.wraps(pseudo_init)
     def _init(self, *args, **kwargs):
       self.__class__.__orig_init__(self, *args, **kwargs)
@@ -148,14 +148,15 @@ class Functor(pg_object.Object, object_utils.Functor):
       return instance()
     return instance
 
-  @object_utils.explicit_method_override
+  @utils.explicit_method_override
   def __init__(
       self,
       *args,
-      root_path: Optional[object_utils.KeyPath] = None,
+      root_path: Optional[utils.KeyPath] = None,
       override_args: bool = False,
       ignore_extra_args: bool = False,
-      **kwargs):
+      **kwargs,
+  ):
     """Constructor.
 
     Args:
@@ -182,8 +183,8 @@ class Functor(pg_object.Object, object_utils.Functor):
         varargs = list(args[len(signature.args) :])
         args = args[: len(signature.args)]
       else:
-        arg_phrase = object_utils.auto_plural(len(signature.args), 'argument')
-        was_phrase = object_utils.auto_plural(len(args), 'was', 'were')
+        arg_phrase = utils.auto_plural(len(signature.args), 'argument')
+        was_phrase = utils.auto_plural(len(args), 'was', 'were')
         raise TypeError(
             f'{signature.id}() takes {len(signature.args)} '
             f'positional {arg_phrase} but {len(args)} {was_phrase} given.'
@@ -257,8 +258,7 @@ class Functor(pg_object.Object, object_utils.Functor):
     # pylint: enable=protected-access
     return typing.cast(Functor, other)
 
-  def _on_change(
-      self, field_updates: Dict[object_utils.KeyPath, base.FieldUpdate]):
+  def _on_change(self, field_updates: Dict[utils.KeyPath, base.FieldUpdate]):
     """Custom handling field change to update bound args."""
     for relative_path, update in field_updates.items():
       assert relative_path
@@ -406,8 +406,8 @@ class Functor(pg_object.Object, object_utils.Functor):
       if ignore_extra_args:
         args = args[: len(signature.args)]
       else:
-        arg_phrase = object_utils.auto_plural(len(signature.args), 'argument')
-        was_phrase = object_utils.auto_plural(len(args), 'was', 'were')
+        arg_phrase = utils.auto_plural(len(signature.args), 'argument')
+        was_phrase = utils.auto_plural(len(args), 'was', 'were')
         raise TypeError(
             f'{signature.id}() takes {len(signature.args)} '
             f'positional {arg_phrase} but {len(args)} {was_phrase} given.'
@@ -483,9 +483,10 @@ class Functor(pg_object.Object, object_utils.Functor):
         missing_required_arg_names.append(arg.name)
 
     if missing_required_arg_names:
-      arg_phrase = object_utils.auto_plural(
-          len(missing_required_arg_names), 'argument')
-      args_str = object_utils.comma_delimited_str(missing_required_arg_names)
+      arg_phrase = utils.auto_plural(
+          len(missing_required_arg_names), 'argument'
+      )
+      args_str = utils.comma_delimited_str(missing_required_arg_names)
       raise TypeError(
           f'{signature.id}() missing {len(missing_required_arg_names)} '
           f'required positional {arg_phrase}: {args_str}.'

pyglove/core/symbolic/functor_test.py

@@ -11,15 +11,13 @@
 # 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.
-"""Tests for pyglove.Functor."""
-
 import inspect
 import io
 import typing
 import unittest
 
-from pyglove.core import object_utils
 from pyglove.core import typing as pg_typing
+from pyglove.core import utils
 from pyglove.core.symbolic import flags
 from pyglove.core.symbolic.base import from_json_str as pg_from_json_str
 from pyglove.core.symbolic.dict import Dict
@@ -31,7 +29,7 @@ from pyglove.core.symbolic.object import members as pg_members
 from pyglove.core.symbolic.object import Object
 
 
-MISSING_VALUE = object_utils.MISSING_VALUE
+MISSING_VALUE = utils.MISSING_VALUE
 
 
 class FunctorTest(unittest.TestCase):

pyglove/core/symbolic/inferred.py

@@ -14,8 +14,8 @@
 """Common inferential values."""
 
 from typing import Any, Tuple
-from pyglove.core import object_utils
 from pyglove.core import typing as pg_typing
+from pyglove.core import utils
 from pyglove.core.symbolic import base
 from pyglove.core.symbolic.object import Object
 
@@ -65,7 +65,7 @@ class ValueFromParentChain(InferredValue):
       if v == pg_typing.MISSING_VALUE:
         if parent is None:
           raise AttributeError(
-              object_utils.message_on_path(
+              utils.message_on_path(
                   (
                       f'`{self.inference_key}` is not found under its context '
                       '(along its symbolic parent chain).'

pyglove/core/symbolic/list.py

@@ -18,8 +18,8 @@ import math
 import numbers
 import typing
 from typing import Any, Callable, Dict, Iterable, Iterator, Optional, Tuple, Union
-from pyglove.core import object_utils
 from pyglove.core import typing as pg_typing
+from pyglove.core import utils
 from pyglove.core.symbolic import base
 from pyglove.core.symbolic import flags
 
@@ -74,13 +74,16 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
   """
 
   @classmethod
-  def partial(cls,
-              items: Optional[Iterable[Any]] = None,
-              *,
-              value_spec: Optional[pg_typing.List] = None,
-              onchange_callback: Optional[Callable[
-                  [Dict[object_utils.KeyPath, base.FieldUpdate]], None]] = None,
-              **kwargs) -> 'List':
+  def partial(
+      cls,
+      items: Optional[Iterable[Any]] = None,
+      *,
+      value_spec: Optional[pg_typing.List] = None,
+      onchange_callback: Optional[
+          Callable[[Dict[utils.KeyPath, base.FieldUpdate]], None]
+      ] = None,
+      **kwargs,
+  ) -> 'List':
     """Class method that creates a partial List object."""
     return cls(items,
                value_spec=value_spec,
@@ -89,13 +92,15 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
                **kwargs)
 
   @classmethod
-  def from_json(cls,
-                json_value: Any,
-                *,
-                value_spec: Optional[pg_typing.List] = None,
-                allow_partial: bool = False,
-                root_path: Optional[object_utils.KeyPath] = None,
-                **kwargs) -> 'List':
+  def from_json(
+      cls,
+      json_value: Any,
+      *,
+      value_spec: Optional[pg_typing.List] = None,
+      allow_partial: bool = False,
+      root_path: Optional[utils.KeyPath] = None,
+      **kwargs,
+  ) -> 'List':
     """Class method that load an symbolic List from a JSON value.
 
     Example::
@@ -136,10 +141,11 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
         [
             base.from_json(
                 v,
-                root_path=object_utils.KeyPath(i, root_path),
+                root_path=utils.KeyPath(i, root_path),
                 allow_partial=allow_partial,
-                **kwargs
-            ) for i, v in enumerate(json_value)
+                **kwargs,
+            )
+            for i, v in enumerate(json_value)
         ],
         value_spec=value_spec,
         root_path=root_path,
@@ -151,12 +157,14 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
       items: Optional[Iterable[Any]] = None,
       *,
       value_spec: Optional[pg_typing.List] = None,
-      onchange_callback: Optional[Callable[
-          [Dict[object_utils.KeyPath, base.FieldUpdate]], None]] = None,
+      onchange_callback: Optional[
+          Callable[[Dict[utils.KeyPath, base.FieldUpdate]], None]
+      ] = None,
       allow_partial: bool = False,
       accessor_writable: bool = True,
       sealed: bool = False,
-      root_path: Optional[object_utils.KeyPath] = None):
+      root_path: Optional[utils.KeyPath] = None,
+  ):
     """Constructor.
 
     Args:
@@ -337,8 +345,8 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
     return missing
 
   def _sym_rebind(
-      self, path_value_pairs: typing.Dict[object_utils.KeyPath, Any]
-      ) -> typing.List[base.FieldUpdate]:
+      self, path_value_pairs: typing.Dict[utils.KeyPath, Any]
+  ) -> typing.List[base.FieldUpdate]:
     """Subclass specific rebind implementation."""
     updates = []
 
@@ -378,14 +386,13 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
     return self
 
   def _update_children_paths(
-      self,
-      old_path: object_utils.KeyPath,
-      new_path: object_utils.KeyPath) -> None:
+      self, old_path: utils.KeyPath, new_path: utils.KeyPath
+  ) -> None:
     """Update children paths according to root_path of current node."""
     del old_path
     for idx, item in self.sym_items():
       if isinstance(item, base.TopologyAware):
-        item.sym_setpath(object_utils.KeyPath(idx, new_path))
+        item.sym_setpath(utils.KeyPath(idx, new_path))
 
   def _set_item_without_permission_check(  # pytype: disable=signature-mismatch  # overriding-parameter-type-checks
       self, key: int, value: Any) -> Optional[base.FieldUpdate]:
@@ -432,13 +439,15 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
     value = base.from_json(
         value,
         allow_partial=allow_partial,
-        root_path=object_utils.KeyPath(idx, self.sym_path))
+        root_path=utils.KeyPath(idx, self.sym_path),
+    )
     if self._value_spec and flags.is_type_check_enabled():
       value = self._value_spec.element.apply(
           value,
           allow_partial=allow_partial,
           transform_fn=base.symbolic_transform_fn(self._allow_partial),
-          root_path=object_utils.KeyPath(idx, self.sym_path))
+          root_path=utils.KeyPath(idx, self.sym_path),
+      )
     return self._relocate_if_symbolic(idx, value)
 
   @property
@@ -446,8 +455,7 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
     """Returns True if current list subscribes field updates."""
     return self._onchange_callback is not None
 
-  def _on_change(self,
-                 field_updates: Dict[object_utils.KeyPath, base.FieldUpdate]):
+  def _on_change(self, field_updates: Dict[utils.KeyPath, base.FieldUpdate]):
     """On change event of List."""
     # Do nothing for now to handle changes of List.
 
@@ -463,7 +471,7 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
     # Update paths for children.
     for idx, item in self.sym_items():
       if isinstance(item, base.TopologyAware) and item.sym_path.key != idx:
-        item.sym_setpath(object_utils.KeyPath(idx, self.sym_path))
+        item.sym_setpath(utils.KeyPath(idx, self.sym_path))
 
     if self._onchange_callback is not None:
       self._onchange_callback(field_updates)
@@ -723,11 +731,12 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
 
   def custom_apply(
       self,
-      path: object_utils.KeyPath,
+      path: utils.KeyPath,
       value_spec: pg_typing.ValueSpec,
       allow_partial: bool,
       child_transform: Optional[
-          Callable[[object_utils.KeyPath, pg_typing.Field, Any], Any]] = None
+          Callable[[utils.KeyPath, pg_typing.Field, Any], Any]
+      ] = None,
   ) -> Tuple[bool, 'List']:
     """Implement pg.typing.CustomTyping interface.
 
@@ -746,9 +755,12 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
     if self._value_spec:
       if value_spec and not value_spec.is_compatible(self._value_spec):
         raise ValueError(
-            object_utils.message_on_path(
+            utils.message_on_path(
                 f'List (spec={self._value_spec!r}) cannot be assigned to an '
-                f'incompatible field (spec={value_spec!r}).', path))
+                f'incompatible field (spec={value_spec!r}).',
+                path,
+            )
+        )
       if self._allow_partial == allow_partial:
         proceed_with_standard_apply = False
       else:
@@ -758,9 +770,8 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
     return (proceed_with_standard_apply, self)
 
   def sym_jsonify(
-      self,
-      use_inferred: bool = False,
-      **kwargs) -> object_utils.JSONValueType:
+      self, use_inferred: bool = False, **kwargs
+  ) -> utils.JSONValueType:
     """Converts current list to a list of plain Python objects."""
     def json_item(idx):
       v = self.sym_getattr(idx)
@@ -778,7 +789,7 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
       python_format: bool = False,
       use_inferred: bool = False,
       cls_name: Optional[str] = None,
-      bracket_type: object_utils.BracketType = object_utils.BracketType.SQUARE,
+      bracket_type: utils.BracketType = utils.BracketType.SQUARE,
       **kwargs,
   ) -> str:
     """Formats this List."""
@@ -787,16 +798,22 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
       return ' ' * 2 * indent + text
 
     cls_name = cls_name or ''
-    open_bracket, close_bracket = object_utils.bracket_chars(bracket_type)
+    open_bracket, close_bracket = utils.bracket_chars(bracket_type)
     s = [f'{cls_name}{open_bracket}']
     if compact:
       kv_strs = []
       for idx, elem in self.sym_items():
         if use_inferred and isinstance(elem, base.Inferential):
           elem = self.sym_inferred(idx, default=elem)
-        v_str = object_utils.format(
-            elem, compact, verbose, root_indent + 1,
-            python_format=python_format, use_inferred=use_inferred, **kwargs)
+        v_str = utils.format(
+            elem,
+            compact,
+            verbose,
+            root_indent + 1,
+            python_format=python_format,
+            use_inferred=use_inferred,
+            **kwargs,
+        )
         if python_format:
           kv_strs.append(v_str)
         else:
@@ -812,9 +829,15 @@ class List(list, base.Symbolic, pg_typing.CustomTyping):
             s.append('\n')
           else:
             s.append(',\n')
-          v_str = object_utils.format(
-              elem, compact, verbose, root_indent + 1,
-              python_format=python_format, use_inferred=use_inferred, **kwargs)
+          v_str = utils.format(
+              elem,
+              compact,
+              verbose,
+              root_indent + 1,
+              python_format=python_format,
+              use_inferred=use_inferred,
+              **kwargs,
+          )
           if python_format:
             s.append(_indent(v_str, root_indent + 1))
           else:

pyglove/core/symbolic/list_test.py

@@ -20,8 +20,8 @@ import pickle
 from typing import Any
 import unittest
 
-from pyglove.core import object_utils
 from pyglove.core import typing as pg_typing
+from pyglove.core import utils
 from pyglove.core.symbolic import base
 from pyglove.core.symbolic import flags
 from pyglove.core.symbolic import inferred
@@ -34,7 +34,7 @@ from pyglove.core.symbolic.pure_symbolic import NonDeterministic
 from pyglove.core.symbolic.pure_symbolic import PureSymbolic
 
 
-MISSING_VALUE = object_utils.MISSING_VALUE
+MISSING_VALUE = utils.MISSING_VALUE
 
 
 class ListTest(unittest.TestCase):
@@ -685,7 +685,7 @@ class ListTest(unittest.TestCase):
     self.assertTrue(sl.sym_has('[0].x'))
     self.assertTrue(sl.sym_has('[0].x[0]'))
     self.assertTrue(sl.sym_has('[0].x[0].y'))
-    self.assertTrue(sl.sym_has(object_utils.KeyPath.parse('[0].x[0].y')))
+    self.assertTrue(sl.sym_has(utils.KeyPath.parse('[0].x[0].y')))
 
   def test_sym_get(self):
     sl = List([dict(x=[dict(y=1)])])
@@ -1100,7 +1100,7 @@ class ListTest(unittest.TestCase):
     self.assertEqual(sl[1].sym_path, '[1]')
     self.assertEqual(sl[1][0].b.sym_path, '[1][0].b')
 
-    sl.sym_setpath(object_utils.KeyPath('a'))
+    sl.sym_setpath(utils.KeyPath('a'))
     self.assertEqual(sl.sym_path, 'a')
     self.assertEqual(sl[0].sym_path, 'a[0]')
     self.assertEqual(sl[0].a.sym_path, 'a[0].a')
@@ -1412,96 +1412,112 @@ class RebindTest(unittest.TestCase):
         '[3]': 'foo',  # Unchanged.
         '[4]': Insertion('bar')
     })
-    self.assertEqual(updates, [
-        {  # Notification to `sl[2][0]`.
-            'p': base.FieldUpdate(
-                object_utils.KeyPath.parse('[2][0].p'),
-                target=sl[2][0],
-                field=None,
-                old_value=1,
-                new_value=MISSING_VALUE),
-            'q': base.FieldUpdate(
-                object_utils.KeyPath.parse('[2][0].q'),
-                target=sl[2][0],
-                field=None,
-                old_value=MISSING_VALUE,
-                new_value=2),
-        },
-        {  # Notification to `sl.c`.
-            '[0].p': base.FieldUpdate(
-                object_utils.KeyPath.parse('[2][0].p'),
-                target=sl[2][0],
-                field=None,
-                old_value=1,
-                new_value=MISSING_VALUE),
-            '[0].q': base.FieldUpdate(
-                object_utils.KeyPath.parse('[2][0].q'),
-                target=sl[2][0],
-                field=None,
-                old_value=MISSING_VALUE,
-                new_value=2),
-        },
-        {  # Notification to `sl[1].y`.
-            'z': base.FieldUpdate(
-                object_utils.KeyPath.parse('[1].y.z'),
-                target=sl[1].y,
-                field=None,
-                old_value=MISSING_VALUE,
-                new_value=1),
-        },
-        {  # Notification to `sl.b`.
-            'x': base.FieldUpdate(
-                object_utils.KeyPath.parse('[1].x'),
-                target=sl[1],
-                field=None,
-                old_value=1,
-                new_value=2),
-            'y.z': base.FieldUpdate(
-                object_utils.KeyPath.parse('[1].y.z'),
-                target=sl[1].y,
-                field=None,
-                old_value=MISSING_VALUE,
-                new_value=1),
-        },
-        {  # Notification to `sl`.
-            '[0]': base.FieldUpdate(
-                object_utils.KeyPath.parse('[0]'),
-                target=sl,
-                field=None,
-                old_value=1,
-                new_value=2),
-            '[1].x': base.FieldUpdate(
-                object_utils.KeyPath.parse('[1].x'),
-                target=sl[1],
-                field=None,
-                old_value=1,
-                new_value=2),
-            '[1].y.z': base.FieldUpdate(
-                object_utils.KeyPath.parse('[1].y.z'),
-                target=sl[1].y,
-                field=None,
-                old_value=MISSING_VALUE,
-                new_value=1),
-            '[2][0].p': base.FieldUpdate(
-                object_utils.KeyPath.parse('[2][0].p'),
-                target=sl[2][0],
-                field=None,
-                old_value=1,
-                new_value=MISSING_VALUE),
-            '[2][0].q': base.FieldUpdate(
-                object_utils.KeyPath.parse('[2][0].q'),
-                target=sl[2][0],
-                field=None,
-                old_value=MISSING_VALUE,
-                new_value=2),
-            '[4]': base.FieldUpdate(
-                object_utils.KeyPath.parse('[4]'),
-                target=sl,
-                field=None,
-                old_value=MISSING_VALUE,
-                new_value='bar')
-        }
-    ])
+    self.assertEqual(
+        updates,
+        [
+            {  # Notification to `sl[2][0]`.
+                'p': base.FieldUpdate(
+                    utils.KeyPath.parse('[2][0].p'),
+                    target=sl[2][0],
+                    field=None,
+                    old_value=1,
+                    new_value=MISSING_VALUE,
+                ),
+                'q': base.FieldUpdate(
+                    utils.KeyPath.parse('[2][0].q'),
+                    target=sl[2][0],
+                    field=None,
+                    old_value=MISSING_VALUE,
+                    new_value=2,
+                ),
+            },
+            {  # Notification to `sl.c`.
+                '[0].p': base.FieldUpdate(
+                    utils.KeyPath.parse('[2][0].p'),
+                    target=sl[2][0],
+                    field=None,
+                    old_value=1,
+                    new_value=MISSING_VALUE,
+                ),
+                '[0].q': base.FieldUpdate(
+                    utils.KeyPath.parse('[2][0].q'),
+                    target=sl[2][0],
+                    field=None,
+                    old_value=MISSING_VALUE,
+                    new_value=2,
+                ),
+            },
+            {  # Notification to `sl[1].y`.
+                'z': base.FieldUpdate(
+                    utils.KeyPath.parse('[1].y.z'),
+                    target=sl[1].y,
+                    field=None,
+                    old_value=MISSING_VALUE,
+                    new_value=1,
+                ),
+            },
+            {  # Notification to `sl.b`.
+                'x': base.FieldUpdate(
+                    utils.KeyPath.parse('[1].x'),
+                    target=sl[1],
+                    field=None,
+                    old_value=1,
+                    new_value=2,
+                ),
+                'y.z': base.FieldUpdate(
+                    utils.KeyPath.parse('[1].y.z'),
+                    target=sl[1].y,
+                    field=None,
+                    old_value=MISSING_VALUE,
+                    new_value=1,
+                ),
+            },
+            {  # Notification to `sl`.
+                '[0]': base.FieldUpdate(
+                    utils.KeyPath.parse('[0]'),
+                    target=sl,
+                    field=None,
+                    old_value=1,
+                    new_value=2,
+                ),
+                '[1].x': base.FieldUpdate(
+                    utils.KeyPath.parse('[1].x'),
+                    target=sl[1],
+                    field=None,
+                    old_value=1,
+                    new_value=2,
+                ),
+                '[1].y.z': base.FieldUpdate(
+                    utils.KeyPath.parse('[1].y.z'),
+                    target=sl[1].y,
+                    field=None,
+                    old_value=MISSING_VALUE,
+                    new_value=1,
+                ),
+                '[2][0].p': base.FieldUpdate(
+                    utils.KeyPath.parse('[2][0].p'),
+                    target=sl[2][0],
+                    field=None,
+                    old_value=1,
+                    new_value=MISSING_VALUE,
+                ),
+                '[2][0].q': base.FieldUpdate(
+                    utils.KeyPath.parse('[2][0].q'),
+                    target=sl[2][0],
+                    field=None,
+                    old_value=MISSING_VALUE,
+                    new_value=2,
+                ),
+                '[4]': base.FieldUpdate(
+                    utils.KeyPath.parse('[4]'),
+                    target=sl,
+                    field=None,
+                    old_value=MISSING_VALUE,
+                    new_value='bar',
+                ),
+            },
+        ],
+    )
 
   def test_rebind_with_fn(self):
     sl = List([0, dict(x=1, y='foo', z=[2, 3, 4])])
@@ -1716,7 +1732,7 @@ class FormatTest(unittest.TestCase):
 
   def test_compact_python_format(self):
     self.assertEqual(
-        object_utils.format(
+        utils.format(
             self._list, compact=True, python_format=True, markdown=True
         ),
         "`[{'a1': 1, 'a2': {'b1': {'c1': [{'d1': MISSING_VALUE, "
@@ -1726,9 +1742,12 @@ class FormatTest(unittest.TestCase):
 
   def test_noncompact_python_format(self):
     self.assertEqual(
-        object_utils.format(
-            self._list, compact=False, verbose=False,
-            python_format=True, markdown=True
+        utils.format(
+            self._list,
+            compact=False,
+            verbose=False,
+            python_format=True,
+            markdown=True,
         ),
         inspect.cleandoc("""
           ```