pyglove 0.4.5.dev202502040809__py3-none-any.whl → 0.4.5.dev202502060809__py3-none-any.whl

pyglove/core/symbolic/object.py

@@ -16,6 +16,7 @@
 import abc
 import functools
 import inspect
+import sys
 import typing
 from typing import Any, Dict, Iterator, List, Optional, Sequence, Union
 
@@ -154,7 +155,9 @@ class ObjectMeta(abc.ABCMeta):
       if typing.get_origin(attr_annotation) is typing.ClassVar:
         continue
 
-      field = pg_typing.Field.from_annotation(key, attr_annotation)
+      field = pg_typing.Field.from_annotation(
+          key, attr_annotation, parent_module=sys.modules[cls.__module__]
+      )
       if isinstance(key, pg_typing.ConstStrKey):
         attr_value = cls.__dict__.get(attr_name, pg_typing.MISSING_VALUE)
         if attr_value != pg_typing.MISSING_VALUE:

pyglove/core/typing/__init__.py

@@ -375,6 +375,9 @@ import pyglove.core.typing.annotation_conversion  # pylint: disable=unused-impor
 # Interface for custom typing.
 from pyglove.core.typing.custom_typing import CustomTyping
 
+# Annotation conversion
+from pyglove.core.typing.annotation_conversion import annotation_from_str
+
 # Callable signature.
 from pyglove.core.typing.callable_signature import Argument
 from pyglove.core.typing.callable_signature import CallableType

pyglove/core/typing/annotation_conversion.py

@@ -13,11 +13,13 @@
 # limitations under the License.
 """Conversion from annotations to PyGlove value specs."""
 
+import builtins
 import collections
 import inspect
 import types
 import typing
 
+from pyglove.core import coding
 from pyglove.core import utils
 from pyglove.core.typing import annotated
 from pyglove.core.typing import class_schema
@@ -35,6 +37,231 @@ _Annotated = getattr(typing, 'Annotated', None)  # pylint: disable=invalid-name
 _UnionType = getattr(types, 'UnionType', None)  # pylint: disable=invalid-name
 
 
+def annotation_from_str(
+    annotation_str: str,
+    parent_module: typing.Optional[types.ModuleType] = None,
+    ) -> typing.Any:
+  """Parses annotations from str.
+
+  BNF for PyType annotations:
+
+  ```
+  <maybe_union>      ::= <type> | <type> "|" <maybe_union>
+  <type>             ::= <literal_type> | <non_literal_type>
+
+  <literal_type>     ::= "Literal"<literal_params>
+  <literal_params>   ::= "["<python_values>"]" (parsed by `pg.coding.evaluate`)
+
+  <non_literal_type> ::= <type_id> | <type_id>"["<type_arg>"]"
+  <type_arg>       ::= <maybe_type_list> | <maybe_type_list>","<maybe_type_list>
+  <maybe_type_list>  ::= "["<type_arg>"]" | <maybe_union>
+  <type_id>          ::= 'aAz_.1-9'
+  ```
+
+  Args:
+    annotation_str: String form of type annotations. E.g. "list[str]"
+    parent_module: The module where the annotation was defined.
+
+  Returns:
+    Object form of the annotation.
+
+  Raises:
+    SyntaxError: If the annotation string is invalid.
+  """
+  s = annotation_str
+  context = dict(pos=0)
+
+  def _eof() -> bool:
+    return context['pos'] == len(s)
+
+  def _pos() -> int:
+    return context['pos']
+
+  def _next(n: int = 1, offset: int = 0) -> str:
+    if _eof():
+      return '<EOF>'
+    return s[_pos() + offset:_pos() + offset + n]
+
+  def _advance(n: int) -> None:
+    context['pos'] += n
+
+  def _error_illustration() -> str:
+    return f'{s}\n{" " * _pos()}' + '^'
+
+  def _match(ch) -> bool:
+    if _next(len(ch)) == ch:
+      _advance(len(ch))
+      return True
+    return False
+
+  def _skip_whitespaces() -> None:
+    while _next() in ' \t':
+      _advance(1)
+
+  def _maybe_union():
+    t = _type()
+    while not _eof():
+      _skip_whitespaces()
+      if _match('|'):
+        t = t | _type()
+      else:
+        break
+    return t
+
+  def _type():
+    type_id = _type_id()
+    t = _resolve(type_id)
+    if t is typing.Literal:
+      return t[_literal_params()]
+    elif _match('['):
+      arg = _type_arg()
+      if not _match(']'):
+        raise SyntaxError(
+            f'Expected "]" at position {_pos()}.\n\n' + _error_illustration()
+        )
+      return t[arg]
+    return t
+
+  def _literal_params():
+    if not _match('['):
+      raise SyntaxError(
+          f'Expected "[" at position {_pos()}.\n\n' + _error_illustration()
+      )
+    arg_start = _pos()
+    in_str = False
+    escape_mode = False
+    num_open_bracket = 1
+
+    while num_open_bracket > 0:
+      ch = _next()
+      if _eof():
+        raise SyntaxError(
+            f'Unexpected end of annotation at position {_pos()}.\n\n'
+            + _error_illustration()
+        )
+      if ch == '\\':
+        escape_mode = not escape_mode
+      else:
+        escape_mode = False
+
+      if ch == "'" and not escape_mode:
+        in_str = not in_str
+      elif not in_str:
+        if ch == '[':
+          num_open_bracket += 1
+        elif ch == ']':
+          num_open_bracket -= 1
+      _advance(1)
+
+    arg_str = s[arg_start:_pos() - 1]
+    return coding.evaluate(
+        '(' + arg_str + ')', permission=coding.CodePermission.BASIC
+    )
+
+  def _type_arg():
+    t_args = []
+    t_args.append(_maybe_type_list())
+    while _match(','):
+      t_args.append(_maybe_type_list())
+    return tuple(t_args) if len(t_args) > 1 else t_args[0]
+
+  def _maybe_type_list():
+    if _match('['):
+      ret = _type_arg()
+      if not _match(']'):
+        raise SyntaxError(
+            f'Expected "]" at position {_pos()}.\n\n' + _error_illustration()
+        )
+      return list(ret) if isinstance(ret, tuple) else [ret]
+    return _maybe_union()
+
+  def _type_id() -> str:
+    _skip_whitespaces()
+    if _match('...'):
+      return '...'
+    start = _pos()
+    while not _eof():
+      c = _next()
+      if c.isalnum() or c in '_.':
+        _advance(1)
+      else:
+        break
+    t_id = s[start:_pos()]
+    if not all(x.isidentifier() for x in t_id.split('.')):
+      raise SyntaxError(
+          f'Expected type identifier, got {t_id!r} at position {start}.\n\n'
+          + _error_illustration()
+      )
+    return t_id
+
+  def _resolve(type_id: str):
+
+    def _as_forward_ref() -> typing.ForwardRef:
+      return typing.ForwardRef(type_id, False, parent_module)  # pytype: disable=not-callable
+
+    def _resolve_name(name: str, parent_obj: typing.Any):
+      if name == 'None':
+        return None, True
+      if parent_obj is not None and hasattr(parent_obj, name):
+        return getattr(parent_obj, name), False
+      if hasattr(builtins, name):
+        return getattr(builtins, name), True
+      if type_id == '...':
+        return ..., True
+      return utils.MISSING_VALUE, False
+
+    names = type_id.split('.')
+    if len(names) == 1:
+      reference, is_builtin = _resolve_name(names[0], parent_module)
+      if is_builtin:
+        return reference
+      if not is_builtin and (
+          # When reference is not found, we should treat it as a forward
+          # reference.
+          reference == utils.MISSING_VALUE
+          # When module is being reloaded, we should treat all non-builtin
+          # references as forward references.
+          or getattr(parent_module, '__reloading__', False)
+      ):
+        return _as_forward_ref()
+      return reference
+
+    root_obj, _ = _resolve_name(names[0], parent_module)
+    # When root object is not found, we should treat it as a forward reference.
+    if root_obj == utils.MISSING_VALUE:
+      return _as_forward_ref()
+
+    parent_obj = root_obj
+    # When root object is a module, we should treat reference to its children
+    # as non-forward references.
+    if inspect.ismodule(root_obj):
+      for name in names[1:]:
+        parent_obj, _ = _resolve_name(name, parent_obj)
+        if parent_obj == utils.MISSING_VALUE:
+          raise TypeError(f'{type_id!r} does not exist.')
+      return parent_obj
+    # When root object is non-module variable of current module, and when the
+    # module is being reloaded, we should treat reference to its children as
+    # forward references.
+    elif getattr(parent_module, '__reloading__', False):
+      return _as_forward_ref()
+    # When root object is non-module variable of current module, we should treat
+    # unresolved reference to its children as forward references.
+    else:
+      for name in names[1:]:
+        parent_obj, _ = _resolve_name(name, parent_obj)
+        if parent_obj == utils.MISSING_VALUE:
+          return _as_forward_ref()
+      return parent_obj
+
+  root = _maybe_union()
+  if _pos() != len(s):
+    raise SyntaxError(
+        'Unexpected end of annotation.\n\n' + _error_illustration()
+    )
+  return root
+
+
 def _field_from_annotation(
     key: typing.Union[str, class_schema.KeySpec],
     annotation: typing.Any,
@@ -91,7 +318,12 @@ def _value_spec_from_type_annotation(
     parent_module: typing.Optional[types.ModuleType] = None
 ) -> class_schema.ValueSpec:
   """Creates a value spec from type annotation."""
-  if annotation is bool:
+  if isinstance(annotation, str) and not accept_value_as_annotation:
+    annotation = annotation_from_str(annotation, parent_module)
+
+  if annotation is None:
+    return vs.Object(type(None))
+  elif annotation is bool:
     return vs.Bool()
   elif annotation is int:
     return vs.Int()
@@ -193,10 +425,7 @@ def _value_spec_from_type_annotation(
   elif (
       inspect.isclass(annotation)
       or pg_inspect.is_generic(annotation)
-      or (isinstance(annotation, str) and not accept_value_as_annotation)
   ):
-    if isinstance(annotation, str) and parent_module is not None:
-      annotation = class_schema.ForwardRef(parent_module, annotation)
     return vs.Object(annotation)
 
   if accept_value_as_annotation:
@@ -227,11 +456,12 @@ def _value_spec_from_annotation(
     return annotation
   elif annotation == inspect.Parameter.empty:
     return vs.Any()
-  elif annotation is None:
+
+  if annotation is None:
     if accept_value_as_annotation:
       return vs.Any().noneable()
     else:
-      return vs.Any().freeze(None)
+      return vs.Object(type(None))
 
   if auto_typing:
     return _value_spec_from_type_annotation(

pyglove/core/typing/annotation_conversion_test.py

@@ -1,4 +1,4 @@
-# Copyright 2023 The PyGlove Authors
+# Copyright 2025 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.
@@ -11,13 +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.annotation_conversion."""
-
 import inspect
 import sys
 import typing
 import unittest
 
+from pyglove.core import coding
 from pyglove.core.typing import annotated
 from pyglove.core.typing import annotation_conversion
 from pyglove.core.typing import key_specs as ks
@@ -28,7 +27,168 @@ from pyglove.core.typing.class_schema import ValueSpec
 
 
 class Foo:
-  pass
+  class Bar:
+    pass
+
+
+_MODULE = sys.modules[__name__]
+
+
+class AnnotationFromStrTest(unittest.TestCase):
+  """Tests for annotation_from_str."""
+
+  def test_basic_types(self):
+    self.assertIsNone(annotation_conversion.annotation_from_str('None'))
+    self.assertEqual(annotation_conversion.annotation_from_str('str'), str)
+    self.assertEqual(annotation_conversion.annotation_from_str('int'), int)
+    self.assertEqual(annotation_conversion.annotation_from_str('float'), float)
+    self.assertEqual(annotation_conversion.annotation_from_str('bool'), bool)
+    self.assertEqual(annotation_conversion.annotation_from_str('list'), list)
+    self.assertEqual(
+        annotation_conversion.annotation_from_str('list[int]'), list[int]
+    )
+    self.assertEqual(annotation_conversion.annotation_from_str('tuple'), tuple)
+    self.assertEqual(
+        annotation_conversion.annotation_from_str('tuple[int]'), tuple[int]
+    )
+    self.assertEqual(
+        annotation_conversion.annotation_from_str('tuple[int, ...]'),
+        tuple[int, ...]
+    )
+    self.assertEqual(
+        annotation_conversion.annotation_from_str('tuple[int, str]'),
+        tuple[int, str]
+    )
+    self.assertEqual(
+        annotation_conversion.annotation_from_str('list[Foo]', _MODULE),
+        list[Foo]
+    )
+    self.assertEqual(
+        annotation_conversion.annotation_from_str('list[Foo.Bar]', _MODULE),
+        list[Foo.Bar]
+    )
+    self.assertEqual(
+        annotation_conversion.annotation_from_str('list[Foo.Baz]', _MODULE),
+        list[typing.ForwardRef('Foo.Baz', False, _MODULE)]
+    )
+
+  def test_generic_types(self):
+    self.assertEqual(
+        annotation_conversion.annotation_from_str('typing.List[str]', _MODULE),
+        typing.List[str]
+    )
+
+  def test_union(self):
+    self.assertEqual(
+        annotation_conversion.annotation_from_str(
+            'typing.Union[str, typing.Union[int, float]]', _MODULE),
+        typing.Union[str, int, float]
+    )
+    if sys.version_info >= (3, 10):
+      self.assertEqual(
+          annotation_conversion.annotation_from_str(
+              'str | int | float', _MODULE),
+          typing.Union[str, int, float]
+      )
+
+  def test_literal(self):
+    self.assertEqual(
+        annotation_conversion.annotation_from_str(
+            'typing.Literal[1, True, "a", \'"b"\', "\\"c\\"", "\\\\"]',
+            _MODULE
+        ),
+        typing.Literal[1, True, 'a', '"b"', '"c"', '\\']
+    )
+    self.assertEqual(
+        annotation_conversion.annotation_from_str(
+            'typing.Literal[(1, 1), f"A {[1]}"]', _MODULE),
+        typing.Literal[(1, 1), 'A [1]']
+    )
+    with self.assertRaisesRegex(SyntaxError, 'Expected "\\["'):
+      annotation_conversion.annotation_from_str('typing.Literal', _MODULE)
+
+    with self.assertRaisesRegex(SyntaxError, 'Unexpected end of annotation'):
+      annotation_conversion.annotation_from_str('typing.Literal[1', _MODULE)
+
+    with self.assertRaisesRegex(
+        coding.CodeError, 'Function definition is not allowed'
+    ):
+      annotation_conversion.annotation_from_str(
+          'typing.Literal[lambda x: x]', _MODULE
+      )
+
+  def test_callable(self):
+    self.assertEqual(
+        annotation_conversion.annotation_from_str(
+            'typing.Callable[int, int]', _MODULE),
+        typing.Callable[[int], int]
+    )
+    self.assertEqual(
+        annotation_conversion.annotation_from_str(
+            'typing.Callable[[int], int]', _MODULE),
+        typing.Callable[[int], int]
+    )
+    self.assertEqual(
+        annotation_conversion.annotation_from_str(
+            'typing.Callable[..., None]', _MODULE),
+        typing.Callable[..., None]
+    )
+
+  def test_forward_ref(self):
+    self.assertEqual(
+        annotation_conversion.annotation_from_str(
+            'AAA', _MODULE),
+        typing.ForwardRef(
+            'AAA', False, _MODULE
+        )
+    )
+    self.assertEqual(
+        annotation_conversion.annotation_from_str(
+            'typing.List[AAA]', _MODULE),
+        typing.List[
+            typing.ForwardRef(
+                'AAA', False, _MODULE
+            )
+        ]
+    )
+
+  def test_reloading(self):
+    setattr(_MODULE, '__reloading__', True)
+    self.assertEqual(
+        annotation_conversion.annotation_from_str(
+            'typing.List[Foo]', _MODULE),
+        typing.List[
+            typing.ForwardRef(
+                'Foo', False, _MODULE
+            )
+        ]
+    )
+    self.assertEqual(
+        annotation_conversion.annotation_from_str(
+            'typing.List[Foo.Bar]', _MODULE),
+        typing.List[
+            typing.ForwardRef(
+                'Foo.Bar', False, _MODULE
+            )
+        ]
+    )
+    delattr(_MODULE, '__reloading__')
+
+  def test_bad_annotation(self):
+    with self.assertRaisesRegex(SyntaxError, 'Expected type identifier'):
+      annotation_conversion.annotation_from_str('typing.List[]')
+
+    with self.assertRaisesRegex(SyntaxError, 'Expected "]"'):
+      annotation_conversion.annotation_from_str('typing.List[int')
+
+    with self.assertRaisesRegex(SyntaxError, 'Unexpected end of annotation'):
+      annotation_conversion.annotation_from_str('typing.List[int]1', _MODULE)
+
+    with self.assertRaisesRegex(SyntaxError, 'Expected "]"'):
+      annotation_conversion.annotation_from_str('typing.Callable[[x')
+
+    with self.assertRaisesRegex(TypeError, '.* does not exist'):
+      annotation_conversion.annotation_from_str('typing.Foo', _MODULE)
 
 
 class FieldFromAnnotationTest(unittest.TestCase):
@@ -132,17 +292,24 @@ class ValueSpecFromAnnotationTest(unittest.TestCase):
 
   def test_none(self):
     self.assertEqual(
-        ValueSpec.from_annotation(None, False), vs.Any().freeze(None))
+        ValueSpec.from_annotation(None, False), vs.Object(type(None)))
     self.assertEqual(
-        ValueSpec.from_annotation(None, True), vs.Any().freeze(None))
+        ValueSpec.from_annotation('None', True), vs.Object(type(None)))
     self.assertEqual(
-        ValueSpec.from_annotation(
-            None, accept_value_as_annotation=True), vs.Any().noneable())
+        ValueSpec.from_annotation(None, True), vs.Object(type(None)))
+    self.assertEqual(
+        ValueSpec.from_annotation(None, accept_value_as_annotation=True),
+        vs.Any().noneable()
+    )
 
   def test_any(self):
     self.assertEqual(
         ValueSpec.from_annotation(typing.Any, False),
         vs.Any(annotation=typing.Any))
+    self.assertEqual(
+        ValueSpec.from_annotation('typing.Any', True, parent_module=_MODULE),
+        vs.Any(annotation=typing.Any)
+    )
     self.assertEqual(
         ValueSpec.from_annotation(typing.Any, True),
         vs.Any(annotation=typing.Any))
@@ -152,6 +319,7 @@ class ValueSpecFromAnnotationTest(unittest.TestCase):
 
   def test_bool(self):
     self.assertEqual(ValueSpec.from_annotation(bool, True), vs.Bool())
+    self.assertEqual(ValueSpec.from_annotation('bool', True), vs.Bool())
     self.assertEqual(
         ValueSpec.from_annotation(bool, False), vs.Any(annotation=bool))
     self.assertEqual(
@@ -159,6 +327,7 @@ class ValueSpecFromAnnotationTest(unittest.TestCase):
 
   def test_int(self):
     self.assertEqual(ValueSpec.from_annotation(int, True), vs.Int())
+    self.assertEqual(ValueSpec.from_annotation('int', True), vs.Int())
     self.assertEqual(ValueSpec.from_annotation(int, True, True), vs.Int())
     self.assertEqual(
         ValueSpec.from_annotation(int, False), vs.Any(annotation=int))
@@ -182,7 +351,9 @@ class ValueSpecFromAnnotationTest(unittest.TestCase):
         ValueSpec.from_annotation(str, False, True), vs.Any(annotation=str))
 
     self.assertEqual(
-        ValueSpec.from_annotation('A', False, False), vs.Any(annotation='A'))
+        ValueSpec.from_annotation('A', False, False),
+        vs.Any(annotation='A')
+    )
     self.assertEqual(
         ValueSpec.from_annotation('A', False, True), vs.Str('A'))
     self.assertEqual(

pyglove/core/typing/annotation_future_test.py

@@ -0,0 +1,135 @@
+# Copyright 2025 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.
+
+from __future__ import annotations
+import sys
+import typing
+from typing import List, Literal, Union
+import unittest
+
+from pyglove.core import symbolic as pg
+from pyglove.core.typing import key_specs as ks
+from pyglove.core.typing import value_specs as vs
+
+
+class AnnotationFutureConversionTest(unittest.TestCase):
+
+  # Class with forward declaration must not be defined in functions.
+  class A(pg.Object):
+    a: typing.Optional[AnnotationFutureConversionTest.A]
+    b: List[AnnotationFutureConversionTest.A]
+
+  def assert_value_spec(self, cls, field_name, expected_value_spec):
+    self.assertEqual(cls.__schema__[field_name].value, expected_value_spec)
+
+  def test_basics(self):
+
+    class Foo(pg.Object):
+      a: int
+      b: float
+      c: bool
+      d: str
+      e: typing.Any
+      f: typing.Dict[str, typing.Any]
+      g: typing.List[str]
+      h: typing.Tuple[int, int]
+      i: typing.Callable[[int, int], None]
+
+    self.assert_value_spec(Foo, 'a', vs.Int())
+    self.assert_value_spec(Foo, 'b', vs.Float())
+    self.assert_value_spec(Foo, 'c', vs.Bool())
+    self.assert_value_spec(Foo, 'd', vs.Str())
+    self.assert_value_spec(Foo, 'e', vs.Any(annotation=typing.Any))
+    self.assert_value_spec(
+        Foo, 'f', vs.Dict([(ks.StrKey(), vs.Any(annotation=typing.Any))])
+    )
+    self.assert_value_spec(Foo, 'g', vs.List(vs.Str()))
+    self.assert_value_spec(Foo, 'h', vs.Tuple([vs.Int(), vs.Int()]))
+    self.assert_value_spec(
+        Foo, 'i',
+        vs.Callable([vs.Int(), vs.Int()], returns=vs.Object(type(None)))
+    )
+
+  def test_list(self):
+    if sys.version_info >= (3, 10):
+
+      class Bar(pg.Object):
+        x: list[int | None]
+
+      self.assert_value_spec(Bar, 'x', vs.List(vs.Int().noneable()))
+
+  def test_var_length_tuple(self):
+
+    class Foo(pg.Object):
+      x: typing.Tuple[int, ...]
+
+    self.assert_value_spec(Foo, 'x', vs.Tuple(vs.Int()))
+
+    if sys.version_info >= (3, 10):
+
+      class Bar(pg.Object):
+        x: tuple[int, ...]
+
+      self.assert_value_spec(Bar, 'x', vs.Tuple(vs.Int()))
+
+  def test_optional(self):
+
+    class Foo(pg.Object):
+      x: typing.Optional[int]
+
+    self.assert_value_spec(Foo, 'x', vs.Int().noneable())
+
+    if sys.version_info >= (3, 10):
+      class Bar(pg.Object):
+        x: int | None
+
+      self.assert_value_spec(Bar, 'x', vs.Int().noneable())
+
+  def test_union(self):
+
+    class Foo(pg.Object):
+      x: Union[int, typing.Union[str, bool], None]
+
+    self.assert_value_spec(
+        Foo, 'x', vs.Union([vs.Int(), vs.Str(), vs.Bool()]).noneable()
+    )
+
+    if sys.version_info >= (3, 10):
+
+      class Bar(pg.Object):
+        x: int | str | bool
+
+      self.assert_value_spec(
+          Bar, 'x', vs.Union([vs.Int(), vs.Str(), vs.Bool()])
+      )
+
+  def test_literal(self):
+
+    class Foo(pg.Object):
+      x: Literal[1, True, 'abc']
+
+    self.assert_value_spec(
+        Foo, 'x', vs.Enum(vs.MISSING_VALUE, [1, True, 'abc'])
+    )
+
+  def test_self_referencial(self):
+    self.assert_value_spec(
+        self.A, 'a', vs.Object(self.A).noneable()
+    )
+    self.assert_value_spec(
+        self.A, 'b', vs.List(vs.Object(self.A))
+    )
+
+if __name__ == '__main__':
+  unittest.main()

pyglove/core/typing/class_schema.py

@@ -97,9 +97,9 @@ class KeySpec(utils.Formattable, utils.JSONConvertible):
 class ForwardRef(utils.Formattable):
   """Forward type reference."""
 
-  def __init__(self, module: types.ModuleType, name: str):
+  def __init__(self, module: types.ModuleType, qualname: str):
     self._module = module
-    self._name = name
+    self._qualname = qualname
 
   @property
   def module(self) -> types.ModuleType:
@@ -109,33 +109,49 @@ class ForwardRef(utils.Formattable):
   @property
   def name(self) -> str:
     """Returns the name of the type reference."""
-    return self._name
+    return self._qualname.split('.')[-1]
 
   @property
   def qualname(self) -> str:
     """Returns the qualified name of the reference."""
-    return f'{self.module.__name__}.{self.name}'
+    return self._qualname
+
+  @property
+  def type_id(self) -> str:
+    """Returns the type id of the reference."""
+    return f'{self.module.__name__}.{self.qualname}'
 
   def as_annotation(self) -> Union[Type[Any], str]:
     """Returns the forward reference as an annotation."""
-    return self.cls if self.resolved else self.name
+    return self.cls if self.resolved else self.qualname
 
   @property
   def resolved(self) -> bool:
     """Returns True if the symbol for the name is resolved.."""
-    return hasattr(self.module, self.name)
+    return self._resolve() is not None
+
+  def _resolve(self) -> Optional[Any]:
+    names = self._qualname.split('.')
+    parent_obj = self.module
+    for name in names:
+      parent_obj = getattr(parent_obj, name, utils.MISSING_VALUE)
+      if parent_obj == utils.MISSING_VALUE:
+        return None
+    if not inspect.isclass(parent_obj):
+      raise TypeError(
+          f'{self.qualname!r} from module {self.module.__name__!r} '
+          'is not a class.'
+      )
+    return parent_obj
 
   @property
   def cls(self) -> Type[Any]:
     """Returns the resolved reference class.."""
-    reference = getattr(self.module, self.name, None)
+    reference = self._resolve()
     if reference is None:
       raise TypeError(
-          f'{self.name!r} does not exist in module {self.module.__name__!r}'
-      )
-    elif not inspect.isclass(reference):
-      raise TypeError(
-          f'{self.name!r} from module {self.module.__name__!r} is not a class.'
+          f'{self.qualname!r} does not exist in '
+          f'module {self.module.__name__!r}'
       )
     return reference
 
@@ -150,7 +166,7 @@ class ForwardRef(utils.Formattable):
     return utils.kvlist_str(
         [
             ('module', self.module.__name__, None),
-            ('name', self.name, None),
+            ('name', self.qualname, None),
         ],
         label=self.__class__.__name__,
         compact=compact,
@@ -164,7 +180,7 @@ class ForwardRef(utils.Formattable):
     if self is other:
       return True
     elif isinstance(other, ForwardRef):
-      return self.module is other.module and self.name == other.name
+      return self.module is other.module and self.qualname == other.qualname
     elif inspect.isclass(other):
       return self.resolved and self.cls is other  # pytype: disable=bad-return-type
 
@@ -173,11 +189,11 @@ class ForwardRef(utils.Formattable):
     return not self.__eq__(other)
 
   def __hash__(self) -> int:
-    return hash((self.module, self.name))
+    return hash((self.module, self.qualname))
 
   def __deepcopy__(self, memo) -> 'ForwardRef':
     """Override deep copy to avoid copying module."""
-    return ForwardRef(self.module, self.name)
+    return ForwardRef(self.module, self.qualname)
 
 
 class ValueSpec(utils.Formattable, utils.JSONConvertible):
@@ -628,9 +644,11 @@ class Field(utils.Formattable, utils.JSONConvertible):
       annotation: Any,
       description: Optional[str] = None,
       metadata: Optional[Dict[str, Any]] = None,
-      auto_typing=True) -> 'Field':
+      auto_typing=True,
+      parent_module: Optional[types.ModuleType] = None
+      ) -> 'Field':
     """Gets a Field from annotation."""
-    del key, annotation, description, metadata, auto_typing
+    del key, annotation, description, metadata, auto_typing, parent_module
     assert False, 'Overridden in `annotation_conversion.py`.'
 
   @property

pyglove/core/typing/class_schema_test.py

@@ -31,24 +31,31 @@ from pyglove.core.typing.class_schema import Schema
 class ForwardRefTest(unittest.TestCase):
   """Test for `ForwardRef` class."""
 
+  class A:
+    pass
+
   def setUp(self):
     super().setUp()
     self._module = sys.modules[__name__]
 
   def test_basics(self):
-    r = class_schema.ForwardRef(self._module, 'FieldTest')
+    r = class_schema.ForwardRef(self._module, 'ForwardRefTest.A')
     self.assertIs(r.module, self._module)
-    self.assertEqual(r.name, 'FieldTest')
-    self.assertEqual(r.qualname, f'{self._module.__name__}.FieldTest')
+    self.assertEqual(r.name, 'A')
+    self.assertEqual(r.qualname, 'ForwardRefTest.A')
+    self.assertEqual(r.type_id, f'{self._module.__name__}.ForwardRefTest.A')
 
   def test_resolved(self):
-    self.assertTrue(class_schema.ForwardRef(self._module, 'FieldTest').resolved)
+    self.assertTrue(
+        class_schema.ForwardRef(self._module, 'ForwardRefTest.A').resolved
+    )
     self.assertFalse(class_schema.ForwardRef(self._module, 'Foo').resolved)
 
   def test_as_annotation(self):
     self.assertEqual(
-        class_schema.ForwardRef(self._module, 'FieldTest').as_annotation(),
-        FieldTest,
+        class_schema.ForwardRef(
+            self._module, 'ForwardRefTest.A').as_annotation(),
+        ForwardRefTest.A,
     )
     self.assertEqual(
         class_schema.ForwardRef(self._module, 'Foo').as_annotation(), 'Foo'
@@ -56,7 +63,8 @@ class ForwardRefTest(unittest.TestCase):
 
   def test_cls(self):
     self.assertIs(
-        class_schema.ForwardRef(self._module, 'FieldTest').cls, FieldTest
+        class_schema.ForwardRef(self._module, 'ForwardRefTest.A').cls,
+        ForwardRefTest.A
     )
 
     with self.assertRaisesRegex(TypeError, '.* does not exist in module'):

{pyglove-0.4.5.dev202502040809.dist-info → pyglove-0.4.5.dev202502060809.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pyglove
-Version: 0.4.5.dev202502040809
+Version: 0.4.5.dev202502060809
 Summary: PyGlove: A library for manipulating Python objects.
 Home-page: https://github.com/google/pyglove
 Author: PyGlove Authors

{pyglove-0.4.5.dev202502040809.dist-info → pyglove-0.4.5.dev202502060809.dist-info}/RECORD

@@ -88,7 +88,7 @@ pyglove/core/symbolic/inferred.py,sha256=E4zgphg6NNZad9Fl3jdHQOMZeqEp9XHq5OUYqXE
 pyglove/core/symbolic/inferred_test.py,sha256=G6uPykONcChvs6vZujXHSWaYfjewLTVBscMqzzKNty0,1270
 pyglove/core/symbolic/list.py,sha256=z8goU0ntd-Q5ADaCGiKsJwPhdRdQb0Kd_p-ZekXaLy4,30303
 pyglove/core/symbolic/list_test.py,sha256=IAyFQ48nyczKUcPNZFKHBkX5oh7Xuxbnv3rRkONhbHw,61146
-pyglove/core/symbolic/object.py,sha256=T1HtGYNA1qLp0iTZVmgR90nfMLuOQVNopkBPYw_j8B8,42021
+pyglove/core/symbolic/object.py,sha256=6bCg20r76sfHfVA-BBQYFxTYBzOM_c8BihHEKMKt3i8,42093
 pyglove/core/symbolic/object_test.py,sha256=vIL_ymGpPPXamIljEBdufpw-p82kTeWNy2IbgzGQjig,93811
 pyglove/core/symbolic/origin.py,sha256=OSWMKjvPcISOXrzuX3lCQC8m_qaGl-9INsIB81erUnU,6124
 pyglove/core/symbolic/origin_test.py,sha256=dU_ZGrGDetM_lYVMn3wQO0d367_t_t8eESe3NrKPBNE,3159
@@ -106,17 +106,18 @@ pyglove/core/tuning/protocols.py,sha256=10Iukt1rqh05caURTZffSsb3CcHo7epBQnNtnyMy
 pyglove/core/tuning/protocols_test.py,sha256=Cbzvz3EacaW2sbm1rTSQXEt_VucMoQbeQ6AeN-GV5Vc,1883
 pyglove/core/tuning/sample.py,sha256=UzsCY8kiqnzH_mR94zLXhOloyvvEwfmBWluBjmefUFA,12975
 pyglove/core/tuning/sample_test.py,sha256=JqwDPy3EPC_VjU9dipk90jj1kovZB3Zb9hAjAlZ-U1U,17551
-pyglove/core/typing/__init__.py,sha256=Z_jnwUvDQ3wA16a5TiuWbuof9hW0Xm6YoTNwgG4QGqI,14395
+pyglove/core/typing/__init__.py,sha256=MwraQ-6K8NYI_xk4V3oaVSkrPqiU9InDtAgXPSRBvik,14494
 pyglove/core/typing/annotated.py,sha256=llaajIDj9GK-4kUGJoO4JsHU6ESPOra2SZ-jG6xmsOQ,3203
 pyglove/core/typing/annotated_test.py,sha256=p1qid3R-jeiOTTxOVq6hXW8XFvn-h1cUzJWISPst2l8,2484
-pyglove/core/typing/annotation_conversion.py,sha256=OhBQRCaSh7zJKfb_IQKF7sD32E_YNTekz00qZaSIVnw,9007
-pyglove/core/typing/annotation_conversion_test.py,sha256=tZheqbLWbr76WBIDOplLtY3yznMc4m9u7KCznWEJdEs,11660
+pyglove/core/typing/annotation_conversion.py,sha256=7aMxv5AhC5oYteBtVTRp1no16dFgfGFCLbmxVasrdzQ,15557
+pyglove/core/typing/annotation_conversion_test.py,sha256=tOUM7k_VNiGfBlSy_r6vMKk0lD8gRNT6dqnzBzvhul4,17422
+pyglove/core/typing/annotation_future_test.py,sha256=ZVLU3kheO2V-nrp-m5jrGMLgGMs4S6RWnJbyD9KbHl4,3746
 pyglove/core/typing/callable_ext.py,sha256=PiBQWPeUAH7Lgmf2xKCZqgK7N0OSrTdbnEkV8Ph31OA,9127
 pyglove/core/typing/callable_ext_test.py,sha256=TnWKU4_ZjvpbHZFtFHgFvCMDiCos8VmLlODcM_7Xg8M,10156
 pyglove/core/typing/callable_signature.py,sha256=DRpt7aShfkn8pb3SCiZzS_27eHbkQ_d2UB8BUhJjs0Q,27176
 pyglove/core/typing/callable_signature_test.py,sha256=iQmHsKPhJPQlMikDhEyxKyq7yWyXI9juKCLYgKhrH3U,25145
-pyglove/core/typing/class_schema.py,sha256=xfPrLYpqntejMLvSL-7rNiXHTQOgAr2kmxWeR890qLs,53940
-pyglove/core/typing/class_schema_test.py,sha256=UWANPqhu9v_FHNo3cVe05P-bO-HliBmrSBywKrlWep0,29204
+pyglove/core/typing/class_schema.py,sha256=dKmF1dwv-7RmCjnAb412AciYZL3LJCToU5WTJWYLj3Y,54482
+pyglove/core/typing/class_schema_test.py,sha256=RurRdCyPuypKJ7izgcq9zW3JNHgODiJdQvDn0BDZDjU,29353
 pyglove/core/typing/custom_typing.py,sha256=qdnIKHWNt5kZAAFdpQXra8bBu6RljMbbJ_YDG2mhAUA,2205
 pyglove/core/typing/inspect.py,sha256=VLSz1KAunNm2hx0eEMjiwxKLl9FHlKr9nHelLT25iEA,7726
 pyglove/core/typing/inspect_test.py,sha256=xclevobF0X8c_B5b1q1dkBJZN1TsVA1RUhk5l25DUCM,10248
@@ -211,8 +212,8 @@ pyglove/ext/scalars/randoms.py,sha256=LkMIIx7lOq_lvJvVS3BrgWGuWl7Pi91-lA-O8x_gZs
 pyglove/ext/scalars/randoms_test.py,sha256=nEhiqarg8l_5EOucp59CYrpO2uKxS1pe0hmBdZUzRNM,2000
 pyglove/ext/scalars/step_wise.py,sha256=IDw3tuTpv0KVh7AN44W43zqm1-E0HWPUlytWOQC9w3Y,3789
 pyglove/ext/scalars/step_wise_test.py,sha256=TL1vJ19xVx2t5HKuyIzGoogF7N3Rm8YhLE6JF7i0iy8,2540
-pyglove-0.4.5.dev202502040809.dist-info/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
-pyglove-0.4.5.dev202502040809.dist-info/METADATA,sha256=g47xUh8StCt5ojg7Arw96L0nds0Kl8hrGazZx7IsU10,7067
-pyglove-0.4.5.dev202502040809.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-pyglove-0.4.5.dev202502040809.dist-info/top_level.txt,sha256=wITzJSKcj8GZUkbq-MvUQnFadkiuAv_qv5qQMw0fIow,8
-pyglove-0.4.5.dev202502040809.dist-info/RECORD,,
+pyglove-0.4.5.dev202502060809.dist-info/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+pyglove-0.4.5.dev202502060809.dist-info/METADATA,sha256=r1aB5PMkBiDYY5J67WcefYKfO6WHmnF7nGNB5y6gLVY,7067
+pyglove-0.4.5.dev202502060809.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+pyglove-0.4.5.dev202502060809.dist-info/top_level.txt,sha256=wITzJSKcj8GZUkbq-MvUQnFadkiuAv_qv5qQMw0fIow,8
+pyglove-0.4.5.dev202502060809.dist-info/RECORD,,