pg.members

Accessible via pg.members, pg.symbolic.members.

members(fields, metadata=None, init_arg_list=None, **kwargs)[source]

Function/Decorator for declaring symbolic fields for pg.Object.

Example:

@pg.members([
  # Declare symbolic fields. Each field produces a symbolic attribute
  # for its object, which can be accessed by `self.<field_name>`.
  # Description is optional.
  ('x', pg.typing.Int(min_value=0, default=0), 'Description for `x`.'),
  ('y', pg.typing.Str(), 'Description for `y`.')
])
class A(pg.Object):
  def sum(self):
    return self.x + self.y

@pg.members([
  # Override field 'x' inherited from class A and make it more restrictive.
  ('x', pg.typing.Int(max_value=10, default=5)),
  # Add field 'z'.
  ('z', pg.typing.Bool().noneable())
])
class B(A):
  pass

@pg.members([
  # Declare dynamic fields: any keyword can be acceptable during `__init__`
  # and can be accessed using `self.<field_name>`.
  (pg.typing.StrKey(), pg.typing.Int())
])
class D(B):
  pass

@pg.members([
  # Declare dynamic fields: keywords started with 'foo' is acceptable.
  (pg.typing.StrKey('foo.*'), pg.typing.Int())
])
class E(pg.Object):
  pass

See pg.ValueSpec for supported value specifications.

Return type:

~pyglove.core.typing.pytype_support.

Parameters:

  • fields – A list of pg.typing.Field or equivalent tuple representation as (<key>, <value-spec>, [description], [metadata-objects]). key should be a string. value-spec should be pg_typing.ValueSpec classes or equivalent, e.g. primitive values which will be converted to ValueSpec implementation according to its type and used as its default value. description is optional only when field overrides a field from its parent class. metadata-objects is an optional list of any type, which can be used to generate code according to the schema.

  • metadata – Optional dict of user objects as class-level metadata which will be attached to class schema.

  • init_arg_list – An optional sequence of strings as the positional argument list for __init__. This is helpful when symbolic attributes are inherited from base classes or the user want to change its order. If not provided, the init_arg_list will be automatically generated from symbolic attributes defined from pg.members in their declaration order, from the base classes to the subclass.

  • **kwargs – Keyword arguments for infrequently used options. Acceptable keywords are: * serialization_key: An optional string to be used as the serialization key for the class during sym_jsonify. If None, cls.__type_name__ will be used. This is introduced for scenarios when we want to relocate a class, before the downstream can recognize the new location, we need the class to serialize it using previous key. * additional_keys: An optional list of strings as additional keys to deserialize an object of the registered class. This can be useful when we need to relocate or rename the registered class while being able to load existing serialized JSON values.

Returns:

a decorator function that register the class or function with schema

created from the fields.

Raises:

  • TypeError – Decorator cannot be applied on target class or keyword argument provided is not supported.

  • KeyError – If type has already been registered in the registry.

  • ValueError – schema cannot be created from fields.