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

pyglove/core/typing/value_specs_test.py

@@ -11,33 +11,35 @@
 # 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.value_specs."""
-
 import contextlib
+import datetime
+import inspect
 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
 from pyglove.core.typing import custom_typing
-from pyglove.core.typing import inspect as pg_inspect
-from pyglove.core.typing import typed_missing
 from pyglove.core.typing import key_specs as ks
+from pyglove.core.typing import typed_missing
 from pyglove.core.typing import value_specs as vs
 
 
+Argument = callable_signature.Argument
+Signature = callable_signature.Signature
+
+
 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):
@@ -60,15 +62,15 @@ class BoolTest(ValueSpecTest):
     self.assertFalse(vs.Bool().is_noneable)
     self.assertTrue(vs.Bool().noneable().is_noneable)
 
-  def test_str(self):
-    self.assertEqual(str(vs.Bool()), 'Bool()')
-    self.assertEqual(str(vs.Bool(True)), 'Bool(default=True)')
-    self.assertEqual(str(vs.Bool(True).freeze()),
+  def test_repr(self):
+    self.assertEqual(repr(vs.Bool()), 'Bool()')
+    self.assertEqual(repr(vs.Bool(True)), 'Bool(default=True)')
+    self.assertEqual(repr(vs.Bool(True).freeze()),
                      'Bool(default=True, frozen=True)')
     self.assertEqual(
-        str(vs.Bool().noneable()), 'Bool(default=None, noneable=True)')
+        repr(vs.Bool().noneable()), 'Bool(default=None, noneable=True)')
     self.assertEqual(
-        str(vs.Bool(True).noneable()), 'Bool(default=True, noneable=True)')
+        repr(vs.Bool(True).noneable()), 'Bool(default=True, noneable=True)')
 
   def test_annotation(self):
     self.assertEqual(vs.Bool().annotation, bool)
@@ -96,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))
@@ -114,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.'):
@@ -124,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)
 
@@ -141,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(
@@ -193,14 +213,14 @@ class StrTest(ValueSpecTest):
     self.assertFalse(vs.Str().is_noneable)
     self.assertTrue(vs.Str().noneable().is_noneable)
 
-  def test_str(self):
-    self.assertEqual(str(vs.Str()), 'Str()')
+  def test_repr(self):
+    self.assertEqual(repr(vs.Str()), 'Str()')
     self.assertEqual(
-        str(vs.Str().noneable()), 'Str(default=None, noneable=True)')
-    self.assertEqual(str(vs.Str('a')), 'Str(default=\'a\')')
-    self.assertEqual(str(vs.Str('a').freeze()),
+        repr(vs.Str().noneable()), 'Str(default=None, noneable=True)')
+    self.assertEqual(repr(vs.Str('a')), 'Str(default=\'a\')')
+    self.assertEqual(repr(vs.Str('a').freeze()),
                      'Str(default=\'a\', frozen=True)')
-    self.assertEqual(str(vs.Str(regex='.*')), 'Str(regex=\'.*\')')
+    self.assertEqual(repr(vs.Str(regex='.*')), 'Str(regex=\'.*\')')
 
   def test_annotation(self):
     self.assertEqual(vs.Str().annotation, str)
@@ -221,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')
@@ -263,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.'):
@@ -273,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)
 
@@ -290,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(
@@ -304,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`."""
 
@@ -334,17 +372,17 @@ class IntTest(ValueSpecTest):
     self.assertFalse(vs.Int().is_noneable)
     self.assertTrue(vs.Int().noneable().is_noneable)
 
-  def test_str(self):
-    self.assertEqual(str(vs.Int()), 'Int()')
-    self.assertEqual(str(vs.Int(1)), 'Int(default=1)')
-    self.assertEqual(str(vs.Int(1).freeze()),
+  def test_repr(self):
+    self.assertEqual(repr(vs.Int()), 'Int()')
+    self.assertEqual(repr(vs.Int(1)), 'Int(default=1)')
+    self.assertEqual(repr(vs.Int(1).freeze()),
                      'Int(default=1, frozen=True)')
     self.assertEqual(
-        str(vs.Int().noneable()), 'Int(default=None, noneable=True)')
+        repr(vs.Int().noneable()), 'Int(default=None, noneable=True)')
     self.assertEqual(
-        str(vs.Int(1).noneable()), 'Int(default=1, noneable=True)')
+        repr(vs.Int(1).noneable()), 'Int(default=1, noneable=True)')
     self.assertEqual(
-        str(vs.Int(min_value=0, max_value=1)), 'Int(min=0, max=1)')
+        repr(vs.Int(min_value=0, max_value=1)), 'Int(min=0, max=1)')
 
   def test_annotation(self):
     self.assertEqual(vs.Int().annotation, int)
@@ -374,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)
@@ -431,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())
@@ -463,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)
 
@@ -480,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(
@@ -526,16 +585,16 @@ class FloatTest(ValueSpecTest):
     self.assertFalse(vs.Float().is_noneable)
     self.assertTrue(vs.Float().noneable().is_noneable)
 
-  def test_str(self):
+  def test_repr(self):
     self.assertEqual(str(vs.Float()), 'Float()')
     self.assertEqual(
-        str(vs.Float().noneable()), 'Float(default=None, noneable=True)')
+        repr(vs.Float().noneable()), 'Float(default=None, noneable=True)')
     self.assertEqual(
-        str(vs.Float(1.0).freeze()), 'Float(default=1.0, frozen=True)')
+        repr(vs.Float(1.0).freeze()), 'Float(default=1.0, frozen=True)')
     self.assertEqual(
-        str(vs.Float(1.0).noneable()), 'Float(default=1.0, noneable=True)')
+        repr(vs.Float(1.0).noneable()), 'Float(default=1.0, noneable=True)')
     self.assertEqual(
-        str(vs.Float(default=1., min_value=0., max_value=1.).noneable()),
+        repr(vs.Float(default=1., min_value=0., max_value=1.).noneable()),
         'Float(default=1.0, min=0.0, max=1.0, noneable=True)')
 
   def test_annotation(self):
@@ -568,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.)
@@ -614,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())
@@ -642,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)
 
@@ -659,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(
@@ -730,13 +810,13 @@ class EnumTest(ValueSpecTest):
         vs.Enum('a', ['a', 'b']).noneable(),
         vs.Enum('a', ['a', 'b', None]))
 
-  def test_str(self):
+  def test_repr(self):
     self.assertEqual(
-        str(vs.Enum('a', ['a', 'b', 'c'])),
+        repr(vs.Enum('a', ['a', 'b', 'c'])),
         'Enum(default=\'a\', values=[\'a\', \'b\', \'c\'])')
 
     self.assertEqual(
-        str(vs.Enum('a', ['a', 'b', 'c']).freeze()),
+        repr(vs.Enum('a', ['a', 'b', 'c']).freeze()),
         'Enum(default=\'a\', values=[\'a\', \'b\', \'c\'], frozen=True)')
 
   def test_annotation(self):
@@ -765,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))
@@ -781,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()))
 
@@ -791,7 +878,7 @@ class EnumTest(ValueSpecTest):
 
     # Child cannot extend a non-noneable base to noneable.
     with self.assertRaisesRegex(
-        TypeError, '.* cannot extend .*: values in base should be super set.'):
+        TypeError, '.* cannot extend .*: \'b\' is not an acceptable value.'):
       vs.Enum('a', ['a', 'b']).extend(vs.Enum('a', ['a']))
 
   def test_freeze(self):
@@ -811,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):
@@ -939,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),
@@ -1104,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(
@@ -1298,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))
@@ -1530,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(
@@ -1574,6 +1673,9 @@ class DictTest(ValueSpecTest):
         ('z', vs.Int(min_value=0, max_value=None), 'field z.', dict(foo=1))
     ]))
 
+    self.assertEqual(vs.Dict(vs.Int()), vs.Dict([(ks.StrKey(), vs.Int())]))
+    self.assertEqual(vs.Dict(int), vs.Dict([(ks.StrKey(), vs.Int())]))
+
     with self.assertRaisesRegex(
         TypeError,
         '`pg.typing.Dict` accepts 1 dict type argument as the schema'):
@@ -1657,7 +1759,12 @@ class DictTest(ValueSpecTest):
                 ('b', 1, 'field 1'),
                 ('a', vs.Str(), 'field 2'),
             ]).noneable()),
-        'Dict({b=Int(default=1), a=Str()}, noneable=True)')
+        (
+            'Dict(fields=[Field(key=b, value=Int(default=1), '
+            'description=\'field 1\'), Field(key=a, value=Str(), '
+            'description=\'field 2\')], noneable=True)'
+        )
+    )
 
     self.assertEqual(
         repr(
@@ -1665,7 +1772,42 @@ class DictTest(ValueSpecTest):
                 ('b', 1, 'field 1'),
                 ('a', vs.Str('abc'), 'field 2'),
             ]).freeze()),
-        'Dict({b=Int(default=1), a=Str(default=\'abc\')}, frozen=True)')
+        (
+            'Dict(fields=[Field(key=b, value=Int(default=1), '
+            'description=\'field 1\'), Field(key=a, '
+            'value=Str(default=\'abc\'), description=\'field 2\')], '
+            'frozen=True)'
+        )
+    )
+
+  def test_str(self):
+    self.assertEqual(str(vs.Dict()), 'Dict()')
+    self.assertEqual(
+        str(
+            vs.Dict([
+                ('b', 1, 'field 1'),
+                ('a', vs.Str(), 'field 2'),
+            ]).noneable()),
+        inspect.cleandoc('''
+        Dict(
+          fields=[
+            Field(
+              key=b,
+              value=Int(
+                default=1
+              ),
+              description='field 1'
+            ),
+            Field(
+              key=a,
+              value=Str(),
+              description='field 2'
+            )
+          ],
+          noneable=True
+        )
+        ''')
+    )
 
   def test_annotation(self):
     self.assertEqual(vs.Dict().annotation, typing.Dict[str, typing.Any])
@@ -1695,11 +1837,6 @@ class DictTest(ValueSpecTest):
         vs.Dict(class_schema.create_schema([('a', vs.Int())])),
         vs.Dict([('a', vs.Int())]))
 
-    with self.assertRaisesRegex(
-        TypeError,
-        'Schema definition should be a dict .* a list .*'):
-      vs.Dict(int)
-
     with self.assertRaisesRegex(
         TypeError, 'The 1st element of field definition should be of '
         '<(type|class) \'str\'>'):
@@ -1715,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(
@@ -1902,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)),
@@ -1945,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'}
@@ -2001,6 +2144,8 @@ class ObjectTest(ValueSpecTest):
   def test_forward_refs(self):
     self.assertEqual(vs.Object(self.A).forward_refs, set())
     self.assertEqual(vs.Object('Foo').forward_refs, set([forward_ref('Foo')]))
+    self.assertEqual(
+        vs.Object(forward_ref('Foo')).forward_refs, set([forward_ref('Foo')]))
 
   def test_default(self):
     self.assertEqual(vs.Object(self.A).default, typed_missing.MISSING_VALUE)
@@ -2012,14 +2157,14 @@ class ObjectTest(ValueSpecTest):
     self.assertTrue(vs.Object(self.A).noneable().is_noneable)
     self.assertTrue(vs.Object('Foo').noneable().is_noneable)
 
-  def test_str(self):
-    self.assertEqual(str(vs.Object(self.A)), 'Object(A)')
-    self.assertEqual(str(vs.Object('Foo')), 'Object(Foo)')
+  def test_repr(self):
+    self.assertEqual(repr(vs.Object(self.A)), 'Object(A)')
+    self.assertEqual(repr(vs.Object('Foo')), 'Object(Foo)')
     self.assertEqual(
-        str(vs.Object(self.A).noneable()),
+        repr(vs.Object(self.A).noneable()),
         'Object(A, default=None, noneable=True)')
     self.assertEqual(
-        str(vs.Object(self.A).noneable().freeze()),
+        repr(vs.Object(self.A).noneable().freeze()),
         'Object(A, default=None, noneable=True, frozen=True)')
 
   def test_annotation(self):
@@ -2065,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)
@@ -2187,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(
@@ -2228,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())
@@ -2268,10 +2417,10 @@ class CallableTest(ValueSpecTest):
     self.assertFalse(vs.Callable().is_noneable)
     self.assertTrue(vs.Callable().noneable().is_noneable)
 
-  def test_str(self):
-    self.assertEqual(str(vs.Callable()), 'Callable()')
+  def test_repr(self):
+    self.assertEqual(repr(vs.Callable()), 'Callable()')
     self.assertEqual(
-        str(
+        repr(
             vs.Callable(
                 args=[vs.Int(), vs.Int()],
                 kw=[('a', vs.Str().noneable())],
@@ -2279,7 +2428,7 @@ class CallableTest(ValueSpecTest):
         'Callable(args=[Int(), Int()], kw=[(\'a\', '
         'Str(default=None, noneable=True))], returns=Int())')
     self.assertEqual(
-        str(
+        repr(
             vs.Callable(
                 args=[vs.Int(), vs.Int()],
                 kw=[('a', vs.Str().noneable())],
@@ -2384,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:
@@ -2430,15 +2583,15 @@ class CallableTest(ValueSpecTest):
 
   def test_apply_on_functor(self):
 
-    class FunctorWithRegularArgs(object_utils.Functor):
+    class FunctorWithRegularArgs(utils.Functor):
 
-      __signature__ = callable_signature.Signature(
+      __signature__ = Signature(
           callable_type=callable_signature.CallableType.FUNCTION,
           name='foo',
           module_name='__main__',
           args=[
-              callable_signature.Argument('a', vs.Int()),
-              callable_signature.Argument('b', vs.Str())
+              Argument('a', Argument.Kind.POSITIONAL_OR_KEYWORD, vs.Int()),
+              Argument('b', Argument.Kind.POSITIONAL_OR_KEYWORD, vs.Str()),
           ])
 
       def __init__(self, value):
@@ -2476,18 +2629,28 @@ class CallableTest(ValueSpecTest):
 
   def test_apply_on_functor_with_varargs(self):
 
-    class FunctorWithVarArgs(object_utils.Functor):
+    class FunctorWithVarArgs(utils.Functor):
 
-      __signature__ = callable_signature.Signature(
+      __signature__ = Signature(
           callable_type=callable_signature.CallableType.FUNCTION,
           name='foo',
           module_name='__main__',
           args=[
-              callable_signature.Argument('a', vs.Int()),
-              callable_signature.Argument('b', vs.Str())
+              Argument(
+                  'a', Argument.Kind.POSITIONAL_OR_KEYWORD, vs.Int()
+              ),
+              Argument(
+                  'b', Argument.Kind.POSITIONAL_OR_KEYWORD, vs.Str()
+              )
           ],
-          varargs=callable_signature.Argument('args', vs.Int()),
-          varkw=callable_signature.Argument('kwargs', vs.Int()),
+          varargs=Argument(
+              'args', Argument.Kind.VAR_POSITIONAL, vs.List(vs.Int())
+          ),
+          varkw=Argument(
+              'kwargs',
+              Argument.Kind.VAR_KEYWORD,
+              vs.Dict([(ks.StrKey(), vs.Int())])
+          ),
           return_value=vs.Object(ValueError))
 
       def __init__(self, value):
@@ -2599,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(
@@ -2617,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()
     )
@@ -2699,14 +2862,16 @@ class TypeTest(ValueSpecTest):
     self.assertFalse(vs.Type(Exception).is_noneable)
     self.assertTrue(vs.Type(Exception).noneable().is_noneable)
 
-  def test_str(self):
-    self.assertEqual(str(vs.Type(Exception)), 'Type(<class \'Exception\'>)')
+  def test_repr(self):
+    self.assertEqual(repr(vs.Type(Exception)), 'Type(<class \'Exception\'>)')
     self.assertEqual(
-        str(vs.Type(Exception).noneable()),
-        'Type(<class \'Exception\'>, default=None, noneable=True)')
+        repr(vs.Type(Exception).noneable()),
+        'Type(<class \'Exception\'>, default=None, noneable=True)'
+    )
     self.assertEqual(
-        str(vs.Type(Exception).noneable().freeze()),
-        'Type(<class \'Exception\'>, default=None, noneable=True, frozen=True)')
+        repr(vs.Type(Exception).noneable().freeze()),
+        'Type(<class \'Exception\'>, default=None, noneable=True, frozen=True)'
+    )
 
   def test_annotation(self):
     self.assertEqual(vs.Type(Exception).annotation, typing.Type[Exception])
@@ -2742,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)
@@ -2849,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(
@@ -3056,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(
@@ -3085,6 +3259,15 @@ class UnionTest(ValueSpecTest):
       with self.assertRaisesRegex(TypeError, 'Expect .* but encountered .*'):
         _ = v.apply('foo')
 
+    # Union with strong-type and non-strong-type candidates.
+    self.assertEqual(
+        vs.Union([typing.Callable[[int], int], str]).apply('foo'), 'foo'
+    )
+    # Union with type conversion.
+    self.assertIsInstance(
+        vs.Union([int, str]).apply(datetime.datetime.now()), int
+    )
+
     # Bad cases.
     with self.assertRaisesRegex(ValueError, 'Value cannot be None'):
       vs.Union([vs.Int(), vs.Str()]).apply(None)
@@ -3093,6 +3276,11 @@ class UnionTest(ValueSpecTest):
         TypeError, 'Expect \\(.*\\) but encountered <(type|class) \'list\'>.'):
       vs.Union([vs.Int(), vs.Str()]).apply([])
 
+    with self.assertRaisesRegex(
+        TypeError, '1 does not match any candidate of .*'
+    ):
+      vs.Union([typing.Callable[[int], int], str]).apply(1)
+
   def test_is_compatible(self):
     self.assertTrue(
         vs.Union([vs.Int(), vs.Bool()]).is_compatible(
@@ -3160,7 +3348,7 @@ class UnionTest(ValueSpecTest):
 
     # Test enum of different values cannot be extended.
     with self.assertRaisesRegex(
-        TypeError, '.* cannot extend .*: values in base should be super set.'):
+        TypeError, '.* cannot extend .*: 1 is not an acceptable value'):
       vs.Union([vs.Enum(1, [1, 2]), vs.Int()]).extend(
           vs.Union([vs.Enum('a', ['a', 'b']), vs.Int()]))
 
@@ -3192,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(
@@ -3249,10 +3437,17 @@ class AnyTest(ValueSpecTest):
   def test_noneable(self):
     self.assertTrue(vs.Any().is_noneable)
 
+  def test_repr(self):
+    self.assertEqual(repr(vs.Any()), 'Any()')
+    self.assertEqual(repr(vs.Any(1)), 'Any(default=1)')
+    self.assertEqual(repr(vs.Any(1).freeze()), 'Any(default=1, frozen=True)')
+
   def test_str(self):
     self.assertEqual(str(vs.Any()), 'Any()')
-    self.assertEqual(str(vs.Any(1)), 'Any(default=1)')
-    self.assertEqual(str(vs.Any(1).freeze()), 'Any(default=1, frozen=True)')
+    self.assertEqual(str(vs.Any(1)), 'Any(\n  default=1\n)')
+    self.assertEqual(
+        str(vs.Any(1).freeze()), 'Any(\n  default=1,\n  frozen=True\n)'
+    )
 
   def test_annotation(self):
     self.assertEqual(vs.Any().annotation, typed_missing.MISSING_VALUE)
@@ -3267,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)
@@ -3316,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(
@@ -3387,5 +3586,44 @@ def forward_ref(name):
   return class_schema.ForwardRef(sys.modules[__name__], name)
 
 
+class EnsureValueSpecTest(unittest.TestCase):
+  """Tests for `ensure_value_spec`."""
+
+  def test_basics(self):
+    self.assertEqual(
+        vs.ensure_value_spec(
+            vs.Int(min_value=1), vs.Int()),
+        vs.Int(min_value=1)
+    )
+
+    self.assertEqual(
+        vs.ensure_value_spec(
+            vs.Int(min_value=1), vs.Number(int)
+        ),
+        vs.Int(min_value=1)
+    )
+
+    with self.assertRaisesRegex(
+        TypeError, 'Source spec .* is not compatible with destination spec'):
+      vs.ensure_value_spec(vs.Int(min_value=1), vs.Bool())
+
+  def test_union(self):
+    self.assertEqual(
+        vs.ensure_value_spec(
+            vs.Union([vs.Int(), vs.Str(regex='a.*')]),
+            vs.Str()), vs.Str(regex='a.*')
+    )
+
+    with self.assertRaisesRegex(
+        TypeError, 'Source spec .* is not compatible with destination spec'):
+      vs.ensure_value_spec(
+          vs.Union([vs.Int(), vs.Str()]),
+          vs.Bool()
+      )
+
+  def test_any(self):
+    self.assertIsNone(vs.ensure_value_spec(vs.Any(), vs.Int()))
+
+
 if __name__ == '__main__':
   unittest.main()