HasProperties

class properties.HasProperties(**kwargs)[source]

Base class to enable Property behavior

Classes that inherit HasProperties need simply to declare the Properties they need. HasProperties will save these Properties as _props on the class. Property values will be saved to _backend on 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.

The PropertyMetaclass contains more information about what goes into HasProperties class construction and validation.

classmethod deserialize(value, trusted=False, strict=False, assert_valid=False, **kwargs)[source]

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.

Parameters:

  • 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)[source]

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.SelfReferenceError will be raised.

Parameters:

  • include_class - If True (the default), the name of the class will also be saved to the serialized dictionary under key '__class__'
  • 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.
validate()[source]

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.

class properties.base.PropertyMetaclass[source]

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 _REGISTRY or 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:

properties.copy(value, **kwargs)[source]

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, copy will fail. Any keyword arguments will be passed through to both serialize and deserialize.

properties.equal(value_a, value_b)[source]

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

Note

HasProperties objects with recursive self-references will not evaluate to equal, even if their property values and structure are equivalent.



HasProperties features:

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