pg.Dict¶
Accessible via pg.Dict
, pg.dict
, pg.symbolic.Dict
.
- class Dict(dict_obj=None, *, value_spec=None, onchange_callback=None, **kwargs)[source]¶
Bases:
dict
,pg.Symbolic
,pg.CustomTyping
Symbolic dict.
pg.Dict
implements a dict type whose instances are symbolically programmable, which is a subclass of the built-in Pythondict
and a subclass ofpg.Symbolic
.pg.Dict
provides the following features:It a symbolic programmable dict with string keys.
It enables attribute access on dict keys.
It supports symbolic validation and value completitions based on schema.
It provides events to handle sub-nodes changes.
pg.Dict
can be used as a regular dict with string keys:# Construct a symbolic dict from key value pairs. d = pg.Dict(x=1, y=2)
or:
# Construct a symbolic dict from a mapping object. d = pg.Dict({'x': 1, 'y': 2})
Besides regular items access using
[]
, it allows attribute access to its keys:# Read access to key `x`. assert d.x == 1 # Write access to key 'y'. d.y = 1
pg.Dict
supports symbolic validation when thevalue_spec
argument is provided:d = pg.Dict(x=1, y=2, value_spec=pg.typing.Dict([ ('x', pg.typing.Int(min_value=1)), ('y', pg.typing.Int(min_value=1)), (pg.typing.StrKey('foo.*'), pg.typing.Str()) ]) # Okay: all keys started with 'foo' is acceptable and are strings. d.foo1 = 'abc' # Raises: 'bar' is not acceptable as keys in the dict. d.bar = 'abc'
Users can mutate the values contained in it:
d = pg.Dict(x=pg.Dict(y=1), p=pg.List([0])) d.rebind({ 'x.y': 2, 'p[0]': 1 })
It also allows the users to subscribe subtree updates:
def on_change(updates): print(updates) d = pg.Dict(x=1, onchange_callaback=on_change) # `on_change` will be triggered on item insertion. d['y'] = {'z': 1} # `on_change` will be triggered on item removal. del d.x # `on_change` will also be triggered on subtree change. d.rebind({'y.z': 2})
Classes:
Methods:
Get converter from source type to a JSON simple type.
__copy__
()Overridden shallow copy.
__deepcopy__
(memo)Overridden deep copy.
__eq__
(other)Operator ==.
__hash__
()Overridden hashing function using symbolic hash.
__ne__
(other)Operator !=.
add_module_alias
(source_name, target_name)Adds a module alias so previous serialized objects could be loaded.
class_from_typename
(type_name)Gets the class for a registered type name.
clear
()Removes all the keys in current dict.
clone
([deep, memo, override])Clones current object symbolically.
copy
()Overridden copy using symbolic copy.
custom_apply
(path, value_spec, allow_partial)Implement pg.typing.CustomTyping interface.
format
([compact, verbose, root_indent, ...])Formats this Dict.
from_json
(json_value, *[, value_spec, ...])Class method that load an symbolic Dict from a JSON value.
fromkeys
([value])Create a new dictionary with keys from iterable and values set to value.
get
(key[, default])Return the value for key if key is in the dictionary, else default.
inspect
([path_regex, where, ...])Inspects current object by printing out selected values.
is_registered
(type_name)Returns True if a type name is registered.
items
()Returns an iterator of (key, value) items in current dict.
keys
()Returns an iterator of keys in current dict.
load
(*args, **kwargs)Loads an instance of this type using the global load handler.
missing_values
([flatten])Alias for sym_missing.
non_default_values
([flatten])Alias for sym_nondefault.
partial
([dict_obj, value_spec, ...])Class method that creates a partial Dict object.
pop
(key[, default])Pops a key from current dict.
popitem
()Remove and return a (key, value) pair as a 2-tuple.
rebind
([path_value_pairs, ...])Alias for sym_rebind.
register
(type_name, subclass[, ...])Registers a class with a type name.
Returns an iterator of registered (serialization key, class) tuples.
save
(*args, **kwargs)Saves current object using the global save handler.
seal
([sealed])Seals or unseals current object from further modification.
set_accessor_writable
([writable])Sets accessor writable.
setdefault
(key[, default])Sets default as the value to key if not present.
sym_ancestor
([where])Returns the nearest ancestor of specific classes.
sym_attr_field
(key)Returns the field definition for a symbolic attribute.
sym_clone
([deep, memo, override])Clones current object symbolically.
sym_contains
([value, type])Returns True if the object contains sub-nodes of given value or type.
sym_descendants
([where, option, include_self])Returns all descendants of specific classes.
sym_eq
(other)Returns if this object equals to another object symbolically.
sym_get
(path[, default, use_inferred])Returns a sub-node by path.
sym_getattr
(key[, default])Gets a symbolic attribute.
sym_gt
(other)Returns if this object is symbolically greater than another object.
sym_has
(path)Returns True if a path exists in the sub-tree.
sym_hasattr
(key)Tests if a symbolic attribute exists.
sym_hash
()Symbolic hashing.
sym_inferrable
(key, **kwargs)Returns True if the attribute under key can be inferred.
sym_inferred
(key[, default])Returns the inferred value of the attribute under key.
Iterates the (key, value) pairs of symbolic attributes.
sym_jsonify
([hide_default_values, ...])Converts current object to a dict with plain Python objects.
sym_keys
()Iterates the keys of symbolic attributes.
sym_lt
(other)Returns True if this object is symbolically less than other object.
sym_missing
([flatten])Returns missing values.
sym_ne
(other)Returns if this object does not equal to another object symbolically.
sym_nondefault
([flatten])Returns missing values.
sym_rebind
([path_value_pairs, ...])Mutates the sub-nodes of current object.
sym_seal
([is_seal])Seals or unseals current object from further modification.
sym_setorigin
(source, tag[, stacktrace, ...])Sets the symbolic origin of current object.
sym_setparent
(parent)Override set parent of Dict to handle the passing through scenario.
sym_setpath
(path)Sets the path of current node in its symbolic tree.
Iterates the values of symbolic attributes.
to_json
(**kwargs)Alias for sym_jsonify.
to_json_dict
(fields, *[, exclude_default, ...])Helper method to create JSON dict from class and field.
to_json_str
([json_indent])Serializes current object into a JSON string.
update
([other])Update Dict with the same semantic as update on standard dict.
use_value_spec
(value_spec[, allow_partial])Applies a
pg.typing.Dict
as the value spec for current dict.values
()Returns an iterator of values in current dict..
Attributes:
Returns True if mutation can be made by attribute assignment.
Returns True if partial binding is allowed.
Alias for sym_abstract.
Returns if current object is deterministic.
Alias for sym_partial.
Alias for sym_puresymbolic.
Alias for sym_sealed.
Returns True if current value is abstract (partial or pure symbolic).
Returns the symbolic field for current object.
Returns the symbolic origin of current object.
Returns the containing symbolic object.
Returns True if current value is partial.
Returns the path of current object from the root of its symbolic tree.
Returns True if current value is or contains subnodes of PureSymbolic.
Returns the root of the symbolic tree.
Returns True if current object is sealed.
Returns value spec of this dict.
- DictType[source]¶
alias of
pg.Dict
Classes:Methods:
TYPE_CONVERTER
()Get converter from source type to a JSON simple type.
__copy__
()Overridden shallow copy.
__deepcopy__
(memo)Overridden deep copy.
__eq__
(other)Operator ==.
__hash__
()Overridden hashing function using symbolic hash.
__ne__
(other)Operator !=.
add_module_alias
(source_name, target_name)Adds a module alias so previous serialized objects could be loaded.
class_from_typename
(type_name)Gets the class for a registered type name.
clear
()Removes all the keys in current dict.
clone
([deep, memo, override])Clones current object symbolically.
copy
()Overridden copy using symbolic copy.
custom_apply
(path, value_spec, allow_partial)Implement pg.typing.CustomTyping interface.
format
([compact, verbose, root_indent, ...])Formats this Dict.
from_json
(json_value, *[, value_spec, ...])Class method that load an symbolic Dict from a JSON value.
fromkeys
([value])Create a new dictionary with keys from iterable and values set to value.
get
(key[, default])Return the value for key if key is in the dictionary, else default.
inspect
([path_regex, where, ...])Inspects current object by printing out selected values.
is_registered
(type_name)Returns True if a type name is registered.
items
()Returns an iterator of (key, value) items in current dict.
keys
()Returns an iterator of keys in current dict.
load
(*args, **kwargs)Loads an instance of this type using the global load handler.
missing_values
([flatten])Alias for sym_missing.
non_default_values
([flatten])Alias for sym_nondefault.
partial
([dict_obj, value_spec, ...])Class method that creates a partial Dict object.
pop
(key[, default])Pops a key from current dict.
popitem
()Remove and return a (key, value) pair as a 2-tuple.
rebind
([path_value_pairs, ...])Alias for sym_rebind.
register
(type_name, subclass[, ...])Registers a class with a type name.
registered_types
()Returns an iterator of registered (serialization key, class) tuples.
save
(*args, **kwargs)Saves current object using the global save handler.
seal
([sealed])Seals or unseals current object from further modification.
set_accessor_writable
([writable])Sets accessor writable.
setdefault
(key[, default])Sets default as the value to key if not present.
sym_ancestor
([where])Returns the nearest ancestor of specific classes.
sym_attr_field
(key)Returns the field definition for a symbolic attribute.
sym_clone
([deep, memo, override])Clones current object symbolically.
sym_contains
([value, type])Returns True if the object contains sub-nodes of given value or type.
sym_descendants
([where, option, include_self])Returns all descendants of specific classes.
sym_eq
(other)Returns if this object equals to another object symbolically.
sym_get
(path[, default, use_inferred])Returns a sub-node by path.
sym_getattr
(key[, default])Gets a symbolic attribute.
sym_gt
(other)Returns if this object is symbolically greater than another object.
sym_has
(path)Returns True if a path exists in the sub-tree.
sym_hasattr
(key)Tests if a symbolic attribute exists.
sym_hash
()Symbolic hashing.
sym_inferrable
(key, **kwargs)Returns True if the attribute under key can be inferred.
sym_inferred
(key[, default])Returns the inferred value of the attribute under key.
sym_items
()Iterates the (key, value) pairs of symbolic attributes.
sym_jsonify
([hide_default_values, ...])Converts current object to a dict with plain Python objects.
sym_keys
()Iterates the keys of symbolic attributes.
sym_lt
(other)Returns True if this object is symbolically less than other object.
sym_missing
([flatten])Returns missing values.
sym_ne
(other)Returns if this object does not equal to another object symbolically.
sym_nondefault
([flatten])Returns missing values.
sym_rebind
([path_value_pairs, ...])Mutates the sub-nodes of current object.
sym_seal
([is_seal])Seals or unseals current object from further modification.
sym_setorigin
(source, tag[, stacktrace, ...])Sets the symbolic origin of current object.
sym_setparent
(parent)Override set parent of Dict to handle the passing through scenario.
sym_setpath
(path)Sets the path of current node in its symbolic tree.
sym_values
()Iterates the values of symbolic attributes.
to_json
(**kwargs)Alias for sym_jsonify.
to_json_dict
(fields, *[, exclude_default, ...])Helper method to create JSON dict from class and field.
to_json_str
([json_indent])Serializes current object into a JSON string.
update
([other])Update Dict with the same semantic as update on standard dict.
use_value_spec
(value_spec[, allow_partial])Applies a
pg.typing.Dict
as the value spec for current dict.values
()Returns an iterator of values in current dict..
Attributes:
accessor_writable
Returns True if mutation can be made by attribute assignment.
allow_partial
Returns True if partial binding is allowed.
is_abstract
Alias for sym_abstract.
is_deterministic
Returns if current object is deterministic.
is_partial
Alias for sym_partial.
is_pure_symbolic
Alias for sym_puresymbolic.
is_sealed
Alias for sym_sealed.
sym_abstract
Returns True if current value is abstract (partial or pure symbolic).
sym_field
Returns the symbolic field for current object.
sym_origin
Returns the symbolic origin of current object.
sym_parent
Returns the containing symbolic object.
sym_partial
Returns True if current value is partial.
sym_path
Returns the path of current object from the root of its symbolic tree.
sym_puresymbolic
Returns True if current value is or contains subnodes of PureSymbolic.
sym_root
Returns the root of the symbolic tree.
sym_sealed
Returns True if current object is sealed.
value_spec
Returns value spec of this dict.
- ListType[source]¶
alias of
pg.List
Classes:Methods:
TYPE_CONVERTER
()Get converter from source type to a JSON simple type.
__copy__
()List.copy.
__deepcopy__
(memo)Overridden deep copy.
__eq__
(value, /)Return self==value.
__hash__
()Overriden hashing function.
__ne__
(value, /)Return self!=value.
add_module_alias
(source_name, target_name)Adds a module alias so previous serialized objects could be loaded.
append
(value)Appends an item.
class_from_typename
(type_name)Gets the class for a registered type name.
clear
()Clears the list.
clone
([deep, memo, override])Clones current object symbolically.
copy
()Shallow current list.
count
(value, /)Return number of occurrences of value.
custom_apply
(path, value_spec, allow_partial)Implement pg.typing.CustomTyping interface.
extend
(other)Extend list by appending elements from the iterable.
format
([compact, verbose, root_indent, ...])Formats this List.
from_json
(json_value, *[, value_spec, ...])Class method that load an symbolic List from a JSON value.
index
(value[, start, stop])Return first index of value.
insert
(index, value)Inserts an item at a given position.
inspect
([path_regex, where, ...])Inspects current object by printing out selected values.
is_registered
(type_name)Returns True if a type name is registered.
load
(*args, **kwargs)Loads an instance of this type using the global load handler.
missing_values
([flatten])Alias for sym_missing.
non_default_values
([flatten])Alias for sym_nondefault.
partial
([items, value_spec, onchange_callback])Class method that creates a partial List object.
pop
([index])Pop an item and return its value.
rebind
([path_value_pairs, ...])Alias for sym_rebind.
register
(type_name, subclass[, ...])Registers a class with a type name.
registered_types
()Returns an iterator of registered (serialization key, class) tuples.
remove
(value)Removes the first occurrence of the value.
reverse
()Reverse the elements of the list in place.
save
(*args, **kwargs)Saves current object using the global save handler.
seal
([sealed])Seal or unseal current object from further modification.
set_accessor_writable
([writable])Sets accessor writable.
sort
(*[, key, reverse])Sorts the items of the list in place..
sym_ancestor
([where])Returns the nearest ancestor of specific classes.
sym_attr_field
(key)Returns the field definition for a symbolic attribute.
sym_clone
([deep, memo, override])Clones current object symbolically.
sym_contains
([value, type])Returns True if the object contains sub-nodes of given value or type.
sym_descendants
([where, option, include_self])Returns all descendants of specific classes.
sym_eq
(other)Returns if this object equals to another object symbolically.
sym_get
(path[, default, use_inferred])Returns a sub-node by path.
sym_getattr
(key[, default])Gets a symbolic attribute.
sym_gt
(other)Returns if this object is symbolically greater than another object.
sym_has
(path)Returns True if a path exists in the sub-tree.
sym_hasattr
(key)Tests if a symbolic attribute exists.
sym_hash
()Symbolically hashing.
sym_inferrable
(key, **kwargs)Returns True if the attribute under key can be inferred.
sym_inferred
(key[, default])Returns the inferred value of the attribute under key.
sym_items
()Iterates the (key, value) pairs of symbolic attributes.
sym_jsonify
([use_inferred])Converts current list to a list of plain Python objects.
sym_keys
()Symbolically iterates indices.
sym_lt
(other)Returns True if this object is symbolically less than other object.
sym_missing
([flatten])Returns missing values.
sym_ne
(other)Returns if this object does not equal to another object symbolically.
sym_nondefault
([flatten])Returns missing values.
sym_rebind
([path_value_pairs, ...])Mutates the sub-nodes of current object.
sym_seal
([is_seal])Seals or unseals current object from further modification.
sym_setorigin
(source, tag[, stacktrace, ...])Sets the symbolic origin of current object.
sym_setparent
(parent)Sets the parent of current node in the symbolic tree.
sym_setpath
(path)Sets the path of current node in its symbolic tree.
sym_values
()Iterates the values of symbolic attributes.
to_json
(**kwargs)Alias for sym_jsonify.
to_json_dict
(fields, *[, exclude_default, ...])Helper method to create JSON dict from class and field.
to_json_str
([json_indent])Serializes current object into a JSON string.
use_value_spec
(value_spec[, allow_partial])Applies a
pg.List
as the value spec for current list.Attributes:
accessor_writable
Returns True if mutation can be made by attribute assignment.
allow_partial
Returns True if partial binding is allowed.
is_abstract
Alias for sym_abstract.
is_deterministic
Returns if current object is deterministic.
is_partial
Alias for sym_partial.
is_pure_symbolic
Alias for sym_puresymbolic.
is_sealed
Alias for sym_sealed.
max_size
Returns max size of this list.
sym_abstract
Returns True if current value is abstract (partial or pure symbolic).
sym_field
Returns the symbolic field for current object.
sym_origin
Returns the symbolic origin of current object.
sym_parent
Returns the containing symbolic object.
sym_partial
Returns True if current value is partial.
sym_path
Returns the path of current object from the root of its symbolic tree.
sym_puresymbolic
Returns True if current value is or contains subnodes of PureSymbolic.
sym_root
Returns the root of the symbolic tree.
sym_sealed
Returns True if current object is sealed.
value_spec
Returns value spec of this List.
- ObjectType[source]¶
alias of
pg.Object
Classes:Methods:
TYPE_CONVERTER
()Get converter from source type to a JSON simple type.
__copy__
()Overridden shallow copy.
__deepcopy__
(memo)Overridden deep copy.
__eq__
(other)Operator==.
__hash__
()Hashing function.
__ne__
(other)Operator!=.
add_module_alias
(source_name, target_name)Adds a module alias so previous serialized objects could be loaded.
class_from_typename
(type_name)Gets the class for a registered type name.
clone
([deep, memo, override])Clones current object symbolically.
format
([compact, verbose, root_indent])Formats this object.
from_json
(json_value, *[, allow_partial, ...])Class method that load an symbolic Object from a JSON value.
inspect
([path_regex, where, ...])Inspects current object by printing out selected values.
is_registered
(type_name)Returns True if a type name is registered.
load
(*args, **kwargs)Loads an instance of this type using the global load handler.
missing_values
([flatten])Alias for sym_missing.
non_default_values
([flatten])Alias for sym_nondefault.
partial
(*args, **kwargs)Class method that creates a partial object of current class.
rebind
([path_value_pairs, ...])Alias for sym_rebind.
register
(type_name, subclass[, ...])Registers a class with a type name.
registered_types
()Returns an iterator of registered (serialization key, class) tuples.
save
(*args, **kwargs)Saves current object using the global save handler.
seal
([sealed])Seal or unseal current object from further modification.
set_accessor_writable
([writable])Sets accessor writable.
sym_ancestor
([where])Returns the nearest ancestor of specific classes.
sym_attr_field
(key)Returns the field definition for a symbolic attribute.
sym_clone
([deep, memo, override])Clones current object symbolically.
sym_contains
([value, type])Returns True if the object contains sub-nodes of given value or type.
sym_descendants
([where, option, include_self])Returns all descendants of specific classes.
sym_eq
(other)Tests symbolic equality.
sym_get
(path[, default, use_inferred])Returns a sub-node by path.
sym_getattr
(key[, default])Gets a symbolic attribute.
sym_gt
(other)Returns if this object is symbolically greater than another object.
sym_has
(path)Returns True if a path exists in the sub-tree.
sym_hasattr
(key)Tests if a symbolic attribute exists.
sym_hash
()Symbolically hashing.
sym_inferrable
(key, **kwargs)Returns True if the attribute under key can be inferred.
sym_inferred
(key[, default])Returns the inferred value of the attribute under key.
sym_items
()Iterates the (key, value) pairs of symbolic attributes.
sym_jsonify
(**kwargs)Converts current object to a dict of plain Python objects.
sym_keys
()Iterates the keys of symbolic attributes.
sym_lt
(other)Tests symbolic less-than.
sym_missing
([flatten])Returns missing values.
sym_ne
(other)Returns if this object does not equal to another object symbolically.
sym_nondefault
([flatten])Returns missing values.
sym_rebind
([path_value_pairs, ...])Mutates the sub-nodes of current object.
sym_seal
([is_seal])Seals or unseals current object from further modification.
sym_setorigin
(source, tag[, stacktrace, ...])Sets the symbolic origin of current object.
sym_setparent
(parent)Sets the parent of current node in the symbolic tree.
sym_setpath
(path)Sets the path of current node in its symbolic tree.
sym_values
()Iterates the values of symbolic attributes.
to_json
(**kwargs)Alias for sym_jsonify.
to_json_dict
(fields, *[, exclude_default, ...])Helper method to create JSON dict from class and field.
to_json_str
([json_indent])Serializes current object into a JSON string.
Attributes:
accessor_writable
Returns True if mutation can be made by attribute assignment.
allow_partial
Returns True if partial binding is allowed.
is_abstract
Alias for sym_abstract.
is_deterministic
Returns if current object is deterministic.
is_partial
Alias for sym_partial.
is_pure_symbolic
Alias for sym_puresymbolic.
is_sealed
Alias for sym_sealed.
sym_abstract
Returns True if current value is abstract (partial or pure symbolic).
sym_field
Returns the symbolic field for current object.
sym_init_args
Returns the symbolic attributes which are also the __init__ args.
sym_origin
Returns the symbolic origin of current object.
sym_parent
Returns the containing symbolic object.
sym_partial
Returns True if current value is partial.
sym_path
Returns the path of current object from the root of its symbolic tree.
sym_puresymbolic
Returns True if current value is or contains subnodes of PureSymbolic.
sym_root
Returns the root of the symbolic tree.
sym_sealed
Returns True if current object is sealed.
- property accessor_writable: bool[source]¶
Returns True if mutation can be made by attribute assignment.
- classmethod add_module_alias(source_name, target_name)[source]¶
Adds a module alias so previous serialized objects could be loaded.
- Return type:
- classmethod class_from_typename(type_name)[source]¶
Gets the class for a registered type name.
- Return type:
- Parameters:
type_name – A string as the global unique type identifier for requested class.
- Returns:
A type object if registered, otherwise None.
- clone(deep=False, memo=None, override=None)[source]¶
Clones current object symbolically.
- Return type:
- Parameters:
deep – If True, perform deep copy (equivalent to copy.deepcopy). Otherwise shallow copy (equivalent to copy.copy).
memo – Memo object for deep clone.
override – An optional dict of key path to new values to override cloned value.
- Returns:
A copy of self.
- custom_apply(path, value_spec, allow_partial, child_transform=None)[source]¶
Implement pg.typing.CustomTyping interface.
- Return type:
- Parameters:
path – KeyPath of current object.
value_spec – Origin value spec of the field.
allow_partial – Whether allow partial object to be created.
child_transform – Function to transform child node values in dict_obj into their final values. Transform function is called on leaf nodes first, then on their containers, recursively.
- Returns:
A tuple (proceed_with_standard_apply, transformed value)
- format(compact=False, verbose=True, root_indent=0, *, python_format=False, markdown=False, hide_default_values=False, hide_missing_values=False, include_keys=None, exclude_keys=None, use_inferred=False, cls_name=None, bracket_type=BracketType.CURLY, key_as_attribute=False, extra_blankline_for_field_docstr=False, **kwargs)[source]¶
Formats this Dict.
- Return type:
- classmethod from_json(json_value, *, value_spec=None, allow_partial=False, root_path=None, **kwargs)[source]¶
Class method that load an symbolic Dict from a JSON value.
- Return type:
- Parameters:
json_value – Input JSON value, only JSON dict is acceptable.
value_spec – An optional value spec to apply.
allow_partial – Whether to allow members of the dict to be partial.
root_path – KeyPath of loaded object in its object tree.
**kwargs – Allow passing through keyword arguments that are not applicable.
- Returns:
A schemaless symbolic dict. For example:
d = Dict.from_json({ 'a': { '_type': '__main__.Foo', 'f1': 1, 'f2': { 'f21': True } } }) assert d.value_spec is None # Okay: d.b = 1 # a.f2 is bound by class Foo's field 'f2' definition (assume it defines # a schema for the Dict field). assert d.a.f2.value_spec is not None # Not okay: d.a.f2.abc = 1
- fromkeys(value=None, /)¶
Create a new dictionary with keys from iterable and values set to value.
- get(key, default=None, /)¶
Return the value for key if key is in the dictionary, else default.
- inspect(path_regex=None, where=None, custom_selector=None, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, **kwargs)[source]¶
Inspects current object by printing out selected values.
Example:
@pg.members([ ('x', pg.typing.Int(0)), ('y', pg.typing.Str()) ]) class A(pg.Object): pass value = { 'a1': A(x=0, y=0), 'a2': [A(x=1, y=1), A(x=1, y=2)], 'a3': { 'p': A(x=2, y=1), 'q': A(x=2, y=2) } } # Inspect without constraint, # which is equivalent as `print(value.format(hide_default_values=True))` # Shall print: # { # a1 = A(y=0) # a2 = [ # 0: A(x=1, y=1) # 1: A(x=1, y=2) # a3 = { # p = A(x=2, y=1) # q = A(x=2, y=2) # } # } value.inspect(hide_default_values=True) # Inspect by path regex. # Shall print: # {'a3.p': A(x=2, y=1)} value.inspect(r'.*p') # Inspect by value. # Shall print: # { # 'a3.p.x': 2, # 'a3.q.x': 2, # 'a3.q.y': 2, # } value.inspect(where=lambda v: v==2) # Inspect by path, value and parent. # Shall print: # { # 'a2[1].y': 2 # } value.inspect( r'.*y', where=lambda v, p: v > 1 and isinstance(p, A) and p.x == 1)) # Inspect by custom_selector. # Shall print: # { # 'a2[0].x': 1, # 'a2[0].y': 1, # 'a3.q.x': 2, # 'a3.q.y': 2 # } value.inspect( custom_selector=lambda k, v, p: ( len(k) == 3 and isinstance(p, A) and p.x == v))
- Return type:
- Parameters:
path_regex – Optional regex expression to constrain path.
where – Optional callable to constrain value and parent when path matches path_regex or path_regex is not provided. The signature is: (value) -> should_select, or (value, parent) -> should_select.
custom_selector – Optional callable object as custom selector. When custom_selector is provided, path_regex and where must be None. The signature of custom_selector is: (key_path, value) -> should_select or (key_path, value, parent) -> should_select.
file – Output file stream. This can be any object with a write(str) method.
**kwargs – Wildcard keyword arguments to pass to format.
- classmethod is_registered(type_name)[source]¶
Returns True if a type name is registered. Otherwise False.
- Return type:
- classmethod load(*args, **kwargs)[source]¶
Loads an instance of this type using the global load handler.
- Return type:
- classmethod partial(dict_obj=None, value_spec=None, *, onchange_callback=None, **kwargs)[source]¶
Class method that creates a partial Dict object.
- Return type:
- popitem()[source]¶
Remove and return a (key, value) pair as a 2-tuple.
Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.
- rebind(path_value_pairs=None, *, raise_on_no_change=True, notify_parents=True, skip_notification=None, **kwargs)[source]¶
Alias for sym_rebind.
Alias for sym_rebind. rebind is the recommended way for mutating symbolic objects in PyGlove: :rtype:
pg.Symbolic
It allows mutations not only on immediate child nodes, but on the entire sub-tree.
It allows mutations by rules via passing a callable object as the value for path_value_pairs.
It batches the updates from multiple sub-nodes, which triggers the _on_change or _on_bound event once for recomputing the parent object’s internal states.
It respects the “sealed” flag of the object or the pg.seal context manager to trigger permission error.
Example:
# # Rebind on pg.Object subclasses. # @pg.members([ ('x', pg.typing.Dict([ ('y', pg.typing.Int(default=0)) ])), ('z', pg.typing.Int(default=1)) ]) class A(pg.Object): pass a = A() # Rebind using path-value pairs. a.rebind({ 'x.y': 1, 'z': 0 }) # Rebind using **kwargs. a.rebind(x={y: 1}, z=0) # Rebind using rebinders. # Rebind based on path. a.rebind(lambda k, v: 1 if k == 'x.y' else v) # Rebind based on key. a.rebind(lambda k, v: 1 if k and k.key == 'y' else v) # Rebind based on value. a.rebind(lambda k, v: 0 if v == 1 else v) # Rebind baesd on value and parent. a.rebind(lambda k, v, p: (0 if isinstance(p, A) and isinstance(v, int) else v)) # Rebind on pg.Dict. # d = pg.Dict(value_spec=pg.typing.Dict([ ('a', pg.typing.Dict([ ('b', pg.typing.Int()), ])), ('c', pg.typing.Float()) ]) # Rebind using **kwargs. d.rebind(a={b: 1}, c=1.0) # Rebind using key path to value dict. d.rebind({ 'a.b': 2, 'c': 2.0 }) # NOT OKAY: **kwargs and dict/rebinder cannot be used at the same time. d.rebind({'a.b': 2}, c=2) # Rebind with rebinder by path (on subtree). d.rebind(lambda k, v: 1 if k.key == 'b' else v) # Rebind with rebinder by value (on subtree). d.rebind(lambda k, v: 0 if isinstance(v, int) else v) # # Rebind on pg.List. # l = pg.List([{ 'a': 'foo', 'b': 0, } ], value_spec = pg.typing.List(pg.typing.Dict([ ('a', pg.typing.Str()), ('b', pg.typing.Int()) ]), max_size=10)) # Rebind using integer as list index: update semantics on list[0]. l.rebind({ 0: { 'a': 'bar', 'b': 1 } }) # Rebind: trigger append semantics when index is larger than list length. l.rebind({ 999: { 'a': 'fun', 'b': 2 } }) # Rebind using key path. l.rebind({ '[0].a': 'bar2' '[1].b': 3 }) # Rebind using function (rebinder). # Change all integers to 0 in sub-tree. l.rebind(lambda k, v: v if not isinstance(v, int) else 0)
- Parameters:
path_value_pairs –
A dictionary of key/or key path to new field value, or a function that generate updates based on the key path, value and parent of each node under current object. We use terminology ‘rebinder’ for this type of functions. The signature of a rebinder is:
(key_path: pg.KeyPath, value: Any) or (key_path: pg.KeyPath, value: Any, parent: pg.Symbolic)
raise_on_no_change – If True, raises
ValueError
when there are no values to change. This is useful when rebinder is used, which may or may not generate any updates.notify_parents – If True (default), parents will be notified upon change. Otherwisee only the current object and the impacted children will be notified. A most common use case for setting this flag to False is when users want to rebind a child within the parent _on_bound method.
skip_notification – If True, there will be no
_on_change
event triggered from current rebind. If None, the default value will be inferred from thepg.notify_on_change
context manager. Use it only when you are certain that current rebind does not invalidate internal states of its object tree.**kwargs – For
pg.Dict
andpg.Object
subclasses, user can use keyword arguments (in format of <field_name>=<field_value>) to directly modify immediate child nodes.
- Returns:
Self.
- Raises:
WritePermissionError – If object is sealed.
KeyError – If update location specified by key or key path is not aligned with the schema of the object tree.
TypeError – If updated field value type does not conform to field spec.
ValueError – If updated field value is not acceptable according to field spec, or nothing is updated and raise_on_no_change is set to True.
- classmethod register(type_name, subclass, override_existing=False)[source]¶
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:
- 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()[source]¶
Returns an iterator of registered (serialization key, class) tuples.
- Return type:
- setdefault(key, default=None)[source]¶
Sets default as the value to key if not present.
- Return type:
- property sym_abstract: bool[source]¶
Returns True if current value is abstract (partial or pure symbolic).
- sym_contains(value=None, type=None)[source]¶
Returns True if the object contains sub-nodes of given value or type.
- Return type:
- sym_descendants(where=None, option=DescendantQueryOption.ALL, include_self=False)[source]¶
Returns all descendants of specific classes.
- Return type:
- Parameters:
where – Optional callable object as the filter of descendants to return.
option – Descendant query options, indicating whether all matched, immediate matched or only the matched leaf nodes will be returned.
include_self – If True, self will be included in the query, otherwise only strict descendants are included.
- Returns:
A list of objects that match the descendant_cls.
- sym_get(path, default=(MISSING_VALUE,), use_inferred=False)[source]¶
Returns a sub-node by path.
NOTE: there is no sym_set, use sym_rebind.
- Return type:
- Parameters:
path – A KeyPath object or equivalence.
default – Default value if path does not exists. If absent, KeyError will be thrown.
use_inferred – If True, return inferred value instead of the symbolic form of pg.Inferential objects.
- Returns:
Value of symbolic attribute specified by path if found, otherwise the default value if it’s specified.
- Raises:
KeyError if path does not exist and default is not specified. –
- sym_getattr(key, default=(MISSING_VALUE,))[source]¶
Gets a symbolic attribute.
- Return type:
- Parameters:
key – Key of symbolic attribute.
default – Default value if attribute does not exist. If absent,
- Returns:
Value of symbolic attribute if found, otherwise the default value if it’s specified.
- Raises:
AttributeError if key does not exist and default is not provided. –
- sym_gt(other)[source]¶
Returns if this object is symbolically greater than another object.
- Return type:
- sym_has(path)[source]¶
Returns True if a path exists in the sub-tree.
- Return type:
- Parameters:
path – A KeyPath object or equivalence.
- Returns:
True if the path exists in current sub-tree, otherwise False.
- sym_inferrable(key, **kwargs)[source]¶
Returns True if the attribute under key can be inferred.
- Return type:
- sym_inferred(key, default=(MISSING_VALUE,), **kwargs)[source]¶
Returns the inferred value of the attribute under key.
- Return type:
- sym_jsonify(hide_default_values=False, exclude_keys=None, use_inferred=False, **kwargs)[source]¶
Converts current object to a dict with plain Python objects.
- sym_lt(other)[source]¶
Returns True if this object is symbolically less than other object.
- Return type:
- sym_ne(other)[source]¶
Returns if this object does not equal to another object symbolically.
- Return type:
- property sym_path: KeyPath[source]¶
Returns the path of current object from the root of its symbolic tree.
- property sym_puresymbolic: bool[source]¶
Returns True if current value is or contains subnodes of PureSymbolic.
- sym_rebind(path_value_pairs=None, *, raise_on_no_change=True, notify_parents=True, skip_notification=None, **kwargs)[source]¶
Mutates the sub-nodes of current object. Please see rebind.
- Return type:
- sym_seal(is_seal=True)[source]¶
Seals or unseals current object from further modification.
- Return type:
- sym_setorigin(source, tag, stacktrace=None, stacklimit=None, stacktop=-1)[source]¶
Sets the symbolic origin of current object.
- Parameters:
source – Source value for current object.
tag – A descriptive tag of the origin. Built-in tags are: __init__, clone, deepclone, return. Users can manually call sym_setorigin with custom tag value.
stacktrace – If True, enable stack trace for the origin. If None, enable stack trace if pg.tracek_origin() is called. Otherwise stack trace is disabled.
stacklimit – An optional integer to limit the stack depth. If None, it’s determined by the value passed to pg.set_origin_stacktrace_limit, which is 10 by default.
stacktop – A negative or zero-value integer indicating the stack top among the stack frames that we want to present to user, by default it’s 1-level up from the stack within current sym_setorigin call.
Example:
def foo(): return bar() def bar(): s = MyObject() t = s.build() t.sym_setorigin(s, 'builder', stacktrace=True, stacklimit=5, stacktop=-1)
This example sets the origin of t using s as its source with tag ‘builder’. We also record the callstack where the sym_setorigin is called, so users can call t.sym_origin.stacktrace to get the call stack later. The stacktop -1 indicates that we do not need the stack frame within
sym_setorigin
, so users will see the stack top within the function bar. We also set the max number of stack frames to display to 5, not including the stack frame insidesym_setorigin
.
- classmethod to_json_dict(fields, *, exclude_default=False, exclude_keys=None, **kwargs)[source]¶
Helper method to create JSON dict from class and field.
- to_json_str(json_indent=None, **kwargs)[source]¶
Serializes current object into a JSON string.
- Return type:
- update(other=None, **kwargs)[source]¶
Update Dict with the same semantic as update on standard dict.
- Return type:
- use_value_spec(value_spec, allow_partial=False)[source]¶
Applies a
pg.typing.Dict
as the value spec for current dict.- Return type:
- Parameters:
value_spec – A Dict ValueSpec to apply to this Dict. If current Dict is schema-less (whose immediate members are not validated against schema), and value_spec is not None, the value spec will be applied to the Dict. Or else if current Dict is already symbolic (whose immediate members are under the constraint of a Dict value spec), and value_spec is None, current Dict will become schema-less. However, the schema constraints for non-immediate members will remain.
allow_partial – Whether allow partial dict based on the schema. This flag will override allow_partial flag in __init__ for spec-less Dict.
- Returns:
Self.
- Raises:
ValueError – validation failed due to value error.
RuntimeError – Dict is already bound with another spec.
TypeError – type errors during validation.
KeyError – key errors during validation.