pg.wrap

Accessible via pg.wrap, pg.symbolic.wrap.

wrap(cls, init_args=None, *, reset_state_fn=None, repr=True, eq=False, class_name=None, module_name=None, auto_doc=False, auto_typing=False, serialization_key=None, additional_keys=None, override=None)[source]

Makes a symbolic class wrapper from a regular Python class.

pg.wrap is called by pg.symbolize for symbolizing existing Python classes. For example:

class A:
  def __init__(self, x):
    self.x = x

# The following two lines are equivalent.
A1 = pg.symbolize(A)
A2 = pg.wrap(A)

Besides passing the source class, pg.wrap allows the user to pass symbolic field definitions for the init arguments. For example:

A3 = pg.wrap(A, [
  ('x', pg.typing.Int())
])

Moreover, multiple flags are provided to determine whether or not to use the symbolic operations as the default behaviors. For example:

A4 = pg.wrap(
  A,
  [],
  # Instead clearing out all internal states (default),
  # do not reset internal state.
  reset_state_fn=lambda self: None,
  # Use symbolic representation for __repr__ and __str__.
  repr=True,
  # use symbolic equality for __eq__, __ne__ and __hash__.
  eq=True,
  # Customize the class name obtained (the default behaivor
  # is to use the source class name).
  class_name='A4'
  # Customize the module name for created class (the default
  # behavior is to use the source module name).
  module_name='my_module')
Return type:

Type[pg.ClassWrapper]

Parameters:

  • cls – Class to wrap.

  • init_args – An optional list of field definitions for the arguments of __init__. It can be a sparse value specifications for argument in the __init__ method of cls.

  • reset_state_fn – An optional callable object to reset the internal state of the user class when rebind happens.

  • repr – Options for generating __repr__ and __str__. If True (default), use symbolic representation if the user class does not define its own. Otherwise use the user class’ definition. If False, always use non-symbolic representations, which falls back to object.__repr__ and object.__str__ if the user class does not define them.

  • eq – Options for generating __eq__, __ne__ and __hash__. If True and the user_cls defines __eq__, __ne__ and __hash__, use the definitions from the user_cls. If True and the user_cls does not define __eq__, __ne__ and __hash__, use symbolic eq/hash. If False (default), use user_cls’s definition if present, or the definitions from the object class.

  • class_name – An optional string used as class name for the wrapper class. If None, the wrapper class will use the class name of the wrapped class.

  • module_name – An optional string used as module name for the wrapper class. If None, the wrapper class will use the module name of the wrapped class.

  • auto_doc – If True, the descriptions for init argument fields will be extracted from docstring if present.

  • auto_typing – If True, PyGlove typing (runtime-typing) will be enabled based on type annotations inspected from the __init__ method.

  • 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.

  • override – Additional class attributes to override.

Returns:

A subclass of cls and ClassWrapper.

Raises:

TypeError – input cls is not a class.