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

pyglove/core/typing/value_specs_test.py

@@ -18,7 +18,7 @@ import sys
 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 callable_signature
 from pyglove.core.typing import class_schema
@@ -36,11 +36,10 @@ class ValueSpecTest(unittest.TestCase):
   """Base class for value spec test."""
 
   def assert_json_conversion(self, v):
-    self.assertEqual(object_utils.from_json(v.to_json()), v)
+    self.assertEqual(utils.from_json(v.to_json()), v)
 
   def assert_json_conversion_key(self, v, key):
-    self.assertEqual(
-        v.to_json()[object_utils.JSONConvertible.TYPE_NAME_KEY], key)
+    self.assertEqual(v.to_json()[utils.JSONConvertible.TYPE_NAME_KEY], key)
 
 
 class BoolTest(ValueSpecTest):
@@ -99,6 +98,13 @@ class BoolTest(ValueSpecTest):
     with self.assertRaisesRegex(ValueError, 'Value cannot be None'):
       vs.Bool().apply(None)
 
+  def test_instantiation(self):
+    self.assertTrue(vs.Bool()(True))
+    self.assertFalse(vs.Bool()(False))
+    self.assertIsNone(vs.Bool().noneable()())
+    self.assertFalse(vs.Bool()())
+    self.assertTrue(vs.Bool().freeze(True)(False))
+
   def test_is_compatible(self):
     v = vs.Bool()
     self.assertTrue(v.is_compatible(v))
@@ -117,6 +123,12 @@ class BoolTest(ValueSpecTest):
     # Child may extend a noneable base into non-noneable.
     self.assertFalse(vs.Bool().extend(vs.Bool().noneable()).is_noneable)
 
+    # A frozen child may extend a enum with its value as candidate.
+    self.assertEqual(
+        vs.Bool().freeze(True).extend(vs.Enum(2, [2, True])),
+        vs.Enum(True, [2, True]).freeze(),
+    )
+
     # Child cannot extend a base with different type.
     with self.assertRaisesRegex(
         TypeError, '.* cannot extend .*: incompatible type.'):
@@ -127,6 +139,11 @@ class BoolTest(ValueSpecTest):
         TypeError, '.* cannot extend .*: None is not allowed in base spec.'):
       vs.Bool().noneable().extend(vs.Bool())
 
+    # Child cannot extend a non-noneable base to noneable.
+    with self.assertRaisesRegex(
+        TypeError, '.* cannot extend .* with incompatible frozen value'):
+      vs.Bool().freeze(True).extend(vs.Enum(False, [2, False]))
+
   def test_freeze(self):
     self.assertFalse(vs.Bool().frozen)
 
@@ -144,7 +161,7 @@ class BoolTest(ValueSpecTest):
     self.assertTrue(v.default)
 
     with self.assertRaisesRegex(
-        TypeError, 'Cannot extend a frozen value spec.'):
+        TypeError, '.* cannot extend a frozen value spec'):
       vs.Bool().extend(v)
 
     with self.assertRaisesRegex(
@@ -224,6 +241,12 @@ class StrTest(ValueSpecTest):
     self.assertNotEqual(vs.Str(), vs.Str(regex='.*'))
     self.assertNotEqual(vs.Str(regex='a'), vs.Str(regex='.*'))
 
+  def test_instantiation(self):
+    self.assertEqual(vs.Str()('abc'), 'abc')
+    self.assertIsNone(vs.Str().noneable()())
+    self.assertEqual(vs.Str()(), '')
+    self.assertEqual(vs.Str().freeze('abc')('def'), 'abc')
+
   def test_apply(self):
     self.assertEqual(vs.Str().apply('a'), 'a')
     self.assertEqual(vs.Str(regex='a.*').apply('a1'), 'a1')
@@ -266,6 +289,12 @@ class StrTest(ValueSpecTest):
     # Child may extend a noneable base into non-noneable.
     self.assertFalse(vs.Str().extend(vs.Str().noneable()).is_noneable)
 
+    # A frozen child may extend a enum with its value as candidate.
+    self.assertEqual(
+        vs.Str().freeze('a').extend(vs.Enum(2, [2, 'a'])),
+        vs.Enum('a', [2, 'a']).freeze(),
+    )
+
     # Child cannot extend a base of different type.
     with self.assertRaisesRegex(
         TypeError, '.* cannot extend .*: incompatible type.'):
@@ -276,6 +305,11 @@ class StrTest(ValueSpecTest):
         TypeError, '.* cannot extend .*: None is not allowed in base spec.'):
       vs.Str().noneable().extend(vs.Str())
 
+    # Child cannot extend a non-noneable base to noneable.
+    with self.assertRaisesRegex(
+        TypeError, '.* cannot extend .* with incompatible frozen value'):
+      vs.Str().freeze('b').extend(vs.Enum('a', ['a', False]))
+
   def test_freeze(self):
     self.assertFalse(vs.Str().frozen)
 
@@ -293,7 +327,7 @@ class StrTest(ValueSpecTest):
     self.assertEqual(v.default, 'foo')
 
     with self.assertRaisesRegex(
-        TypeError, 'Cannot extend a frozen value spec.'):
+        TypeError, '.* cannot extend a frozen value spec'):
       vs.Str().extend(v)
 
     with self.assertRaisesRegex(
@@ -307,6 +341,7 @@ class StrTest(ValueSpecTest):
     self.assert_json_conversion(vs.Str().noneable().freeze('abc'))
     self.assert_json_conversion_key(vs.Str(), 'pyglove.typing.Str')
 
+
 class IntTest(ValueSpecTest):
   """Tests for `Int`."""
 
@@ -377,6 +412,16 @@ class IntTest(ValueSpecTest):
         ValueError, '"max_value" must be equal or greater than "min_value".'):
       vs.Int(min_value=1, max_value=0)
 
+  def test_instantiation(self):
+    self.assertEqual(vs.Int()(1), 1)
+    self.assertEqual(vs.Int()(), 0)
+    self.assertIsNone(vs.Int().noneable()())
+    self.assertEqual(vs.Int().freeze(1)(0), 1)
+    with self.assertRaisesRegex(
+        ValueError, 'Value .* is out of range'
+    ):
+      vs.Int(min_value=1)()
+
   def test_apply(self):
     self.assertEqual(vs.Int().apply(1), 1)
     self.assertEqual(vs.Int(min_value=1, max_value=1).apply(1), 1)
@@ -434,6 +479,12 @@ class IntTest(ValueSpecTest):
         vs.Int(min_value=1),
     )
 
+    # A frozen child may extend a enum with its value as candidate.
+    self.assertEqual(
+        vs.Int().freeze(2).extend(vs.Enum(2, [2, 'a'])),
+        vs.Enum(2, [2, 'a']).freeze(),
+    )
+
     with self.assertRaisesRegex(TypeError,
                                 '.* cannot extend .*: incompatible type.'):
       vs.Int().extend(vs.Bool())
@@ -466,6 +517,11 @@ class IntTest(ValueSpecTest):
         TypeError, '.* cannot extend .*: no compatible type found in Union.'):
       vs.Int().extend(vs.Union([vs.Bool(), vs.Str()]))
 
+    # Child cannot extend a non-noneable base to noneable.
+    with self.assertRaisesRegex(
+        TypeError, '.* cannot extend .* with incompatible frozen value'):
+      vs.Int().freeze(1).extend(vs.Enum('a', ['a', False]))
+
   def test_freeze(self):
     self.assertFalse(vs.Int().frozen)
 
@@ -483,7 +539,7 @@ class IntTest(ValueSpecTest):
     self.assertEqual(v.default, 1)
 
     with self.assertRaisesRegex(
-        TypeError, 'Cannot extend a frozen value spec.'):
+        TypeError, '.* cannot extend a frozen value spec'):
       vs.Int().extend(v)
 
     with self.assertRaisesRegex(
@@ -571,6 +627,16 @@ class FloatTest(ValueSpecTest):
         ValueError, '"max_value" must be equal or greater than "min_value".'):
       vs.Float(min_value=1., max_value=0.)
 
+  def test_instantiation(self):
+    self.assertEqual(vs.Float()(1), 1.0)
+    self.assertEqual(vs.Float()(), 0.0)
+    self.assertIsNone(vs.Float().noneable()())
+    self.assertEqual(vs.Float().freeze(1.0)(0), 1.0)
+    with self.assertRaisesRegex(
+        ValueError, 'Value .* is out of range'
+    ):
+      vs.Float(min_value=1)()
+
   def test_apply(self):
     self.assertEqual(vs.Float().apply(1.), 1.)
     self.assertEqual(vs.Float().apply(1), 1.)
@@ -617,6 +683,12 @@ class FloatTest(ValueSpecTest):
     # Child may extend a noneable base into non-noneable.
     self.assertFalse(vs.Float().extend(vs.Float().noneable()).is_noneable)
 
+    # A frozen child may extend a enum with its value as candidate.
+    self.assertEqual(
+        vs.Float().freeze(2.5).extend(vs.Enum(2.5, [2.5, 'a'])),
+        vs.Enum(2.5, [2.5, 'a']).freeze(),
+    )
+
     with self.assertRaisesRegex(
         TypeError, '.* cannot extend .*: incompatible type.'):
       vs.Float().extend(vs.Int())
@@ -645,6 +717,11 @@ class FloatTest(ValueSpecTest):
         'min_value .* is greater than max_value .* after extension'):
       vs.Float(min_value=1.).extend(vs.Float(max_value=0.))
 
+    # Child cannot extend a non-noneable base to noneable.
+    with self.assertRaisesRegex(
+        TypeError, '.* cannot extend .* with incompatible frozen value'):
+      vs.Float().freeze(1.0).extend(vs.Enum('a', ['a', False]))
+
   def test_freeze(self):
     self.assertFalse(vs.Float().frozen)
 
@@ -662,7 +739,7 @@ class FloatTest(ValueSpecTest):
     self.assertEqual(v.default, 1.0)
 
     with self.assertRaisesRegex(
-        TypeError, 'Cannot extend a frozen value spec.'):
+        TypeError, '.* cannot extend a frozen value spec'):
       vs.Float().extend(v)
 
     with self.assertRaisesRegex(
@@ -768,6 +845,11 @@ class EnumTest(ValueSpecTest):
         ValueError, 'Enum default value \'a\' is not in candidate list.'):
       vs.Enum('a', ['b'])
 
+  def test_instantiation(self):
+    self.assertEqual(vs.Enum(1, [1, 2, 3])(), 1)
+    self.assertEqual(vs.Enum(1, [1, 2, 3])(2), 2)
+    self.assertEqual(vs.Enum(1, [1, 2, 3]).freeze(2)(3), 2)
+
   def test_apply(self):
     self.assertEqual(vs.Enum('a', ['a']).apply('a'), 'a')
     self.assertIsNone(vs.Enum('a', ['a', None]).apply(None))
@@ -784,6 +866,8 @@ class EnumTest(ValueSpecTest):
     self.assertTrue(
         vs.Enum(0, [0, 1]).is_compatible(vs.Enum(0, [0, 1])))
     self.assertTrue(vs.Enum(0, [0, 1]).is_compatible(vs.Enum(0, [0])))
+    self.assertTrue(vs.Enum(0, [0, 'a']).is_compatible(vs.Int().freeze(0)))
+    self.assertTrue(vs.Enum(0, [0, 'a']).is_compatible(vs.Str().freeze('a')))
     self.assertFalse(vs.Enum(0, [0]).is_compatible(vs.Enum(0, [0, 1])))
     self.assertFalse(vs.Enum(0, [0]).is_compatible(vs.Int()))
 
@@ -814,7 +898,7 @@ class EnumTest(ValueSpecTest):
     self.assertEqual(v.default, 'a')
 
     with self.assertRaisesRegex(
-        TypeError, 'Cannot extend a frozen value spec.'):
+        TypeError, '.* cannot extend a frozen value spec'):
       vs.Enum('c', ['a', 'b', 'c']).extend(v)
 
   def test_json_conversion(self):
@@ -942,15 +1026,21 @@ class ListTest(ValueSpecTest):
         'Either "size" or "min_size"/"max_size" pair can be specified.'):
       vs.List(vs.Int(), size=5, min_size=1)
 
+  def test_instantiation(self):
+    self.assertEqual(vs.List(vs.Int())([1]), [1])
+    self.assertEqual(vs.List(vs.Int())(), [])
+    self.assertIsNone(vs.List(vs.Int()).noneable()())
+    self.assertEqual(vs.List(vs.Int()).freeze([0])([]), [0])
+
   def test_apply(self):
     self.assertEqual(vs.List(vs.Int()).apply([]), [])
     self.assertEqual(vs.List(vs.Int()).apply([1]), [1])
     self.assertEqual(vs.List(vs.Int().noneable()).apply([1, None]), [1, None])
     # Automatic conversion: str -> KeyPath is a registered conversion.
     # See 'type_conversion.py'.
-    l = vs.List(vs.Object(object_utils.KeyPath)).apply(['a.b.c'])
-    self.assertIsInstance(l[0], object_utils.KeyPath)
-    self.assertEqual(l, [object_utils.KeyPath.parse('a.b.c')])
+    l = vs.List(vs.Object(utils.KeyPath)).apply(['a.b.c'])
+    self.assertIsInstance(l[0], utils.KeyPath)
+    self.assertEqual(l, [utils.KeyPath.parse('a.b.c')])
     self.assertEqual(
         vs.List(vs.Int()).apply(
             typed_missing.MISSING_VALUE, allow_partial=True),
@@ -1107,7 +1197,7 @@ class ListTest(ValueSpecTest):
     self.assertEqual(v.default, [1])
 
     with self.assertRaisesRegex(
-        TypeError, 'Cannot extend a frozen value spec.'):
+        TypeError, '.* cannot extend a frozen value spec'):
       vs.List(vs.Int()).extend(v)
 
     with self.assertRaisesRegex(
@@ -1301,6 +1391,12 @@ class TupleTest(ValueSpecTest):
         '<(type|class) \'int\'>.'):
       vs.Tuple([vs.Int()], default=1)
 
+  def test_instantiation(self):
+    self.assertEqual(vs.Tuple(vs.Int())([1]), (1,))
+    self.assertEqual(vs.Tuple(vs.Int())(), ())
+    self.assertIsNone(vs.Tuple(vs.Int()).noneable()())
+    self.assertEqual(vs.Tuple(vs.Int()).freeze((0,))((1, 2)), (0,))
+
   def test_apply(self):
     self.assertEqual(vs.Tuple(vs.Int()).apply(tuple()), tuple())
     self.assertEqual(vs.Tuple(vs.Int()).apply((1, 1, 1)), (1, 1, 1))
@@ -1533,7 +1629,7 @@ class TupleTest(ValueSpecTest):
     self.assertEqual(v.default, (1,))
 
     with self.assertRaisesRegex(
-        TypeError, 'Cannot extend a frozen value spec.'):
+        TypeError, '.* cannot extend a frozen value spec'):
       vs.Tuple(vs.Int()).extend(v)
 
     with self.assertRaisesRegex(
@@ -1756,6 +1852,12 @@ class DictTest(ValueSpecTest):
         'should be a dict of objects.'):
       vs.Dict([('key', 1, 'field 1', 123)])
 
+  def test_instantiation(self):
+    self.assertEqual(vs.Dict()(), {})
+    self.assertEqual(vs.Dict()({'x': 1, 2: 2}), {'x': 1, 2: 2})
+    self.assertEqual(vs.Dict()(x=1), dict(x=1))
+    self.assertEqual(vs.Dict({'a': int, 'b': 1})(a=1), dict(a=1, b=1))
+
   def test_apply(self):
     self.assertEqual(vs.Dict().apply({'a': 1}), {'a': 1})
     self.assertEqual(
@@ -1943,7 +2045,7 @@ class DictTest(ValueSpecTest):
     x = vs.Dict([
         ('a', int, 'field 1', dict(x=1)),
     ]).freeze(dict(a=1))
-    y = object_utils.from_json(x.to_json())
+    y = utils.from_json(x.to_json())
     self.assert_json_conversion(
         vs.Dict([
             ('a', int, 'field 1', dict(x=1)),
@@ -1986,7 +2088,7 @@ class ObjectTest(ValueSpecTest):
     class C(A):
       pass
 
-    class D(C, object_utils.MaybePartial):
+    class D(C, utils.MaybePartial):
 
       def missing_values(self):
         return {'SOME_KEY': 'SOME_VALUE'}
@@ -2108,6 +2210,10 @@ class ObjectTest(ValueSpecTest):
         TypeError, '<(type|class) \'object\'> is too general for Object spec.'):
       vs.Object(object)
 
+  def test_instantiation(self):
+    self.assertIsInstance(vs.Object(self.A)(), self.A)
+    self.assertIsInstance(vs.Object(self.B)(1), self.B)
+
   def test_apply(self):
     a = self.A()
     self.assertEqual(vs.Object(self.A).apply(a), a)
@@ -2230,7 +2336,7 @@ class ObjectTest(ValueSpecTest):
     self.assertIs(v.default, b)
 
     with self.assertRaisesRegex(
-        TypeError, 'Cannot extend a frozen value spec.'):
+        TypeError, '.* cannot extend a frozen value spec'):
       vs.Object(self.A).extend(v)
 
     with self.assertRaisesRegex(
@@ -2271,7 +2377,7 @@ class CallableTest(ValueSpecTest):
 
   def test_value_type(self):
     self.assertIsNone(vs.Callable().value_type)
-    self.assertEqual(vs.Functor().annotation, object_utils.Functor)
+    self.assertEqual(vs.Functor().annotation, utils.Functor)
 
   def test_forward_refs(self):
     self.assertEqual(vs.Callable().forward_refs, set())
@@ -2427,6 +2533,10 @@ class CallableTest(ValueSpecTest):
         TypeError, '.* only take 0 positional arguments, while 1 is required'):
       vs.Callable([vs.Int()]).apply(f)
 
+  def test_instantiation(self):
+    with self.assertRaisesRegex(TypeError, '.* cannot be instantiated'):
+      vs.Callable()()
+
   def test_apply_on_callable_object(self):
 
     class CallableObject:
@@ -2473,7 +2583,7 @@ class CallableTest(ValueSpecTest):
 
   def test_apply_on_functor(self):
 
-    class FunctorWithRegularArgs(object_utils.Functor):
+    class FunctorWithRegularArgs(utils.Functor):
 
       __signature__ = Signature(
           callable_type=callable_signature.CallableType.FUNCTION,
@@ -2519,7 +2629,7 @@ class CallableTest(ValueSpecTest):
 
   def test_apply_on_functor_with_varargs(self):
 
-    class FunctorWithVarArgs(object_utils.Functor):
+    class FunctorWithVarArgs(utils.Functor):
 
       __signature__ = Signature(
           callable_type=callable_signature.CallableType.FUNCTION,
@@ -2652,7 +2762,7 @@ class CallableTest(ValueSpecTest):
     self.assertIs(v.default, f)
 
     with self.assertRaisesRegex(
-        TypeError, 'Cannot extend a frozen value spec.'):
+        TypeError, '.* cannot extend a frozen value spec'):
       vs.Callable().extend(v)
 
     with self.assertRaisesRegex(
@@ -2670,7 +2780,7 @@ class CallableTest(ValueSpecTest):
         )
     )
     x = vs.Callable([vs.Int()], default=lambda x: x + 1).noneable()
-    y = object_utils.from_json(x.to_json())
+    y = utils.from_json(x.to_json())
     self.assert_json_conversion(
         vs.Callable([vs.Int()], default=lambda x: x + 1).noneable()
     )
@@ -2797,6 +2907,9 @@ class TypeTest(ValueSpecTest):
     self.assertNotEqual(
         vs.Type(Exception), vs.Type(Exception, default=ValueError))
 
+  def test_instantiate(self):
+    self.assertIs(vs.Type[str](), str)
+
   def test_apply(self):
     self.assertEqual(vs.Type(Exception).apply(Exception), Exception)
     self.assertEqual(vs.Type(Exception).apply(ValueError), ValueError)
@@ -2904,7 +3017,7 @@ class TypeTest(ValueSpecTest):
     self.assertIs(v.default, e)
 
     with self.assertRaisesRegex(
-        TypeError, 'Cannot extend a frozen value spec.'):
+        TypeError, '.* cannot extend a frozen value spec'):
       vs.Type(Exception).extend(v)
 
     with self.assertRaisesRegex(
@@ -3111,6 +3224,12 @@ class UnionTest(ValueSpecTest):
         vs.Union([vs.Callable(), vs.Int()]).get_candidate(vs.Any()),
         vs.Callable())
 
+  def test_instantiate(self):
+    with self.assertRaisesRegex(
+        TypeError, '.* cannot be instantiated'
+    ):
+      vs.Union[int, str]()
+
   def test_apply(self):
     self.assertEqual(vs.Union([vs.Int(), vs.Str()]).apply(1), 1)
     self.assertEqual(
@@ -3261,7 +3380,7 @@ class UnionTest(ValueSpecTest):
     self.assertEqual(v.default, 'foo')
 
     with self.assertRaisesRegex(
-        TypeError, 'Cannot extend a frozen value spec.'):
+        TypeError, '.* cannot extend a frozen value spec.'):
       vs.Str().extend(v)
 
     with self.assertRaisesRegex(
@@ -3343,6 +3462,10 @@ class AnyTest(ValueSpecTest):
     self.assertNotEqual(vs.Any(), vs.Int())
     self.assertNotEqual(vs.Any(True), vs.Any())
 
+  def test_instantiate(self):
+    with self.assertRaisesRegex(TypeError, '.* cannot be instantiated'):
+      vs.Any()()
+
   def test_apply(self):
     self.assertEqual(vs.Any().apply(True), True)
     self.assertEqual(vs.Any().apply(1), 1)
@@ -3392,7 +3515,7 @@ class AnyTest(ValueSpecTest):
     self.assertEqual(v.default, 'foo')
 
     with self.assertRaisesRegex(
-        TypeError, 'Cannot extend a frozen value spec.'):
+        TypeError, '.* cannot extend a frozen value spec'):
       vs.Any().extend(v)
 
     with self.assertRaisesRegex(

pyglove/core/utils/__init__.py

@@ -0,0 +1,172 @@
+# Copyright 2022 The PyGlove Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# pylint: disable=line-too-long
+"""Utility library that provides common traits for objects in Python.
+
+Overview
+--------
+
+``pg.utils`` sits at the bottom of all PyGlove modules and empowers other
+modules with the following features:
+
+  +---------------------+--------------------------------------------+
+  | Functionality       | API                                        |
+  +=====================+============================================+
+  | Formatting          | :class:`pg.Formattable`,                   |
+  |                     |                                            |
+  |                     | :func:`pg.format`,                         |
+  |                     |                                            |
+  |                     | :func:`pg.print`,                          |
+  |                     |                                            |
+  |                     | :func:`pg.utils.kvlist_str`,        |
+  |                     |                                            |
+  |                     | :func:`pg.utils.quote_if_str`,      |
+  |                     |                                            |
+  |                     | :func:`pg.utils.message_on_path`    |
+  +---------------------+--------------------------------------------+
+  | Serialization       | :class:`pg.JSONConvertible`,               |
+  |                     |                                            |
+  |                     | :func:`pg.registered_types`,               |
+  |                     |                                            |
+  |                     | :func:`pg.utils.to_json`,           |
+  |                     |                                            |
+  |                     | :func:`pg.utils.from_json`,         |
+  +---------------------+--------------------------------------------+
+  | Partial construction| :class:`pg.MaybePartial`,                  |
+  |                     |                                            |
+  |                     | :const:`pg.MISSING_VALUE`.                 |
+  +---------------------+--------------------------------------------+
+  | Hierarchical key    | :class:`pg.KeyPath`                        |
+  | representation      |                                            |
+  +---------------------+--------------------------------------------+
+  | Hierarchical object | :func:`pg.utils.traverse`           |
+  | traversal           |                                            |
+  +---------------------+--------------------------------------------+
+  | Hierarchical object | :func:`pg.utils.transform`,         |
+  | transformation      |                                            |
+  |                     | :func:`pg.utils.merge`,             |
+  |                     |                                            |
+  |                     | :func:`pg.utils.canonicalize`,      |
+  |                     |                                            |
+  |                     | :func:`pg.utils.flatten`            |
+  +---------------------+--------------------------------------------+
+  | Docstr handling     | :class:`pg.docstr`,                        |
+  +---------------------+--------------------------------------------+
+  | Error handling     | :class:`pg.catch_errors`,                   |
+  +---------------------+--------------------------------------------+
+"""
+# pylint: enable=line-too-long
+# pylint: disable=g-bad-import-order
+# pylint: disable=g-importing-member
+
+# Handling JSON conversion.
+from pyglove.core.utils.json_conversion import Nestable
+from pyglove.core.utils.json_conversion import JSONValueType
+
+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
+from pyglove.core.utils.json_conversion import registered_types
+
+# Handling formatting.
+from pyglove.core.utils.formatting import Formattable
+from pyglove.core.utils.formatting import format  # pylint: disable=redefined-builtin
+from pyglove.core.utils.formatting import printv as print  # pylint: disable=redefined-builtin
+from pyglove.core.utils.formatting import kvlist_str
+from pyglove.core.utils.formatting import quote_if_str
+from pyglove.core.utils.formatting import maybe_markdown_quote
+from pyglove.core.utils.formatting import comma_delimited_str
+from pyglove.core.utils.formatting import camel_to_snake
+from pyglove.core.utils.formatting import auto_plural
+from pyglove.core.utils.formatting import BracketType
+from pyglove.core.utils.formatting import bracket_chars
+from pyglove.core.utils.formatting import RawText
+
+# Context managers for defining the default format for __str__ and __repr__.
+from pyglove.core.utils.formatting import str_format
+from pyglove.core.utils.formatting import repr_format
+
+# Value location.
+from pyglove.core.utils.value_location import KeyPath
+from pyglove.core.utils.value_location import KeyPathSet
+from pyglove.core.utils.value_location import StrKey
+from pyglove.core.utils.value_location import message_on_path
+
+# Value markers.
+from pyglove.core.utils.missing import MissingValue
+from pyglove.core.utils.missing import MISSING_VALUE
+
+# Handling hierarchical.
+from pyglove.core.utils.hierarchical import traverse
+from pyglove.core.utils.hierarchical import transform
+from pyglove.core.utils.hierarchical import flatten
+from pyglove.core.utils.hierarchical import canonicalize
+from pyglove.core.utils.hierarchical import merge
+from pyglove.core.utils.hierarchical import merge_tree
+from pyglove.core.utils.hierarchical import is_partial
+from pyglove.core.utils.hierarchical import try_listify_dict_with_int_keys
+
+# Common traits.
+from pyglove.core.utils.common_traits import MaybePartial
+from pyglove.core.utils.common_traits import Functor
+
+from pyglove.core.utils.common_traits import explicit_method_override
+from pyglove.core.utils.common_traits import ensure_explicit_method_override
+
+# Handling thread local values.
+from pyglove.core.utils.thread_local import thread_local_value_scope
+from pyglove.core.utils.thread_local import thread_local_has
+from pyglove.core.utils.thread_local import thread_local_set
+from pyglove.core.utils.thread_local import thread_local_get
+from pyglove.core.utils.thread_local import thread_local_del
+from pyglove.core.utils.thread_local import thread_local_increment
+from pyglove.core.utils.thread_local import thread_local_decrement
+from pyglove.core.utils.thread_local import thread_local_push
+from pyglove.core.utils.thread_local import thread_local_pop
+from pyglove.core.utils.thread_local import thread_local_peek
+
+# Handling docstrings.
+from pyglove.core.utils.docstr_utils import DocStr
+from pyglove.core.utils.docstr_utils import DocStrStyle
+from pyglove.core.utils.docstr_utils import DocStrEntry
+from pyglove.core.utils.docstr_utils import DocStrExample
+from pyglove.core.utils.docstr_utils import DocStrArgument
+from pyglove.core.utils.docstr_utils import DocStrReturns
+from pyglove.core.utils.docstr_utils import DocStrRaises
+from pyglove.core.utils.docstr_utils import docstr
+
+# Handling exceptions.
+from pyglove.core.utils.error_utils import catch_errors
+from pyglove.core.utils.error_utils import CatchErrorsContext
+from pyglove.core.utils.error_utils import ErrorInfo
+
+# Timing.
+from pyglove.core.utils.timing import timeit
+from pyglove.core.utils.timing import TimeIt
+
+# Value override from context manager.
+from pyglove.core.utils.contextual import ContextualOverride
+from pyglove.core.utils.contextual import contextual_override
+from pyglove.core.utils.contextual import with_contextual_override
+from pyglove.core.utils.contextual import get_contextual_override
+from pyglove.core.utils.contextual import contextual_value
+from pyglove.core.utils.contextual import all_contextual_values
+
+# Text color.
+from pyglove.core.utils.text_color import colored
+from pyglove.core.utils.text_color import colored_block
+from pyglove.core.utils.text_color import decolor
+
+# pylint: enable=g-importing-member
+# pylint: enable=g-bad-import-order

pyglove/core/{object_utils → utils}/common_traits.py

@@ -18,7 +18,7 @@ object, for example, partiality (MaybePartial), functor (Functor).
 """
 
 import abc
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, Union
 
 
 class MaybePartial(metaclass=abc.ABCMeta):
@@ -47,7 +47,7 @@ class MaybePartial(metaclass=abc.ABCMeta):
     return len(self.missing_values()) > 0  # pylint: disable=g-explicit-length-test
 
   @abc.abstractmethod
-  def missing_values(self, flatten: bool = True) -> Dict[str, Any]:  # pylint: disable=redefined-outer-name
+  def missing_values(self, flatten: bool = True) -> Dict[Union[str, int], Any]:  # pylint: disable=redefined-outer-name
     """Returns missing values from this object.
 
     Args:

pyglove/core/{object_utils → utils}/common_traits_test.py

@@ -11,10 +11,8 @@
 # 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.object_utils.common_traits."""
-
 import unittest
-from pyglove.core.object_utils import common_traits
+from pyglove.core.utils import common_traits
 
 
 class ExplicitlyOverrideTest(unittest.TestCase):