Property

class properties.Property(doc, **kwargs)

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)

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 uses from_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 and properties.undefined are never passed in as values

error(instance, value, error_class=None, extra='')

Generate a ValueError for invalid value assignment

The 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 uses to_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 to error 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. If info is not defined, it defaults to class_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 and deserialize 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 be properties.undefined. However, in some specific cases, it may make sense to override.