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

pyglove/core/symbolic/object.py

@@ -19,9 +19,9 @@ import inspect
 import typing
 from typing import Any, Dict, Iterator, List, Optional, Sequence, Union
 
-from pyglove.core import logging
-from pyglove.core import object_utils
+from pyglove.core import coding
 from pyglove.core import typing as pg_typing
+from pyglove.core import utils
 from pyglove.core.symbolic import base
 from pyglove.core.symbolic import dict as pg_dict
 from pyglove.core.symbolic import flags
@@ -49,21 +49,6 @@ class ObjectMeta(abc.ABCMeta):
     """
     return f'{cls.__module__}.{cls.__qualname__}'
 
-  def __getattr__(cls, name):
-    # NOTE(daiyip): For backward compatibility, we allows these names to
-    # be used as aliases to the canonical names if users do not override them.
-    if name == 'schema':
-      logging.warning(
-          '`pg.Object.schema` is deprecated and will be removed in future. '
-          'Please use `__schema__` instead.')
-      return cls.__schema__
-    elif name == 'type_name':
-      logging.warning(
-          '`pg.Object.type_name` is deprecated and will be removed in future. '
-          'Please use `__type_name__` instead.')
-      return cls.__type_name__
-    raise AttributeError(name)
-
   @property
   def init_arg_list(cls) -> List[str]:
     """Gets __init__ positional argument list."""
@@ -80,7 +65,7 @@ class ObjectMeta(abc.ABCMeta):
     """
     # Formalize schema first.
     if schema is not None:
-      schema = cls._normalize_schema(schema)
+      schema = cls._normalize_schema(schema)  # pytype: disable=attribute-error
       setattr(cls, '__schema__', schema)
       setattr(cls, '__sym_fields', pg_typing.Dict(schema))
 
@@ -111,6 +96,7 @@ class ObjectMeta(abc.ABCMeta):
         base_schema_list=[cls.__schema__] if extend else [],
         allow_nonconst_keys=True,
         metadata=metadata,
+        for_cls=cls,
     )
     cls.apply_schema(schema)
 
@@ -131,7 +117,7 @@ class ObjectMeta(abc.ABCMeta):
 
     # Register class with 'type' property.
     for key in serialization_keys:
-      object_utils.JSONConvertible.register(
+      utils.JSONConvertible.register(
           key, cls, flags.is_repeated_class_registration_allowed()
       )
 
@@ -164,11 +150,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.
@@ -197,6 +194,7 @@ class ObjectMeta(abc.ABCMeta):
             field.value.freeze(attr_value, apply_before_use=False)
         else:
           field.value.set_default(attr_value)
+        field.set_origin(cls)
 
 
 # Use ObjectMeta as meta class to inherit schema and type_name property.
@@ -313,7 +311,7 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
     Args:
       user_cls: The source class that calls this class method.
     """
-    object_utils.ensure_explicit_method_override(
+    utils.ensure_explicit_method_override(
         cls.__init__,
         (
             '`pg.Object.__init__` is a PyGlove managed method. For setting up '
@@ -321,7 +319,8 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
             '`_on_init()`. If you do have a need to override `__init__` and '
             'know the implications, please decorate your overridden method '
             'with `@pg.explicit_method_override`.'
-        ))
+        ),
+    )
 
     # Set `__serialization_key__` before JSONConvertible.__init_subclass__
     # is called.
@@ -347,6 +346,7 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
           base_schema_list=base_schema_list,
           allow_nonconst_keys=True,
           metadata={},
+          for_cls=user_cls,
       )
 
       # Freeze callable symbolic attributes if they are provided as methods.
@@ -367,11 +367,11 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
     """Normalizes the schema before applying it."""
 
     schema.set_name(cls.__type_name__)
-    docstr = object_utils.docstr(cls)
+    docstr = utils.docstr(cls)
     if docstr:
       schema.set_description(docstr.description)
 
-    def _formalize_field(path: object_utils.KeyPath, node: Any) -> bool:
+    def _formalize_field(path: utils.KeyPath, node: Any) -> bool:
       """Formalize field."""
       if isinstance(node, pg_typing.Field):
         field = node
@@ -389,27 +389,29 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
         if isinstance(field.value, pg_typing.Dict):
           if field.value.schema is not None:
             field.value.schema.set_name(f'{schema.name}.{path.path}')
-            object_utils.traverse(field.value.schema.fields, _formalize_field,
-                                  None, path)
+            utils.traverse(
+                field.value.schema.fields, _formalize_field, None, path
+            )
         elif isinstance(field.value, pg_typing.List):
-          _formalize_field(object_utils.KeyPath(0, path), field.value.element)
+          _formalize_field(utils.KeyPath(0, path), field.value.element)
         elif isinstance(field.value, pg_typing.Tuple):
           for i, elem in enumerate(field.value.elements):
-            _formalize_field(object_utils.KeyPath(i, path), elem)
+            _formalize_field(utils.KeyPath(i, path), elem)
         elif isinstance(field.value, pg_typing.Union):
           for i, c in enumerate(field.value.candidates):
             _formalize_field(
-                object_utils.KeyPath(i, path),
-                pg_typing.Field(field.key, c, 'Union sub-type.'))
+                utils.KeyPath(i, path),
+                pg_typing.Field(field.key, c, 'Union sub-type.'),
+            )
       return True
 
-    object_utils.traverse(schema.fields, _formalize_field)
+    utils.traverse(schema.fields, _formalize_field)
     return schema
 
   @classmethod
   def _finalize_init_arg_list(cls) -> List[str]:
     """Finalizes init_arg_list based on schema."""
-     # Update `init_arg_list`` based on the updated schema.
+    # Update `init_arg_list`` based on the updated schema.
     init_arg_list = cls.__schema__.metadata.get('init_arg_list', None)
     if init_arg_list is None:
       # Inherit from the first non-empty base if they have the same signature.
@@ -480,7 +482,7 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
     # Create a new `__init__` that passes through all the arguments to
     # in `pg.Object.__init__`. This is needed for each class to use different
     # signature.
-    @object_utils.explicit_method_override
+    @utils.explicit_method_override
     @functools.wraps(pseudo_init)
     def _init(self, *args, **kwargs):
       # We pass through the arguments to `Object.__init__` instead of
@@ -509,7 +511,7 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
   def _create_sym_attribute(cls, attr_name, field):
     """Customizable trait: template of single symbolic attribute."""
     return property(
-        object_utils.make_function(
+        coding.make_function(
             attr_name,
             ['self'],
             [f"return self.sym_inferred('{attr_name}')"],
@@ -543,8 +545,8 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
       json_value: Any,
       *,
       allow_partial: bool = False,
-      root_path: Optional[object_utils.KeyPath] = None,
-      **kwargs
+      root_path: Optional[utils.KeyPath] = None,
+      **kwargs,
   ) -> 'Object':
     """Class method that load an symbolic Object from a JSON value.
 
@@ -592,15 +594,16 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
         for k, v in json_value.items()
     })
 
-  @object_utils.explicit_method_override
+  @utils.explicit_method_override
   def __init__(
       self,
       *args,
       allow_partial: bool = False,
       sealed: Optional[bool] = None,
-      root_path: Optional[object_utils.KeyPath] = None,
+      root_path: Optional[utils.KeyPath] = None,
       explicit_init: bool = False,
-      **kwargs):
+      **kwargs,
+  ):
     """Create an Object instance.
 
     Args:
@@ -642,8 +645,8 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
     # Fill field_args and init_args from **kwargs.
     _, unmatched_keys = self.__class__.__schema__.resolve(list(kwargs.keys()))
     if unmatched_keys:
-      arg_phrase = object_utils.auto_plural(len(unmatched_keys), 'argument')
-      keys_str = object_utils.comma_delimited_str(unmatched_keys)
+      arg_phrase = utils.auto_plural(len(unmatched_keys), 'argument')
+      keys_str = utils.comma_delimited_str(unmatched_keys)
       raise TypeError(
           f'{self.__class__.__name__}.__init__() got unexpected '
           f'keyword {arg_phrase}: {keys_str}')
@@ -663,8 +666,8 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
         field_args[vararg_name] = list(args[num_named_args:])
         args = args[:num_named_args]
       elif len(args) > len(init_arg_names):
-        arg_phrase = object_utils.auto_plural(len(init_arg_names), 'argument')
-        was_phrase = object_utils.auto_plural(len(args), 'was', 'were')
+        arg_phrase = utils.auto_plural(len(init_arg_names), 'argument')
+        was_phrase = utils.auto_plural(len(args), 'was', 'were')
         raise TypeError(
             f'{self.__class__.__name__}.__init__() takes '
             f'{len(init_arg_names)} positional {arg_phrase} but {len(args)} '
@@ -676,7 +679,7 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
 
     for k, v in kwargs.items():
       if k in field_args:
-        values_str = object_utils.comma_delimited_str([field_args[k], v])
+        values_str = utils.comma_delimited_str([field_args[k], v])
         raise TypeError(
             f'{self.__class__.__name__}.__init__() got multiple values for '
             f'argument \'{k}\': {values_str}.')
@@ -691,8 +694,8 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
             and field.key not in field_args):
           missing_args.append(str(field.key))
       if missing_args:
-        arg_phrase = object_utils.auto_plural(len(missing_args), 'argument')
-        keys_str = object_utils.comma_delimited_str(missing_args)
+        arg_phrase = utils.auto_plural(len(missing_args), 'argument')
+        keys_str = utils.comma_delimited_str(missing_args)
         raise TypeError(
             f'{self.__class__.__name__}.__init__() missing {len(missing_args)} '
             f'required {arg_phrase}: {keys_str}.')
@@ -742,8 +745,7 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
     and during __init__.
     """
 
-  def _on_change(self,
-                 field_updates: Dict[object_utils.KeyPath, base.FieldUpdate]):
+  def _on_change(self, field_updates: Dict[utils.KeyPath, base.FieldUpdate]):
     """Event that is triggered when field values in the subtree are updated.
 
     This event will be called
@@ -763,8 +765,7 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
     del field_updates
     return self._on_bound()
 
-  def _on_path_change(
-      self, old_path: object_utils.KeyPath, new_path: object_utils.KeyPath):
+  def _on_path_change(self, old_path: utils.KeyPath, new_path: utils.KeyPath):
     """Event that is triggered after the symbolic path changes."""
     del old_path, new_path
 
@@ -843,8 +844,8 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
     return self._sym_attributes.sym_getattr(key)
 
   def _sym_rebind(
-      self, path_value_pairs: Dict[object_utils.KeyPath, Any]
-      ) -> List[base.FieldUpdate]:
+      self, path_value_pairs: Dict[utils.KeyPath, Any]
+  ) -> List[base.FieldUpdate]:
     """Rebind current object using object-form members."""
     if base.treats_as_sealed(self):
       raise base.WritePermissionError(
@@ -883,9 +884,8 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
     return self
 
   def _update_children_paths(
-      self,
-      old_path: object_utils.KeyPath,
-      new_path: object_utils.KeyPath) -> None:
+      self, old_path: utils.KeyPath, new_path: utils.KeyPath
+  ) -> None:
     """Update children paths according to root_path of current node."""
     self._sym_attributes.sym_setpath(new_path)
     self._on_path_change(old_path, new_path)
@@ -969,10 +969,10 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
       return self.sym_hash()
     return super().__hash__()
 
-  def sym_jsonify(self, **kwargs) -> object_utils.JSONValueType:
+  def sym_jsonify(self, **kwargs) -> utils.JSONValueType:
     """Converts current object to a dict of plain Python objects."""
     json_dict = {
-        object_utils.JSONConvertible.TYPE_NAME_KEY: (
+        utils.JSONConvertible.TYPE_NAME_KEY: (
             self.__class__.__serialization_key__
         )
     }
@@ -991,8 +991,9 @@ class Object(base.Symbolic, metaclass=ObjectMeta):
         root_indent,
         cls_name=self.__class__.__name__,
         key_as_attribute=True,
-        bracket_type=object_utils.BracketType.ROUND,
-        **kwargs)
+        bracket_type=utils.BracketType.ROUND,
+        **kwargs,
+    )
 
 
 base.Symbolic.ObjectType = Object