Base class to enable Property behavior
Classes that inherit HasProperties need simply to declare the Properties they need. HasProperties will save these Properties as
_propson the class. Property values will be saved to
_backendon the instance.
HasProperties classes also store a registry of all HasProperties classes in as
_REGISTRY. If a subclass re-declares
_REGISTRY, the subsequent subclasses will be saved to this new registry.
PropertyMetaclasscontains more information about what goes into HasProperties class construction and validation.
deserialize(value, trusted=False, strict=False, assert_valid=False, **kwargs)¶
Creates HasProperties instance from serialized dictionary
This uses the Property deserializers to deserialize all JSON-compatible dictionary values into their corresponding Property values on a new instance of a HasProperties class. Extra keys in the dictionary that do not correspond to Properties will be ignored.
- value - Dictionary to deserialize new instance from.
- trusted - If True (and if the input dictionary has
'__class__'keyword and this class is in the registry), the new HasProperties class will come from the dictionary. If False (the default), only the HasProperties class this method is called on will be constructed.
- strict - Requires
'__class__', if present on the input dictionary, to match the deserialized instance’s class. Also disallows unused properties in the input dictionary. Default is False.
- assert_valid - Require deserialized instance to be valid. Default is False.
- Any other keyword arguments will be passed through to the Property deserializers.
serialize(include_class=True, save_dynamic=False, **kwargs)¶
Serializes a HasProperties instance to dictionary
This uses the Property serializers to serialize all Property values to a JSON-compatible dictionary. Properties that are undefined are not included. If the HasProperties instance contains a reference to itself, a
properties.SelfReferenceErrorwill be raised.
- include_class - If True (the default), the name of the class
will also be saved to the serialized dictionary under key
- save_dynamic - If True, dynamic properties are written to the serialized dict (default: False).
- Any other keyword arguments will be passed through to the Property serializers.
- include_class - If True (the default), the name of the class will also be saved to the serialized dictionary under key
Call all registered class validator methods
These are all methods decorated with
@properties.validator. Validator methods are expected to raise a ValidationError if they fail.
Metaclass to establish behavior of HasProperties classes
On class construction:
- Build Property dictionary from the class dictionary and the base classes’ Properties.
- Build listener dictionaries from class dictionary and the base classes’ listeners.
- Check Property names are not private.
- Ensure the Property names referred to by Renamed Properties and handlers are valid.
- Build class docstring.
- Construct default value dictionary, and check that any provided defaults are valid.
- Add the class to the HasProperties
_REGISTRYor the closest parent class with a new registry defined
On class instantiation:
- Initialize private backend dictionary where Property values are stored.
- Initialize private listener dictionary and set the listeners on the class instance.
- Set all the default values on the class without firing change notifications.
Functions that act on HasProperties instances:
Return a copy of a HasProperties instance
A copy is produced by serializing the HasProperties instance then deserializing it to a new instance. Therefore, if any properties cannot be serialized/deserialized,
copywill fail. Any keyword arguments will be passed through to both
Determine if two HasProperties instances are equivalent
Equivalence is determined by checking if (1) the two instances are the same class and (2) all Property values on two instances are equal, using
Property.equal. If the two values are the same HasProperties instance (eg.
value_a is value_b) this method returns True. Finally, if either value is not a HasProperties instance, equality is simply checked with ==.
HasProperties objects with recursive self-references will not evaluate to equal, even if their property values and structure are equivalent.
- Documentation - Classes are auto-documented with a sphinx-style docstring.
- Validation - Instances ensure property values remain correct, compatible, and complete.
- Notifications - Classes allow callbacks to be registered for property changes.
- Serialization - Instances may be serialized to and deserialized from JSON.
- Defaults - Default property values can be set at the HasProperties or Property level.
- Registry - All HasProperties classes are saved to a class registry.