pg.JSONConvertible

Accessible via pg.JSONConvertible, pg.utils.JSONConvertible.

class JSONConvertible

Bases: object

Interface for classes whose instances are convertible from/to JSON.

A JSON convertible object is an object that can be converted into plain Python objects, hence can be serialized into or deserialized from JSON.

Subclasses of JSONConvertible should implement:

• to_json: A method that returns a plain Python dict with a _type property whose value should identify the class.

• from_json: A class method that takes a plain Python dict and returns an instance of the class.

Example:

class MyObject(pg.JSONConvertible):

  def __init__(self, x: int):
    self.x = x

  def to_json(self, **kwargs):
    return {
      '_type': 'MyObject',
      'x': self.x
    }

  @classmethod
  def from_json(cls, json_value, **kwargs):
    return cls(json_value['x'])

All symbolic types (see pg.Symbolic) are JSON convertible.

Methods:

TYPE_CONVERTER()	Get converter from source type to a JSON simple type.
add_module_alias(module, alias)	Adds a module alias so previous serialized objects could be loaded.
class_from_typename(type_name)	Gets the class for a registered type name.
from_json(json_value, **kwargs)	Creates an instance of this class from a plain Python value.
is_registered(type_name)	Returns True if a type name is registered.
load_types_for_deserialization(...)	Context manager for loading unregistered types for deserialization.
register(type_name, subclass[, ...])	Registers a class with a type name.
registered_types()	Returns an iterator of registered (serialization key, class) tuples.
to_json(*[, context])	Returns a plain Python value as a representation for this object.
to_json_dict(fields, *[, exclude_default, ...])	Helper method to create JSON dict from class and field.

TYPE_CONVERTER()

Get converter from source type to a JSON simple type.

Return type:

Optional[Callable[[Any], Any]]

classmethod add_module_alias(module, alias)

Adds a module alias so previous serialized objects could be loaded.

Return type:

None

classmethod class_from_typename(type_name)

Gets the class for a registered type name.

Return type:

Optional[Type[pg.JSONConvertible]]

Parameters:

type_name – A string as the global unique type identifier for requested class.

Returns:

A type object if registered, otherwise None.

classmethod from_json(json_value, **kwargs)

Creates an instance of this class from a plain Python value.

NOTE(daiyip): pg.Symbolic overrides from_json class method.

Return type:

pg.JSONConvertible

Parameters:

• json_value – JSON value type.

• **kwargs – Keyword arguments as flags to control object creation.

Returns:

An instance of cls.

classmethod is_registered(type_name)

Returns True if a type name is registered. Otherwise False.

Return type:

bool

classmethod load_types_for_deserialization(*types_to_deserialize)

Context manager for loading unregistered types for deserialization.

Example:

class A(pg.Object):
  auto_register = False
  x: int

class B(A):
  y: str
with pg.JSONConvertile.load_types_for_deserialization(A, B):
    pg.from_json_str(A(1).to_json_str())
    pg.from_json_str(B(1, 'hi').to_json_str())

Return type:

ContextManager[Dict[str, Type[Any]]]

Parameters:

*types_to_deserialize – A list of types to be loaded for deserialization.

Returns:

A context manager within which the objects of the requested types

could be deserialized.

classmethod register(type_name, subclass, override_existing=False)

Registers a class with a type name.

The type name will be used as the key for class lookup during deserialization. A class can be registered with multiple type names, but a type name should be uesd only for one class.

Return type:

None

Parameters:

• type_name – A global unique string identifier for subclass.

• subclass – A subclass of JSONConvertible.

• override_existing – If True, override the class if the type name is already present in the registry. Otherwise an error will be raised.

classmethod registered_types()

Returns an iterator of registered (serialization key, class) tuples.

Return type:

Iterable[Tuple[str, Type[pg.JSONConvertible]]]

abstract to_json(*, context=None, **kwargs)

Returns a plain Python value as a representation for this object.

A plain Python value are basic python types that can be serialized into JSON, e.g: bool, int, float, str, dict (with string keys), list, tuple where the container types should have plain Python values as their values.

Return type:

Union[int, float, bool, str, List[Any], Dict[Union[str, int], Any]]

Parameters:

• context – JSON conversion context.

• **kwargs – Keyword arguments as flags to control JSON conversion.

Returns:

A plain Python value.

classmethod to_json_dict(fields, *, exclude_default=False, exclude_keys=None, **kwargs)

Helper method to create JSON dict from class and field.

Return type:

Dict[str, Union[int, float, bool, str, List[Any], Dict[Union[str, int], Any]]]