pyglove 0.4.5.dev202501050808__py3-none-any.whl → 0.4.5.dev202501060809__py3-none-any.whl

pyglove/core/__init__.py

@@ -37,8 +37,7 @@ Here lists the sub-modules included in the core PyGlove library:
    |__ tuning          :  Interface for program tuning with a local backend.
    |__ detouring       :  Detouring classes creation without symbolic types.
    |__ patching        :  Patching a program with URL-like strings.
-   |__ object_utils    :  Utility libary on operating with Python objects.
-
+   |__ utils           :  Utility libary on operating with Python objects.
 """
 
 # NOTE(daiyip): We disable bad-import-order to preserve the relation of
@@ -273,31 +272,35 @@ ObjectFactory = patching.ObjectFactory
 
 
 #
-# Symbols from 'object_utils' sub-module.
+# Symbols from 'utils' sub-module.
 #
 
-from pyglove.core import object_utils
-KeyPath = object_utils.KeyPath
-KeyPathSet = object_utils.KeyPathSet
-MISSING_VALUE = object_utils.MISSING_VALUE
+from pyglove.core import utils
+
+# For backward compatibility.
+object_utils = utils
+
+KeyPath = utils.KeyPath
+KeyPathSet = utils.KeyPathSet
+MISSING_VALUE = utils.MISSING_VALUE
 
-Formattable = object_utils.Formattable
-repr_format = object_utils.repr_format
-str_format = object_utils.str_format
+Formattable = utils.Formattable
+repr_format = utils.repr_format
+str_format = utils.str_format
 
-MaybePartial = object_utils.MaybePartial
-JSONConvertible = object_utils.JSONConvertible
-DocStr = object_utils.DocStr
+MaybePartial = utils.MaybePartial
+JSONConvertible = utils.JSONConvertible
+DocStr = utils.DocStr
 
-registered_types = object_utils.registered_types
-explicit_method_override = object_utils.explicit_method_override
+registered_types = utils.registered_types
+explicit_method_override = utils.explicit_method_override
 
-is_partial = object_utils.is_partial
-format = object_utils.format   # pylint: disable=redefined-builtin
-print = object_utils.print    # pylint: disable=redefined-builtin
-docstr = object_utils.docstr
-catch_errors = object_utils.catch_errors
-timeit = object_utils.timeit
+is_partial = utils.is_partial
+format = utils.format  # pylint: disable=redefined-builtin
+print = utils.print  # pylint: disable=redefined-builtin
+docstr = utils.docstr
+catch_errors = utils.catch_errors
+timeit = utils.timeit
 
 # Symbols from 'views' sub-module.
 

pyglove/core/geno/base.py

@@ -19,9 +19,9 @@ import random
 import types
 from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
-from pyglove.core import object_utils
 from pyglove.core import symbolic
 from pyglove.core import typing as pg_typing
+from pyglove.core import utils
 
 
 class AttributeDict(dict):
@@ -37,12 +37,20 @@ class AttributeDict(dict):
 
 
 @symbolic.members([
-    ('location',
-     pg_typing.Object(object_utils.KeyPath, default=object_utils.KeyPath()),
-     ('KeyPath of associated genetic encoder relative to parent object '
-      'template. This allows DNA generator to apply rule based on locations.')),
-    ('hints',
-     pg_typing.Any(default=None), 'Hints for DNA generator to consume.')
+    (
+        'location',
+        pg_typing.Object(utils.KeyPath, default=utils.KeyPath()),
+        (
+            'KeyPath of associated genetic encoder relative to parent object'
+            ' template. This allows DNA generator to apply rule based on'
+            ' locations.'
+        ),
+    ),
+    (
+        'hints',
+        pg_typing.Any(default=None),
+        'Hints for DNA generator to consume.',
+    ),
 ])
 class DNASpec(symbolic.Object):
   """Base class for DNA specifications (genotypes).
@@ -175,7 +183,7 @@ class DNASpec(symbolic.Object):
     """Returns all decision points in their declaration order."""
 
   @property
-  def decision_ids(self) -> List[object_utils.KeyPath]:
+  def decision_ids(self) -> List[utils.KeyPath]:
     """Returns decision IDs."""
     return list(self._decision_point_by_id.keys())
 
@@ -286,7 +294,7 @@ class DNASpec(symbolic.Object):
     return self.parent_spec if self.is_space else self.parent_spec.parent_choice
 
   @property
-  def id(self) -> object_utils.KeyPath:
+  def id(self) -> utils.KeyPath:
     """Returns a path of locations from the root as the ID for current node."""
     if self._id is None:
       parent = self.parent_spec
@@ -295,18 +303,20 @@ class DNASpec(symbolic.Object):
       elif self.is_space:
         assert parent.is_categorical, parent
         assert self.index is not None
-        self._id = object_utils.KeyPath(
-            ConditionalKey(self.index, len(parent.candidates)),
-            parent.id) + self.location
+        self._id = (
+            utils.KeyPath(
+                ConditionalKey(self.index, len(parent.candidates)), parent.id
+            )
+            + self.location
+        )
       else:
         # Float() or a multi-choice spec of a parent Choice.
         self._id = parent.id + self.location
     return self._id
 
-  def get(self,
-          name_or_id: Union[object_utils.KeyPath, str],
-          default: Any = None
-          ) -> Union['DecisionPoint', List['DecisionPoint']]:
+  def get(
+      self, name_or_id: Union[utils.KeyPath, str], default: Any = None
+  ) -> Union['DecisionPoint', List['DecisionPoint']]:
     """Get decision point(s) by name or ID."""
     try:
       return self[name_or_id]
@@ -314,9 +324,8 @@ class DNASpec(symbolic.Object):
       return default
 
   def __getitem__(
-      self,
-      name_or_id: Union[object_utils.KeyPath, str]
-      ) -> Union['DecisionPoint', List['DecisionPoint']]:
+      self, name_or_id: Union[utils.KeyPath, str]
+  ) -> Union['DecisionPoint', List['DecisionPoint']]:
     """Get decision point(s) by name or ID ."""
     v = self._named_decision_points.get(name_or_id, None)
     if v is None:
@@ -475,7 +484,7 @@ class DNA(symbolic.Object):
   # Allow assignment on symbolic attributes.
   allow_symbolic_assignment = True
 
-  @object_utils.explicit_method_override
+  @utils.explicit_method_override
   def __init__(
       self,
       value: Union[None, int, float, str, List[Any], Tuple[Any]] = None,
@@ -727,7 +736,7 @@ class DNA(symbolic.Object):
     return self._decision_by_id_cache
 
   @property
-  def decision_ids(self) -> List[object_utils.KeyPath]:
+  def decision_ids(self) -> List[utils.KeyPath]:
     """Returns decision IDs."""
     self._ensure_dna_spec()
     return self._spec.decision_ids
@@ -1249,9 +1258,11 @@ class DNA(symbolic.Object):
     return dna
 
   def to_numbers(
-      self, flatten: bool = True,
-      ) -> Union[List[Union[int, float, str]],
-                 object_utils.Nestable[Union[int, float, str]]]:
+      self,
+      flatten: bool = True,
+  ) -> Union[
+      List[Union[int, float, str]], utils.Nestable[Union[int, float, str]]
+  ]:
     """Returns a (maybe) nested structure of numbers as decisions.
 
     Args:
@@ -1338,7 +1349,7 @@ class DNA(symbolic.Object):
               f'Location: {dna_spec.location.path}.')
         children = []
         for i, choice in enumerate(decision):
-          choice_location = object_utils.KeyPath(i, dna_spec.location)
+          choice_location = utils.KeyPath(i, dna_spec.location)
           if not isinstance(choice, int):
             raise ValueError(
                 f'Choice value should be int. Encountered: {choice}, '
@@ -1410,7 +1421,7 @@ class DNA(symbolic.Object):
 
     if type_info:
       json_value = {
-          object_utils.JSONConvertible.TYPE_NAME_KEY: (
+          utils.JSONConvertible.TYPE_NAME_KEY: (
               self.__class__.__serialization_key__
           ),
           'format': 'compact',
@@ -1435,7 +1446,8 @@ class DNA(symbolic.Object):
       json_value: Dict[str, Any],
       *,
       allow_partial: bool = False,
-      root_path: Optional[object_utils.KeyPath] = None) -> 'DNA':
+      root_path: Optional[utils.KeyPath] = None,
+  ) -> 'DNA':
     """Class method that load a DNA from a JSON value.
 
     Args:
@@ -1472,8 +1484,8 @@ class DNA(symbolic.Object):
     return not self.children
 
   def __getitem__(
-      self, key: Union[int, slice, str, object_utils.KeyPath, 'DecisionPoint']
-      ) -> Union[None, 'DNA', List[Optional['DNA']]]:
+      self, key: Union[int, slice, str, utils.KeyPath, 'DecisionPoint']
+  ) -> Union[None, 'DNA', List[Optional['DNA']]]:
     """Get an immediate child DNA or DNA in the sub-tree.
 
     Args:
@@ -1504,10 +1516,11 @@ class DNA(symbolic.Object):
         v = self._decision_by_id[key]
       return v
 
-  def get(self,
-          key: Union[int, slice, str, object_utils.KeyPath, 'DecisionPoint'],
-          default: Any = None
-          ) -> Union[Any, None, 'DNA', List[Optional['DNA']]]:
+  def get(
+      self,
+      key: Union[int, slice, str, utils.KeyPath, 'DecisionPoint'],
+      default: Any = None,
+  ) -> Union[Any, None, 'DNA', List[Optional['DNA']]]:
     """Get an immediate child DNA or DNA in the sub-tree."""
     try:
       return self[key]
@@ -1529,8 +1542,9 @@ class DNA(symbolic.Object):
           return True
       else:
         raise ValueError(
-            f'DNA.__contains__ does not accept '
-            f'{object_utils.quote_if_str(dna_or_value)!r}.')
+            'DNA.__contains__ does not accept '
+            f'{utils.quote_if_str(dna_or_value)!r}.'
+        )
     return False
 
   def __hash__(self):
@@ -1605,12 +1619,13 @@ class DNA(symbolic.Object):
   ):
     """Customize format method for DNA for more compact representation."""
     if as_dict and self.spec:
-      details = object_utils.format(
+      details = utils.format(
           self.to_dict(value_type='choice_and_literal'),
           False,
           verbose,
           root_indent,
-          **kwargs)
+          **kwargs,
+      )
       s = f'DNA({details})'
     else:
       if 'list_wrap_threshold' not in kwargs:
@@ -1621,7 +1636,7 @@ class DNA(symbolic.Object):
       elif self.is_leaf:
         s = f'DNA({self.value!r})'
       else:
-        rep = object_utils.format(
+        rep = utils.format(
             self.to_json(compact=True, type_info=False),
             compact,
             verbose,

pyglove/core/geno/base_test.py

@@ -11,12 +11,10 @@
 # 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.geno.DNA."""
-
 import unittest
 
-from pyglove.core import object_utils
 from pyglove.core import symbolic
+from pyglove.core import utils
 from pyglove.core.geno.base import ConditionalKey
 from pyglove.core.geno.base import DNA
 from pyglove.core.geno.categorical import manyof
@@ -1144,7 +1142,7 @@ class ConditionalKeyTest(unittest.TestCase):
     self.assertEqual(key.num_choices, 5)
 
   def test_to_str(self):
-    key = object_utils.KeyPath(['a', ConditionalKey(1, 5), 'b'])
+    key = utils.KeyPath(['a', ConditionalKey(1, 5), 'b'])
     self.assertEqual(str(key), 'a[=1/5].b')
 
 

pyglove/core/geno/categorical.py

@@ -18,10 +18,9 @@ import re
 import types
 from typing import Any, List, Optional, Union
 
-from pyglove.core import object_utils
 from pyglove.core import symbolic
 from pyglove.core import typing as pg_typing
-
+from pyglove.core import utils
 from pyglove.core.geno.base import DecisionPoint
 from pyglove.core.geno.base import DNA
 from pyglove.core.geno.base import DNASpec
@@ -139,14 +138,15 @@ class Choices(DecisionPoint):
       for i in range(self.num_choices):
         subchoice_spec = Choices(
             subchoice_index=i,
-            location=object_utils.KeyPath(i),
+            location=utils.KeyPath(i),
             num_choices=1,
             candidates=self.candidates,
             literal_values=self.literal_values,
             distinct=self.distinct,
             sorted=self.sorted,
             name=self.name,
-            hints=self.hints)
+            hints=self.hints,
+        )
         self._decision_points.extend(subchoice_spec.decision_points)
         subchoice_specs.append(subchoice_spec)
       self._subchoice_specs = symbolic.List(subchoice_specs)
@@ -158,7 +158,8 @@ class Choices(DecisionPoint):
         self._decision_points.extend(c.decision_points)
 
   def _update_children_paths(
-      self, old_path: object_utils.KeyPath, new_path: object_utils.KeyPath):
+      self, old_path: utils.KeyPath, new_path: utils.KeyPath
+  ):
     """Trigger path change for subchoices so their IDs can be invalidated."""
     super()._update_children_paths(old_path, new_path)
     if self._subchoice_specs:
@@ -337,7 +338,7 @@ class Choices(DecisionPoint):
               f'DNA child values should be sorted. '
               f'Encountered: {sub_dna_values}, Location: {self.location.path}.')
       for i, sub_dna in enumerate(dna):
-        sub_location = object_utils.KeyPath(i, self.location)
+        sub_location = utils.KeyPath(i, self.location)
         if not isinstance(sub_dna.value, int):
           raise ValueError(
               f'Choice value should be int. Encountered: {sub_dna.value}, '
@@ -601,13 +602,18 @@ class Choices(DecisionPoint):
       kvlist = [('id', str(self.id), '\'\'')]
     else:
       kvlist = []
-    additionl_properties = object_utils.kvlist_str(kvlist + [
-        ('name', self.name, None),
-        ('distinct', self.distinct, True),
-        ('sorted', self.sorted, False),
-        ('hints', self.hints, None),
-        ('subchoice_index', self.subchoice_index, None)
-    ], compact=False, root_indent=root_indent)
+    additionl_properties = utils.kvlist_str(
+        kvlist
+        + [
+            ('name', self.name, None),
+            ('distinct', self.distinct, True),
+            ('sorted', self.sorted, False),
+            ('hints', self.hints, None),
+            ('subchoice_index', self.subchoice_index, None),
+        ],
+        compact=False,
+        root_indent=root_indent,
+    )
     if additionl_properties:
       s.append(', ')
       s.append(additionl_properties)
@@ -615,14 +621,16 @@ class Choices(DecisionPoint):
     return ''.join(s)
 
 
-def manyof(num_choices: int,
-           candidates: List[DNASpec],
-           distinct: bool = True,
-           sorted: bool = False,      # pylint: disable=redefined-builtin
-           literal_values: Optional[List[Union[str, int, float]]] = None,
-           hints: Any = None,
-           location: Union[str, object_utils.KeyPath] = object_utils.KeyPath(),
-           name: Optional[str] = None) -> Choices:
+def manyof(
+    num_choices: int,
+    candidates: List[DNASpec],
+    distinct: bool = True,
+    sorted: bool = False,  # pylint: disable=redefined-builtin
+    literal_values: Optional[List[Union[str, int, float]]] = None,
+    hints: Any = None,
+    location: Union[str, utils.KeyPath] = utils.KeyPath(),
+    name: Optional[str] = None,
+) -> Choices:
   """Returns a multi-choice specification.
 
   It creates the genotype for :func:`pyglove.manyof`.
@@ -674,11 +682,13 @@ def manyof(num_choices: int,
                  hints=hints, location=location, name=name)
 
 
-def oneof(candidates: List[DNASpec],
-          literal_values: Optional[List[Union[str, int, float]]] = None,
-          hints: Any = None,
-          location: Union[str, object_utils.KeyPath] = object_utils.KeyPath(),
-          name: Optional[str] = None) -> Choices:
+def oneof(
+    candidates: List[DNASpec],
+    literal_values: Optional[List[Union[str, int, float]]] = None,
+    hints: Any = None,
+    location: Union[str, utils.KeyPath] = utils.KeyPath(),
+    name: Optional[str] = None,
+) -> Choices:
   """Returns a single choice specification.
 
   It creates the genotype for :func:`pyglove.oneof`.
@@ -716,4 +726,3 @@ def oneof(candidates: List[DNASpec],
   """
   return manyof(1, candidates, literal_values=literal_values,
                 hints=hints, location=location, name=name)
-

pyglove/core/geno/custom.py

@@ -17,10 +17,9 @@ import random
 import types
 from typing import Any, Callable, List, Optional, Union
 
-from pyglove.core import object_utils
 from pyglove.core import symbolic
 from pyglove.core import typing as pg_typing
-
+from pyglove.core import utils
 from pyglove.core.geno.base import DecisionPoint
 from pyglove.core.geno.base import DNA
 
@@ -125,7 +124,7 @@ class CustomDecisionPoint(DecisionPoint):
           f'CustomDecisionPoint expects string type DNA. '
           f'Encountered: {dna!r}, Location: {self.location.path}.')
 
-  def sym_jsonify(self, **kwargs: Any) -> object_utils.JSONValueType:
+  def sym_jsonify(self, **kwargs: Any) -> utils.JSONValueType:
     """Overrides sym_jsonify to exclude non-serializable fields."""
     exclude_keys = kwargs.pop('exclude_keys', [])
     exclude_keys.extend(['random_dna_fn', 'next_dna_fn'])
@@ -153,21 +152,25 @@ class CustomDecisionPoint(DecisionPoint):
       kvlist = [('id', str(self.id), '\'\'')]
     else:
       kvlist = []
-    details = object_utils.kvlist_str(kvlist + [
-        ('hyper_type', self.hyper_type, None),
-        ('name', self.name, None),
-        ('hints', self.hints, None),
-    ])
+    details = utils.kvlist_str(
+        kvlist
+        + [
+            ('hyper_type', self.hyper_type, None),
+            ('name', self.name, None),
+            ('hints', self.hints, None),
+        ]
+    )
     return f'{self.__class__.__name__}({details})'
 
 
-def custom(hyper_type: Optional[str] = None,
-           next_dna_fn: Optional[
-               Callable[[Optional[DNA]], Optional[DNA]]] = None,
-           random_dna_fn: Optional[Callable[[Any], DNA]] = None,
-           hints: Any = None,
-           location: object_utils.KeyPath = object_utils.KeyPath(),
-           name: Optional[str] = None) -> CustomDecisionPoint:
+def custom(
+    hyper_type: Optional[str] = None,
+    next_dna_fn: Optional[Callable[[Optional[DNA]], Optional[DNA]]] = None,
+    random_dna_fn: Optional[Callable[[Any], DNA]] = None,
+    hints: Any = None,
+    location: utils.KeyPath = utils.KeyPath(),
+    name: Optional[str] = None,
+) -> CustomDecisionPoint:
   """Returns a custom decision point.
 
   It creates the genotype for subclasses of :func:`pyglove.hyper.CustomHyper`.

pyglove/core/geno/numerical.py

@@ -17,10 +17,9 @@ import random
 import types
 from typing import Any, List, Optional, Union
 
-from pyglove.core import object_utils
 from pyglove.core import symbolic
 from pyglove.core import typing as pg_typing
-
+from pyglove.core import utils
 from pyglove.core.geno.base import DecisionPoint
 from pyglove.core.geno.base import DNA
 
@@ -167,22 +166,27 @@ class Float(DecisionPoint):
       kvlist = [('id', str(self.id), '\'\'')]
     else:
       kvlist = []
-    details = object_utils.kvlist_str(kvlist + [
-        ('name', self.name, None),
-        ('min_value', self.min_value, None),
-        ('max_value', self.max_value, None),
-        ('scale', self.scale, None),
-        ('hints', self.hints, None),
-    ])
+    details = utils.kvlist_str(
+        kvlist
+        + [
+            ('name', self.name, None),
+            ('min_value', self.min_value, None),
+            ('max_value', self.max_value, None),
+            ('scale', self.scale, None),
+            ('hints', self.hints, None),
+        ]
+    )
     return f'{self.__class__.__name__}({details})'
 
 
-def floatv(min_value: float,
-           max_value: float,
-           scale: Optional[str] = None,
-           hints: Any = None,
-           location: object_utils.KeyPath = object_utils.KeyPath(),
-           name: Optional[str] = None) -> Float:
+def floatv(
+    min_value: float,
+    max_value: float,
+    scale: Optional[str] = None,
+    hints: Any = None,
+    location: utils.KeyPath = utils.KeyPath(),
+    name: Optional[str] = None,
+) -> Float:
   """Returns a Float specification.
 
   It creates the genotype for :func:`pyglove.floatv`.
@@ -226,4 +230,3 @@ def floatv(min_value: float,
   """
   return Float(min_value, max_value, scale,
                hints=hints, location=location, name=name)
-

pyglove/core/geno/space.py

@@ -18,10 +18,9 @@ import random
 import types
 from typing import List, Optional, Union
 
-from pyglove.core import object_utils
 from pyglove.core import symbolic
 from pyglove.core import typing as pg_typing
-
+from pyglove.core import utils
 from pyglove.core.geno.base import DecisionPoint
 from pyglove.core.geno.base import DNA
 from pyglove.core.geno.base import DNASpec
@@ -231,8 +230,8 @@ class Space(DNASpec):
     return sum([len(elem) for elem in self.elements])
 
   def __getitem__(
-      self, index: Union[int, slice, str, object_utils.KeyPath]
-      ) -> Union[DecisionPoint, List[DecisionPoint]]:
+      self, index: Union[int, slice, str, utils.KeyPath]
+  ) -> Union[DecisionPoint, List[DecisionPoint]]:
     """Operator [] to return element by index or sub-DNASpec by name."""
     if isinstance(index, (int, slice)):
       return self.elements[index]

pyglove/core/hyper/base.py

@@ -18,9 +18,9 @@ import abc
 from typing import Any, Callable, Optional
 
 from pyglove.core import geno
-from pyglove.core import object_utils
 from pyglove.core import symbolic
 from pyglove.core import typing as pg_typing
+from pyglove.core import utils
 
 
 class HyperValue(symbolic.NonDeterministic):  # pytype: disable=ignored-metaclass
@@ -110,8 +110,7 @@ class HyperValue(symbolic.NonDeterministic):  # pytype: disable=ignored-metaclas
     """
 
   @abc.abstractmethod
-  def dna_spec(self,
-               location: Optional[object_utils.KeyPath] = None) -> geno.DNASpec:
+  def dna_spec(self, location: Optional[utils.KeyPath] = None) -> geno.DNASpec:
     """Get DNA spec of DNA that is decodable/encodable by this hyper value."""
 
 
@@ -186,12 +185,13 @@ def set_dynamic_evaluate_fn(
   global _global_dynamic_evaluate_fn
   if per_thread:
     assert _global_dynamic_evaluate_fn is None, _global_dynamic_evaluate_fn
-    object_utils.thread_local_set(_TLS_KEY_DYNAMIC_EVALUATE_FN, fn)
+    utils.thread_local_set(_TLS_KEY_DYNAMIC_EVALUATE_FN, fn)
   else:
     _global_dynamic_evaluate_fn = fn
 
 
 def get_dynamic_evaluate_fn() -> Optional[Callable[[HyperValue], Any]]:
   """Gets current dynamic evaluate function."""
-  return object_utils.thread_local_get(
-      _TLS_KEY_DYNAMIC_EVALUATE_FN, _global_dynamic_evaluate_fn)
+  return utils.thread_local_get(
+      _TLS_KEY_DYNAMIC_EVALUATE_FN, _global_dynamic_evaluate_fn
+  )