pyglove 0.4.5.dev202412140808__tar.gz → 0.4.5.dev202412160810__tar.gz

{pyglove-0.4.5.dev202412140808 → pyglove-0.4.5.dev202412160810}/PKG-INFO

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

{pyglove-0.4.5.dev202412140808 → pyglove-0.4.5.dev202412160810}/pyglove/core/symbolic/object.py

@@ -164,11 +164,22 @@ class ObjectMeta(abc.ABCMeta):
       if key is None:
         continue
 
+      # Skip class-level attributes that are not symbolic fields.
+      if typing.get_origin(attr_annotation) is typing.ClassVar:
+        continue
+
       field = pg_typing.Field.from_annotation(key, attr_annotation)
       if isinstance(key, pg_typing.ConstStrKey):
         attr_value = cls.__dict__.get(attr_name, pg_typing.MISSING_VALUE)
         if attr_value != pg_typing.MISSING_VALUE:
           field.value.set_default(attr_value)
+
+      if (field.value.frozen and
+          field.value.default is
+          pg_typing.value_specs._FROZEN_VALUE_PLACEHOLDER):  # pylint: disable=protected-access
+        raise TypeError(
+            f'Field {field.key!r} is marked as final but has no default value.'
+        )
       fields.append(field)
 
     # Trigger event so subclass could modify the fields.

{pyglove-0.4.5.dev202412140808 → pyglove-0.4.5.dev202412160810}/pyglove/core/symbolic/object_test.py

@@ -324,6 +324,26 @@ class ObjectTest(unittest.TestCase):
     self.assertEqual(e.x, 1)
     self.assertEqual(e.y, 3)
 
+    class F(Object):
+      x: typing.Literal[1, 'a']
+
+    class G(F):
+      x: typing.Final[int] = 1
+      y: typing.ClassVar[int] = 2
+
+    self.assertEqual(G().x, 1)
+    self.assertEqual(G.y, 2)
+
+    with self.assertRaisesRegex(
+        ValueError, 'Frozen field is not assignable'):
+      G(x=2)
+
+    with self.assertRaisesRegex(
+        TypeError, 'Field x is marked as final but has no default value'):
+
+      class H(Object):  # pylint: disable=unused-variable
+        x: typing.Final[int]  # pylint: disable=invalid-name
+
   def test_init_arg_list(self):
 
     def _update_init_arg_list(cls, init_arg_list):

{pyglove-0.4.5.dev202412140808 → pyglove-0.4.5.dev202412160810}/pyglove/core/symbolic/ref.py

@@ -14,16 +14,30 @@
 """Symbolic reference."""
 
 import functools
-import numbers
-from typing import Any, Callable, List, Optional, Tuple
+import typing
+from typing import Any, Callable, List, Optional, Tuple, Type
 from pyglove.core import object_utils
 from pyglove.core import typing as pg_typing
 from pyglove.core.symbolic import base
-from pyglove.core.symbolic.object import Object
+from pyglove.core.symbolic import object as pg_object
 from pyglove.core.views.html import tree_view
 
 
-class Ref(Object, base.Inferential, tree_view.HtmlTreeView.Extension):
+class RefMeta(pg_object.ObjectMeta):
+  """Metaclass for Ref."""
+
+  def __getitem__(cls, type_arg: Type[Any]) -> Any:    # pylint: disable=no-self-argument
+    if typing.TYPE_CHECKING:
+      return type_arg
+    return pg_typing.Object(type_arg, transform=Ref)
+
+
+class Ref(
+    pg_object.Object,
+    base.Inferential,
+    tree_view.HtmlTreeView.Extension,
+    metaclass=RefMeta
+):
   """Symbolic reference.
 
   When adding a symbolic node to a symbolic tree, it undergoes a copy operation
@@ -82,9 +96,9 @@ class Ref(Object, base.Inferential, tree_view.HtmlTreeView.Extension):
 
   def __new__(cls, value: Any, **kwargs):
     del kwargs
-    if isinstance(value, (bool, numbers.Number, str)):
-      return value
-    return object.__new__(cls)
+    if isinstance(value, (base.Symbolic, list, dict)):
+      return object.__new__(cls)
+    return value
 
   @object_utils.explicit_method_override
   def __init__(self, value: Any, **kwargs) -> None:
@@ -241,4 +255,3 @@ def deref(value: base.Symbolic, recursive: bool = False) -> Any:
       return v
     return value.rebind(_deref, raise_on_no_change=False)
   return value
-

{pyglove-0.4.5.dev202412140808 → pyglove-0.4.5.dev202412160810}/pyglove/core/symbolic/ref_test.py

@@ -16,6 +16,7 @@
 import copy
 import inspect
 import pickle
+import typing
 from typing import Any
 import unittest
 
@@ -202,6 +203,22 @@ class RefTest(unittest.TestCase):
         """
     )
 
+  def test_annotation(self):
+    typing.TYPE_CHECKING = True
+    assert ref.Ref[ValueError] is ValueError
+    typing.TYPE_CHECKING = False
+
+    class Bar(Object):
+      x: int
+
+    class Foo(Object):
+      y: ref.Ref[Bar]
+
+    f = Foo(Bar(1))
+    self.assertIsInstance(f.sym_getattr('y'), ref.Ref)
+    self.assertEqual(f.y.sym_path, '')
+    self.assertIsInstance(ref.Ref[Bar](1), ref.Ref)
+
 
 if __name__ == '__main__':
   unittest.main()

{pyglove-0.4.5.dev202412140808 → pyglove-0.4.5.dev202412160810}/pyglove/core/typing/annotation_conversion.py

@@ -177,6 +177,11 @@ def _value_spec_from_type_annotation(
     if optional:
       spec = spec.noneable()
     return spec
+  elif origin is typing.Final:
+    return _value_spec_from_type_annotation(
+        args[0],
+        accept_value_as_annotation=False
+    ).freeze(vs._FROZEN_VALUE_PLACEHOLDER)  # pylint: disable=protected-access
   elif isinstance(annotation, typing.ForwardRef):
     annotation = annotation.__forward_arg__
     if parent_module is not None:

{pyglove-0.4.5.dev202412140808 → pyglove-0.4.5.dev202412160810}/pyglove/core/typing/annotation_conversion_test.py

@@ -306,6 +306,14 @@ class ValueSpecFromAnnotationTest(unittest.TestCase):
           ValueSpec.from_annotation(int | str, True),
           vs.Union([vs.Int(), vs.Str()]))
 
+  def test_final(self):
+    self.assertEqual(
+        ValueSpec.from_annotation(
+            typing.Final[int], True
+        ).set_default(1),
+        vs.Int().freeze(1)
+    )
+
 
 if __name__ == '__main__':
   unittest.main()

{pyglove-0.4.5.dev202412140808 → pyglove-0.4.5.dev202412160810}/pyglove/core/typing/class_schema.py

@@ -344,6 +344,10 @@ class ValueSpec(object_utils.Formattable, object_utils.JSONConvertible):
       Tuple[Type[Any], ...]]:  # pyformat: disable
     """Returns acceptable (resolved) value type(s)."""
 
+  @abc.abstractmethod
+  def __call__(self, *args, **kwargs) -> Any:
+    """Instantiates a value based on the spec.."""
+
   @property
   @abc.abstractmethod
   def forward_refs(self) -> Set[ForwardRef]:

{pyglove-0.4.5.dev202412140808 → pyglove-0.4.5.dev202412160810}/pyglove/core/typing/value_specs.py

@@ -37,6 +37,17 @@ from pyglove.core.typing.custom_typing import CustomTyping
 
 MISSING_VALUE = object_utils.MISSING_VALUE
 
+
+class _FrozenValuePlaceholder(CustomTyping):
+  """Placeholder for to-be-assigned frozen value."""
+
+  def custom_apply(self, *args, **kwargs) -> typing.Tuple[bool, typing.Any]:
+    return (False, self)
+
+
+_FROZEN_VALUE_PLACEHOLDER = _FrozenValuePlaceholder()
+
+
 # Type alias for ValueSpec object or Python annotation that could be converted
 # to ValueSpec via `pg.typing.ValueSpec.from_annotation()`. This type alias is
 # just for better readability.
@@ -194,8 +205,18 @@ class ValueSpecBase(ValueSpec):
 
   def extend(self, base: ValueSpec) -> ValueSpec:
     """Extend current value spec on top of a base spec."""
-    if base.frozen:
-      raise TypeError(f'Cannot extend a frozen value spec: {base!r}')
+    if base.frozen and (not self.frozen or self.default != base.default):
+      raise TypeError(f'{self!r} cannot extend a frozen value spec: {base!r}')
+
+    # Special handling for extending enum.
+    if self.frozen and isinstance(base, Enum):
+      if self.default in base.values:
+        return Enum(MISSING_VALUE, base.values).freeze(self.default)
+      else:
+        raise TypeError(
+            f'{self!r} cannot extend {base!r} with incompatible '
+            f'frozen value: {self.default!r} '
+        )
 
     if self._transform is None:
       self._transform = base.transform
@@ -232,7 +253,7 @@ class ValueSpecBase(ValueSpec):
       root_path: typing.Optional[object_utils.KeyPath] = None) -> typing.Any:  # pyformat: disable pylint: disable=line-too-long
     """Apply spec to validate and complete value."""
     root_path = root_path or object_utils.KeyPath()
-    if self.frozen:
+    if self.frozen and self.default is not _FROZEN_VALUE_PLACEHOLDER:
       # Always return the default value if a field is frozen.
       if MISSING_VALUE != value and self.default != value:
         raise ValueError(
@@ -270,7 +291,8 @@ class ValueSpecBase(ValueSpec):
         value = self._transform(value)
       except Exception as e:  # pylint: disable=broad-except
         raise e.__class__(
-            object_utils.message_on_path(str(e), root_path)
+            object_utils.message_on_path(
+                str(e), root_path)
             ).with_traceback(sys.exc_info()[2])
 
       return self.skip_user_transform.apply(
@@ -319,7 +341,7 @@ class ValueSpecBase(ValueSpec):
     return value
 
   def is_compatible(self, other: ValueSpec) -> bool:
-    """Returns if current spec is compatible with the other value spec."""
+    """Returns if current spec can receive all values from the other spec."""
     if self is other:
       return True
     if not isinstance(other, self.__class__):
@@ -417,6 +439,12 @@ class PrimitiveType(ValueSpecBase):
         value_type, default, is_noneable=is_noneable, frozen=frozen
     )
 
+  def __call__(self, *args, **kwargs) -> typing.Any:
+    del kwargs
+    if (not args and self.has_default) or self.frozen:
+      return self.default
+    return self.apply(self.value_type(*args))
+
 
 class Bool(PrimitiveType):
   """Value spec for boolean type.
@@ -898,6 +926,12 @@ class Enum(Generic, PrimitiveType):
         value_type, default, is_noneable=is_noneable, frozen=frozen
     )
 
+  def __call__(self, *args, **kwargs) -> typing.Any:
+    del kwargs
+    if (not args and self.has_default) or self.frozen:
+      return self.default
+    return self.apply(*args)
+
   def noneable(self) -> 'Enum':
     """Noneable is specially treated for Enum."""
     if None not in self._values:
@@ -929,6 +963,12 @@ class Enum(Generic, PrimitiveType):
             f'{repr(v)} is not an acceptable value.'
         ) from e
 
+  def is_compatible(self, other: ValueSpec) -> bool:
+    """Enum specific compatibility check."""
+    if other.frozen and other.default in self.values:
+      return True
+    return super().is_compatible(other)
+
   def _is_compatible(self, other: 'Enum') -> bool:
     """Enum specific compatibility check."""
     for v in other.values:
@@ -1067,6 +1107,12 @@ class List(Generic, ValueSpecBase):
         list, default, transform, is_noneable=is_noneable, frozen=frozen
     )
 
+  def __call__(self, *args, **kwargs) -> typing.Any:
+    del kwargs
+    if (not args and self.has_default) or self.frozen:
+      return self.default
+    return self.apply(list(*args))
+
   @property
   def element(self) -> Field:
     """Returns Field specification of list element."""
@@ -1316,6 +1362,12 @@ class Tuple(Generic, ValueSpecBase):
         tuple, default, transform, is_noneable=is_noneable, frozen=frozen
     )
 
+  def __call__(self, *args, **kwargs) -> typing.Any:
+    del kwargs
+    if (not args and self.has_default) or self.frozen:
+      return self.default
+    return self.apply(tuple(*args))
+
   @property
   def fixed_length(self) -> bool:
     """Returns True if current Tuple spec is fixed length."""
@@ -1617,6 +1669,9 @@ class Dict(Generic, ValueSpecBase):
     if MISSING_VALUE == default:
       self.set_default(default)
 
+  def __call__(self, *args, **kwargs) -> typing.Any:
+    return self.apply(dict(*args, **kwargs))
+
   @property
   def schema(self) -> typing.Optional[Schema]:
     """Returns the schema of this dict spec."""
@@ -1816,6 +1871,9 @@ class Object(Generic, ValueSpecBase):
         t, default, transform, is_noneable=is_noneable, frozen=frozen
     )
 
+  def __call__(self, *args, **kwargs) -> typing.Any:
+    return self.apply(self.cls(*args, **kwargs))
+
   @property
   def forward_refs(self) -> typing.Set[class_schema.ForwardRef]:
     """Returns forward references used in this spec."""
@@ -2014,6 +2072,10 @@ class Callable(Generic, ValueSpecBase):
         frozen=frozen,
     )
 
+  def __call__(self, *args, **kwargs) -> typing.Any:
+    del args, kwargs
+    raise TypeError(f'{self!r} cannot be instantiated.')
+
   @functools.cached_property
   def forward_refs(self) -> typing.Set[class_schema.ForwardRef]:
     """Returns forward references used in this spec."""
@@ -2351,6 +2413,10 @@ class Type(Generic, ValueSpecBase):
     self._forward_ref = forward_ref
     super().__init__(type, default, is_noneable=is_noneable, frozen=frozen)
 
+  def __call__(self, *args, **kwargs) -> typing.Any:
+    del args, kwargs
+    return self.type
+
   @property
   def type(self) -> typing.Type[typing.Any]:
     """Returns desired type."""
@@ -2539,6 +2605,10 @@ class Union(Generic, ValueSpecBase):
         frozen=frozen,
     )
 
+  def __call__(self, *args, **kwargs) -> typing.Any:
+    del args, kwargs
+    raise TypeError(f'{self!r} cannot be instantiated.')
+
   @functools.cached_property
   def forward_refs(self) -> typing.Set[class_schema.ForwardRef]:
     """Returns forward references used in this spec."""
@@ -2856,6 +2926,10 @@ class Any(ValueSpecBase):
     )
     self._annotation = annotation
 
+  def __call__(self, *args, **kwargs) -> typing.Any:
+    del args, kwargs
+    raise TypeError(f'{self!r} cannot be instantiated.')
+
   def is_compatible(self, other: ValueSpec) -> bool:
     """Any is compatible with any ValueSpec."""
     return True