Property¶
-
class
properties.
Property
(doc, **kwargs)[source]¶ Property class provides documentation, validation, and serialization
When defined within a HasProperties class, each Property contributes to class documentation, validation, and serialization while behaving for the user just like
@property
values on the class. For examples, see the HasProperties documentation and documentation for specific Property types.Available keywords:
- doc - Docstring for the Property. Must be provided on instantiation.
- default - Default value for the Property. This may be a callable that takes no arguments. Upon HasProperties instantiation, default value is assigned to the Property. If no default is given, the Property value will be undefined.
- required - If True, Property must be given a value for the containing
HasProperties instance to pass
validate()
. If false, the Property may remain undefined. By default, required is True. - serializer - Function that will serialize the Property value when
the containing HasProperties instance is serialized. The serializer
must be a callable that takes the value to be serialized and possibly
keyword arguments passed to
serialize
. By default, the serializer writes to JSON. - deserializer - Function that will deserialize an input value to
a valid Property value when a HasProperties instance is deserialized. The
deserializer must be a callable that takes the value to be deserialized
and possibly keyword arguments passed to
deserialize
. By default, the deserializer writes to JSON. - name - Name of the Property. This is overwritten in the HasProperties metaclass to correspond to the Property’s assigned name.
-
assert_valid
(instance, value=None)[source]¶ Returns True if the Property is valid on a HasProperties instance
Raises a ValueError if the value required and not set, not valid, not correctly coerced, etc.
Note
Unlike
validate
, this method requires instance to be a HasProperties instance; it cannot be None.
-
deserialize
(value, **kwargs)¶ Deserialize input value to valid Property value
This method uses the Property
deserializer
if available. Otherwise, it usesfrom_json
. Any keyword arguments are passed through to these methods.
-
equal
(value_a, value_b)¶ Check if two valid Property values are equal
Note
This method assumes that
None
andproperties.undefined
are never passed in as values
-
error
(instance, value, error_class=None, extra='')¶ Generate a
ValueError
for invalid value assignmentThe instance is the containing HasProperties instance, but it may be None if the error is raised outside a HasProperties class.
-
static
from_json
(value, **kwargs)¶ Statically load a Property value from JSON value
-
meta
¶ Get the tagged metadata of a Property instance
-
serialize
(value, **kwargs)¶ Serialize a valid Property value
This method uses the Property
serializer
if available. Otherwise, it usesto_json
. Any keyword arguments are passed through to these methods.
-
tag
(*tag, **kwtags)¶ Tag a Property instance with metadata dictionary
-
static
to_json
(value, **kwargs)¶ Statically convert a valid Property value to JSON value
-
validate
(instance, value)¶ Check if the value is valid for the Property
If valid, return the value, possibly coerced from the input value. If invalid, a ValueError is raised.
Warning
Calling
validate
again on a coerced value must not modify the value further.Note
This function should be able to handle
instance=None
since valid Property values are independent of containing HasProperties class. However, the instance is passed toerror
for a more verbose error message, and it may be used for additional optional validation.
Defining custom Property types¶
Custom Property types can be created by subclassing
Property
and customizing a few attributes
and methods. These include:
class_info
/info
This are used when documenting the Property.class_info
is a general, descriptive string attribute of the new Property class.info
is an@property
method that gives an instance-specific description of the Property, if necessary. Ifinfo
is not defined, it defaults toclass_info
. This string is used in HasProperties class docstrings and error messages.
validate(self, instance, value)
This method defines what values the Property will accept. It must return the validated value. This value may be coerced from the input value; however, validating on the coerced value must not modify the value further.
The input instance is the containing HasProperties instance or None if the Property is not part of a HasProperties instance, so validate must account for either of these scenarios. Usually, Property validation should be instance-independent.
If value is invalid, a ValueError should be raised by calling
self.error(instance, value)
to_json(value, **kwargs)
/from_json(value, **kwargs)
These static methods should allow converting between a validated Property value and a JSON-dumpable version of the Property value. Both these methods assume the value is valid.
The
serialize
anddeserialize
should not need to be customized in new Properties; they simply call upon these methods.
equal(self, value_a, value_b)
This method defines how valid property values should be compared for equality if the default value_a == value_b is insufficient.
_class_default
This should be set to the default value of the new property class. It may also be a callable that returns the default value. Almost always this should be left untouched; in that case, the default will beproperties.undefined
. However, in some specific cases, it may make sense to override.