pyglove 0.4.5.dev20240319__py3-none-any.whl → 0.4.5.dev202501132210__py3-none-any.whl

pyglove/core/typing/class_schema_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.core.typing.class_schema."""
-
 import copy
 import inspect
 import sys
 from typing import Optional, Union, List
 import unittest
 
-from pyglove.core import object_utils
+from pyglove.core import utils
 from pyglove.core.typing import annotation_conversion  # pylint: disable=unused-import
 from pyglove.core.typing import class_schema
 from pyglove.core.typing import custom_typing
@@ -67,10 +65,10 @@ class ForwardRefTest(unittest.TestCase):
     with self.assertRaisesRegex(TypeError, '.* is not a class'):
       _ = class_schema.ForwardRef(self._module, 'unittest').cls
 
-  def test_format(self):
+  def test_repr(self):
     self.assertEqual(
-        str(class_schema.ForwardRef(self._module, 'FieldTest')),
-        f'ForwardRef(module={self._module.__name__}, name=FieldTest)',
+        repr(class_schema.ForwardRef(self._module, 'FieldTest')),
+        f'ForwardRef(module=\'{self._module.__name__}\', name=\'FieldTest\')',
     )
 
   def test_eq_ne(self):
@@ -187,46 +185,24 @@ class FieldTest(unittest.TestCase):
           'b': 1,
       }, allow_partial=False)
 
-  def test_format(self):
-    self.assertEqual(
-        Field('a', vs.Dict([
-            ('b', vs.Int())
-        ]), 'this is a very long field.', {
-            'm1': 1,
-            'm2': 2,
-            'm3': 3,
-            'm4': 4,
-            'm5': 5
-        }).format(compact=True, verbose=False),
-        'Field(key=a, value=Dict({b=Int()}), '
-        'description=\'this is a very long ...\', '
-        'metadata={...})')
-
-    self.assertEqual(
-        Field('a', vs.Dict([
-            ('b', vs.Int())
-        ]), 'this is a very long field.', {
-            'm1': 1,
-            'm2': 2,
-            'm3': 3,
-            'm4': 4,
-            'm5': 5
-        }).format(compact=True, verbose=True),
-        'Field(key=a, value=Dict({b=Int()}), '
-        'description=\'this is a very long field.\', '
-        'metadata={\'m1\': 1, \'m2\': 2, \'m3\': 3, \'m4\': 4, \'m5\': 5})')
-
-    self.assertEqual(
-        Field('a', vs.Dict([
-            ('b', vs.Int())
-        ]), 'field a').format(compact=False, verbose=False),
-        'Field(key=a, value=Dict({\n'
-        '    b = Int()\n'
-        '  }), description=\'field a\')')
+  def test_repr(self):
+    self.assertEqual(
+        repr(
+            Field(
+                'a', vs.Dict([('b', vs.Int())]), 'this is a very long field.',
+                {'m1': 1, 'm2': 2, 'm3': 3, 'm4': 4, 'm5': 5}
+            )
+        ),
+        (
+            'Field(key=a, value=Dict(fields=[Field(key=b, '
+            'value=Int())]), description=\'this is a very long field.\', '
+            'metadata={\'m1\': 1, \'m2\': 2, \'m3\': 3, \'m4\': 4, \'m5\': 5})'
+        )
+    )
 
   def test_json_conversion(self):
     def assert_json_conversion(f):
-      self.assertEqual(object_utils.from_json(f.to_json()), f)
+      self.assertEqual(utils.from_json(f.to_json()), f)
 
     assert_json_conversion(Field('a', vs.Int()))
     assert_json_conversion(Field('a', vs.Int(), 'description'))
@@ -342,58 +318,131 @@ class SchemaTest(unittest.TestCase):
   def test_eq(self):
     self.assertEqual(self._create_test_schema(), self._create_test_schema())
 
-  def test_format(self):
+  def test_repr(self):
     """Tests for Schema.format."""
     self.assertEqual(
-        self._create_test_schema().format(compact=True),
-        'Schema(a=Int(default=1), b=Bool(default=None, noneable=True), '
-        'c=Dict({d=List('
-        'Enum(default=0, values=[0, 1, None]), default=[0, 1]), '
-        'e=List('
-        'Dict({StrKey(regex=\'foo.*\')=Str()})), '
-        'f=Object(SimpleObject)}, noneable=True))')
-
-    self.assertEqual(
-        inspect.cleandoc(self._create_test_schema().format(
-            compact=False, verbose=False)),
-        inspect.cleandoc("""Schema(
-          a = Int(default=1),
-          b = Bool(default=None, noneable=True),
-          c = Dict({
-            d = List(Enum(default=0, values=[0, 1, None]), default=[0, 1]),
-            e = List(Dict({
-              StrKey(regex=\'foo.*\') = Str()
-            })),
-            f = Object(SimpleObject)
-          }, noneable=True)
-        )"""))
-
-    self.assertEqual(
-        inspect.cleandoc(
-            # Equal to schema.format(compact=False, verbose=True)
-            str(self._create_test_schema())),
-        inspect.cleandoc("""Schema(
-            # Field a.
-            a = Int(default=1),
-
-            # Field b.
-            b = Bool(default=None, noneable=True),
-
-            # Field c.
-            c = Dict({
-              # Field d.
-              d = List(Enum(default=0, values=[0, 1, None]), default=[0, 1]),
-
-              # Field e.
-              e = List(Dict({
-                # Mapped values.
-                StrKey(regex=\'foo.*\') = Str()
-              })),
-
-              # Field f.
-              f = Object(SimpleObject)
-            }, noneable=True)
-          )"""))
+        repr(self._create_test_schema()),
+        (
+            "Schema(fields=[Field(key=a, value=Int(default=1), description="
+            "'Field a.'), Field(key=b, value=Bool(default=None, noneable="
+            "True), description='Field b.'), Field(key=c, value=Dict("
+            "fields=[Field(key=d, value=List(Enum(default=0, values=[0, 1, "
+            "None]), default=[0, 1]), description='Field d.'), Field(key=e, "
+            "value=List(Dict(fields=[Field(key=StrKey(regex='foo.*'), "
+            "value=Str(), description='Mapped values.')])), description='Field"
+            " e.'), Field(key=f, value=Object(SimpleObject), description="
+            "'Field f.')], noneable=True), description='Field c.')], "
+            "allow_nonconst_keys=False, metadata={'init_arg_list': []})"
+        )
+    )
+
+  def test_str(self):
+    self.maxDiff = None
+    self.assertEqual(
+        str(self._create_test_schema()),
+        inspect.cleandoc("""
+        Schema(
+          fields=[
+            Field(
+              key=a,
+              value=Int(
+                default=1
+              ),
+              description='Field a.'
+            ),
+            Field(
+              key=b,
+              value=Bool(
+                default=None,
+                noneable=True
+              ),
+              description='Field b.'
+            ),
+            Field(
+              key=c,
+              value=Dict(
+                fields=[
+                  Field(
+                    key=d,
+                    value=List(
+                      Enum(
+                        default=0,
+                        values=[0, 1, None]
+                      ),
+                      default=[0, 1]
+                    ),
+                    description='Field d.'
+                  ),
+                  Field(
+                    key=e,
+                    value=List(
+                      Dict(
+                        fields=[
+                          Field(
+                            key=StrKey(regex='foo.*'),
+                            value=Str(),
+                            description='Mapped values.'
+                          )
+                        ]
+                      )
+                    ),
+                    description='Field e.'
+                  ),
+                  Field(
+                    key=f,
+                    value=Object(
+                      SimpleObject
+                    ),
+                    description='Field f.'
+                  )
+                ],
+                noneable=True
+              ),
+              description='Field c.'
+            )
+          ],
+          allow_nonconst_keys=False,
+          metadata={
+            'init_arg_list': []
+          }
+        )""")
+    )
+
+  def test_merge(self):
+    """Tests for Schema.merge."""
+    self.assertEqual(
+        Schema.merge([
+            class_schema.create_schema([
+                ('a', vs.Int()),
+                ('b', vs.Bool().noneable()),
+            ]),
+            class_schema.create_schema([
+                ('a', vs.Str()),
+                ('c', vs.Float()),
+            ]),
+        ]),
+        class_schema.create_schema([
+            ('a', vs.Int()),
+            ('b', vs.Bool().noneable()),
+            ('c', vs.Float()),
+        ]),
+    )
+    self.assertEqual(
+        Schema.merge([
+            class_schema.create_schema([
+                ('a', vs.Int()),
+                (ks.StrKey(), vs.Str().noneable()),
+            ], allow_nonconst_keys=True),
+            class_schema.create_schema([
+                ('c', vs.Float()),
+            ]),
+        ]),
+        class_schema.create_schema([
+            ('a', vs.Int()),
+            ('c', vs.Float()),
+            (ks.StrKey(), vs.Str().noneable()),
+        ], allow_nonconst_keys=True),
+    )
 
   def test_extend(self):
     """Tests for Schema.extend."""
@@ -541,7 +590,7 @@ class SchemaTest(unittest.TestCase):
     ], base_schema_list=[s], allow_nonconst_keys=True)
     self.assertEqual(s.dynamic_field, Field(ks.StrKey(), vs.Str()))
 
-  def test_Validate(self):
+  def test_validate(self):
     # Validate fully specified fields.
     self._create_test_schema().validate({
         'a': 1,
@@ -771,7 +820,7 @@ class SchemaTest(unittest.TestCase):
     schema = self._create_test_schema()
     schema.set_description('Foo')
     schema.set_name('Bar')
-    schema_copy = object_utils.from_json(schema.to_json())
+    schema_copy = utils.from_json(schema.to_json())
 
     # This compares fields only
     self.assertEqual(schema_copy, schema)
@@ -856,6 +905,11 @@ class CreateSchemaTest(unittest.TestCase):
     ):
       class_schema.create_schema([], metadata=1)
 
+    with self.assertRaisesRegex(
+        TypeError, 'Schema definition should be a dict.*a list.'
+    ):
+      class_schema.create_schema(1, metadata=1)
+
     with self.assertRaisesRegex(
         TypeError, 'Field definition should be tuples with 2 to 4 elements.'
     ):

pyglove/core/typing/custom_typing.py

@@ -16,7 +16,7 @@
 import abc
 from typing import Any, Callable, Optional, Tuple
 
-from pyglove.core import object_utils
+from pyglove.core import utils
 from pyglove.core.typing import class_schema
 
 
@@ -34,11 +34,12 @@ class CustomTyping(metaclass=abc.ABCMeta):
   @abc.abstractmethod
   def custom_apply(
       self,
-      path: object_utils.KeyPath,
+      path: utils.KeyPath,
       value_spec: class_schema.ValueSpec,
       allow_partial: bool,
-      child_transform: Optional[Callable[
-          [object_utils.KeyPath, class_schema.Field, Any], Any]] = None
+      child_transform: Optional[
+          Callable[[utils.KeyPath, class_schema.Field, Any], Any]
+      ] = None,
   ) -> Tuple[bool, Any]:
     """Custom apply on a value based on its original value spec.
 

pyglove/core/typing/inspect.py

@@ -14,6 +14,7 @@
 """Utility module for inspecting generics types."""
 
 import inspect
+import sys
 import typing
 from typing import Any, Callable, Optional, Tuple, Type, Union
 
@@ -116,6 +117,68 @@ def get_type_args(
     return ()
 
 
+def get_outer_class(
+    cls: Type[Any],
+    base_cls: Union[Type[Any], Tuple[Type[Any], ...], None] = None,
+    immediate: bool = False,
+) -> Optional[Type[Any]]:
+  """Returns the outer class.
+
+  Example::
+
+    class A:
+      pass
+
+    class A1:
+      class B:
+        class C:
+          ...
+
+    pg.typing.outer_class(B) is A1
+    pg.typing.outer_class(C) is B
+    pg.typing.outer_class(C, base_cls=A) is None
+    pg.typing.outer_class(C, base_cls=A1) is None
+
+  Args:
+    cls: The class to get the outer class for.
+    base_cls: The base class of the outer class. If provided, an outer class
+      that is not a subclass of `base_cls` will be returned as None.
+    immediate: Whether to return the immediate outer class or a class in the
+      nesting hierarchy that is a subclass of `base_cls`. Applicable when
+      `base_cls` is not None.
+
+  Returns:
+    The outer class of `cls`. None if cannot find one or the outer class is
+      not a subclass of `base_cls`.
+  """
+  if '<locals>' in cls.__qualname__:
+    raise ValueError(
+        'Cannot find the outer class for locally defined class '
+        f'{cls.__qualname__!r}'
+    )
+
+  names = cls.__qualname__.split('.')
+  if len(names) < 2:
+    return None
+
+  parent = sys.modules[cls.__module__]
+  symbols = []
+  for name in names[:-1]:
+    symbol = getattr(parent, name, None)
+    if symbol is None:
+      return None
+    assert inspect.isclass(symbol), symbol
+    symbols.append(symbol)
+    parent = symbol
+
+  for symbol in reversed(symbols):
+    if immediate:
+      return symbol if not base_cls or issubclass(symbol, base_cls) else None
+    if not base_cls or issubclass(symbol, base_cls):
+      return symbol
+  return None
+
+
 def callable_eq(
     x: Optional[Callable[..., Any]], y: Optional[Callable[..., Any]]
 ) -> bool:

pyglove/core/typing/inspect_test.py

@@ -16,8 +16,10 @@
 from typing import Any, Generic, TypeVar
 import unittest
 
+from pyglove.core.typing import callable_signature
 from pyglove.core.typing import inspect
 
+
 XType = TypeVar('XType')
 YType = TypeVar('YType')
 
@@ -50,6 +52,16 @@ class D(C):
   pass
 
 
+class AA:
+  pass
+
+
+class AA1(AA):
+  class BB1:
+    class CC1:
+      pass
+
+
 class InspectTest(unittest.TestCase):
 
   def test_issubclass(self):
@@ -141,6 +153,33 @@ class InspectTest(unittest.TestCase):
     self.assertEqual(inspect.get_type_args(C, A), (str, int))
     self.assertEqual(inspect.get_type_args(C, B), (Str,))
 
+  def test_outer_class(self):
+    class Foo:
+      pass
+
+    with self.assertRaisesRegex(ValueError, '.* locally defined class'):
+      inspect.get_outer_class(Foo)
+
+    self.assertIsNone(inspect.get_outer_class(AA))
+    self.assertIs(inspect.get_outer_class(AA1.BB1), AA1)
+    self.assertIs(inspect.get_outer_class(AA1.BB1, AA), AA1)
+    self.assertIs(inspect.get_outer_class(AA1.BB1, A), None)
+    self.assertIs(inspect.get_outer_class(AA1.BB1.CC1), AA1.BB1)
+    self.assertIsNone(
+        inspect.get_outer_class(AA1.BB1.CC1, base_cls=AA, immediate=True)
+    )
+    self.assertIs(inspect.get_outer_class(AA1.BB1.CC1, AA), AA1)
+    self.assertIs(
+        inspect.get_outer_class(callable_signature.Argument.Kind),
+        callable_signature.Argument
+    )
+
+    class Bar:
+      pass
+
+    Bar.__qualname__ = 'NonExist.Bar'
+    self.assertIsNone(inspect.get_outer_class(Bar))
+
   def test_callable_eq(self):
     def foo(unused_x):
       pass

pyglove/core/typing/key_specs.py

@@ -16,7 +16,7 @@
 import re
 from typing import Any, Dict, Optional
 
-from pyglove.core import object_utils
+from pyglove.core import utils
 from pyglove.core.typing.class_schema import KeySpec
 
 
@@ -29,16 +29,16 @@ class KeySpecBase(KeySpec):
       raise KeyError(f'{self} cannot extend {base} for keys are different.')
     return self
 
-  def __repr__(self) -> str:
-    """Operator repr."""
-    return self.__str__()
-
   def __ne__(self, other: Any) -> bool:
     """Operator !=."""
     return not self.__eq__(other)
 
+  def __str_kwargs__(self) -> Dict[str, Any]:
+    """Returns the string representation of this key spec."""
+    return {}
+
 
-class ConstStrKey(KeySpecBase, object_utils.StrKey):
+class ConstStrKey(KeySpecBase, utils.StrKey):
   """Class that represents a constant string key.
 
   Example::
@@ -159,11 +159,10 @@ class StrKey(NonConstKey):
 
   def format(self, **kwargs):
     """Format this object."""
-    regex_str = object_utils.kvlist_str([
-        ('regex', object_utils.quote_if_str(
-            self._regex.pattern if self._regex else None), None)
-    ])
-    return f'StrKey({regex_str})'
+    return utils.kvlist_str(
+        [('regex', getattr(self._regex, 'pattern', None), None)],
+        label=self.__class__.__name__,
+    )
 
   def to_json(self, **kwargs: Any) -> Dict[str, Any]:
     regex = self._regex.pattern if self._regex is not None else None

pyglove/core/typing/key_specs_test.py

@@ -14,7 +14,7 @@
 """Tests for pyglove.core.typing.key_specs."""
 
 import unittest
-from pyglove.core import object_utils
+from pyglove.core import utils
 from pyglove.core.typing import key_specs as ks
 
 
@@ -22,7 +22,7 @@ class KeySpecTest(unittest.TestCase):
   """Base class for KeySpec tests."""
 
   def assert_json_conversion(self, spec: ks.KeySpec):
-    self.assertEqual(object_utils.from_json(object_utils.to_json(spec)), spec)
+    self.assertEqual(utils.from_json(utils.to_json(spec)), spec)
 
 
 class ConstStrKeyTest(KeySpecTest):
@@ -35,8 +35,10 @@ class ConstStrKeyTest(KeySpecTest):
     self.assertEqual(key.text, 'a')
     self.assertNotEqual(key, 'b')
     self.assertIn(key, {'a': 1})
-    self.assertEqual(str(key), 'a')
-    self.assertEqual(repr(key), 'a')
+    with utils.str_format(markdown=True):
+      self.assertEqual(str(key), 'a')
+    with utils.str_format(markdown=True):
+      self.assertEqual(repr(key), 'a')
     self.assertTrue(key.match('a'))
     self.assertFalse(key.match('b'))
 
@@ -67,6 +69,7 @@ class StrKeyTest(KeySpecTest):
 
   def test_match_with_regex(self):
     key = ks.StrKey('a.*')
+    self.assertEqual(repr(key), 'StrKey(regex=\'a.*\')')
     self.assertTrue(key.match('a1'))
     self.assertTrue(key.match('a'))
     self.assertFalse(key.match('b'))

pyglove/core/typing/type_conversion.py

@@ -17,7 +17,7 @@ import calendar
 import datetime
 from typing import Any, Callable, Optional, Tuple, Type, Union
 
-from pyglove.core import object_utils
+from pyglove.core import utils
 from pyglove.core.typing import inspect as pg_inspect
 
 
@@ -135,10 +135,9 @@ def _register_builtin_converters():
                      lambda x: calendar.timegm(x.timetuple()))
 
   # string <=> KeyPath.
-  register_converter(str, object_utils.KeyPath,
-                     object_utils.KeyPath.parse)
-  register_converter(object_utils.KeyPath, str, lambda x: x.path)
+  register_converter(str, utils.KeyPath, utils.KeyPath.parse)
+  register_converter(utils.KeyPath, str, lambda x: x.path)
 
 
 _register_builtin_converters()
-object_utils.JSONConvertible.TYPE_CONVERTER = get_json_value_converter
+utils.JSONConvertible.TYPE_CONVERTER = get_json_value_converter

pyglove/core/typing/type_conversion_test.py

@@ -11,14 +11,12 @@
 # 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.core.typing.type_conversion."""
-
 import calendar
 import datetime
 import typing
 import unittest
 
-from pyglove.core import object_utils
+from pyglove.core import utils
 from pyglove.core.typing import annotation_conversion  # pylint: disable=unused-import
 from pyglove.core.typing import type_conversion
 from pyglove.core.typing import value_specs as vs
@@ -137,17 +135,19 @@ class BuiltInConversionsTest(unittest.TestCase):
   def test_keypath_to_str(self):
     """Test built-in converter between string and KeyPath."""
     self.assertEqual(
-        vs.Object(object_utils.KeyPath).apply('a.b.c').keys,
-        ['a', 'b', 'c'])
-    self.assertEqual(
-        vs.Union([vs.Object(object_utils.KeyPath), vs.Int()]).apply(
-            'a.b.c').keys,
-        ['a', 'b', 'c'])
+        vs.Object(utils.KeyPath).apply('a.b.c').keys, ['a', 'b', 'c']
+    )
     self.assertEqual(
-        vs.Str().apply(object_utils.KeyPath.parse('a.b.c')), 'a.b.c')
+        vs.Union([vs.Object(utils.KeyPath), vs.Int()]).apply('a.b.c').keys,
+        ['a', 'b', 'c'],
+    )
+    self.assertEqual(vs.Str().apply(utils.KeyPath.parse('a.b.c')), 'a.b.c')
     self.assertEqual(
-        type_conversion.get_json_value_converter(object_utils.KeyPath)(
-            object_utils.KeyPath.parse('a.b.c')), 'a.b.c')
+        type_conversion.get_json_value_converter(utils.KeyPath)(
+            utils.KeyPath.parse('a.b.c')
+        ),
+        'a.b.c',
+    )
 
 
 if __name__ == '__main__':

pyglove/core/typing/typed_missing.py

@@ -14,15 +14,15 @@
 """Typed value placeholders."""
 
 from typing import Any
-from pyglove.core import object_utils
+from pyglove.core import utils
 from pyglove.core.typing import class_schema
 
 
 # Non-typed missing value.
-MISSING_VALUE = object_utils.MISSING_VALUE
+MISSING_VALUE = utils.MISSING_VALUE
 
 
-class MissingValue(object_utils.MissingValue, object_utils.Formattable):
+class MissingValue(utils.MissingValue, utils.Formattable):
   """Class represents missing value **for a specific value spec**."""
 
   def __init__(self, value_spec: class_schema.ValueSpec):
@@ -37,15 +37,15 @@ class MissingValue(object_utils.MissingValue, object_utils.Formattable):
   def __eq__(self, other: Any) -> bool:
     """Operator ==.
 
-    NOTE: `MissingValue(value_spec) and `object_utils.MissingValue` are
+    NOTE: `MissingValue(value_spec) and `utils.MissingValue` are
     considered equal, but `MissingValue(value_spec1)` and
     `MissingValue(value_spec2)` are considered different. That being said,
     the 'eq' operation is not transitive.
 
     However in practice this is not a problem, since user always compare
-    against `schema.MISSING_VALUE` which is `object_utils.MissingValue`.
+    against `schema.MISSING_VALUE` which is `utils.MissingValue`.
     Therefore the `__hash__` function returns the same value with
-    `object_utils.MissingValue`.
+    `utils.MissingValue`.
 
     Args:
       other: the value to compare against.
@@ -80,4 +80,3 @@ class MissingValue(object_utils.MissingValue, object_utils.Formattable):
   def __deepcopy__(self, memo):
     """Avoid deep copy by copying value_spec by reference."""
     return MissingValue(self.value_spec)
-