pyglove 0.4.5.dev202502040809__tar.gz → 0.4.5.dev202502050809__tar.gz

{pyglove-0.4.5.dev202502040809 → pyglove-0.4.5.dev202502050809}/PKG-INFO

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

{pyglove-0.4.5.dev202502040809 → pyglove-0.4.5.dev202502050809}/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-0.4.5.dev202502040809 → pyglove-0.4.5.dev202502050809}/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-0.4.5.dev202502040809 → pyglove-0.4.5.dev202502050809}/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,191 @@ _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 _resolve_name(name: str, parent_obj: typing.Any):
+      if name == 'None':
+        return None
+      if parent_obj is not None and hasattr(parent_obj, name):
+        return getattr(parent_obj, name)
+      if hasattr(builtins, name):
+        return getattr(builtins, name)
+      if type_id == '...':
+        return ...
+      return utils.MISSING_VALUE
+    parent_obj = parent_module
+    for name in type_id.split('.'):
+      parent_obj = _resolve_name(name, parent_obj)
+      if parent_obj == utils.MISSING_VALUE:
+        return typing.ForwardRef(     # pytype: disable=not-callable
+            type_id, False, parent_module
+        )
+    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 +278,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 +385,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 +416,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-0.4.5.dev202502040809 → pyglove-0.4.5.dev202502050809}/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
@@ -31,6 +30,129 @@ class Foo:
   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]
+    )
+
+  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_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')
+
+
 class FieldFromAnnotationTest(unittest.TestCase):
   """Tests for Field.fromAnnotation."""
 
@@ -132,17 +254,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 +281,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 +289,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 +313,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-0.4.5.dev202502050809/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()