fsleyes_props.properties

Python descriptor framework.

This module defines the PropertyBase, ListPropertyBase, which form the basis for defining class properties; and the HasProperties class, which is intended to be sub-classed by application code.

HasProperties	Base class for classes which contain PropertyBase instances.
PropertyBase	The base class for properties.
ListPropertyBase	A PropertyBase for properties which encapsulate more than one value.

exception fsleyes_props.properties.DisabledError

Bases: Exception

A DisabledError is raised when an attempt is made to assign a value to a disabled property. See the PropertyBase.enable() and PropertyBase.disable() methods.

class fsleyes_props.properties.PropertyBase(default=None, validateFunc=None, equalityFunc=None, required=False, allowInvalid=True, **atts)

Bases: object

The base class for properties.

For every HasProperties instance which has this PropertyBase object as a property, one _InstanceData object is created and attached as an attribute of the HasProperties object.

One important point to note is that a PropertyBase object may exist without being bound to a HasProperties instance (in which case it will not create or manage any PropertyValue instances). This is useful if you just want validation functionality via the validate(), getAttribute() and setAttribute() methods, passing in None for the instance parameter. Nothing else will work properly though.

Several subclasses are defined in the properties_types module. All subclasses should:

• Ensure that the superclass __init__() is called.

• Override the validate() method to implement any built in validation rules, ensuring that the the superclass implementation is called first (see the Number property for an example).

• Override the cast() method for implicit casting/conversion logic (see the Boolean property for an example).

Define a PropertyBase property.

Parameters:

• default – Default/initial value.

• required (bool) – Boolean determining whether or not this property must have a value. May alternately be a function which accepts one parameter, the owning HasProperties instance, and returns True or False.

• validateFunc – Custom validation function. Must accept three parameters: a reference to the HasProperties instance, the owner of this property; a dictionary containing the attributes for this property; and the new property value. Should return True if the property value is valid, False otherwise.

• equalityFunc – Function for testing equality of two values.

• allowInvalid – If False, a ValueError will be raised on all attempts to set this property to an invalid value. This does not guarantee that the property value will never be invalid - see caveats in the PropertyValue documentation.

• atts – Type specific attributes used to test validity - passed to the PropertyValue.__init__() method as its attributes.

getLabel(instance)

Returns the property label for the given instance (more specifically, for the class of the given instance), or None if no such label has been defined.

enable(instance)

Enables this property for the given HasProperties instance.

See the disable() method for more details.

disable(instance)

Disables this property for the given HasProperties instance.

An attempt to set the value of a disabled property will result in a DisabledError. This behaviour can be circumvented by dealing directly with the underlying PropertyValue object.

Changes to the enabled state of a property may be detected by registering an attribute listener (see PropertyValue.addAttributeListener()) and listening for changes to the enabled attribute.

isEnabled(instance)

Returns True if this property is enabled for the given HasProperties instance, False otherwise.

See the disable() method for more details.

addListener(instance, *args, **kwargs)

Register a listener with the PropertyValue object managed by this property. See PropertyValue.addListener().

Parameters:

instance – The HasProperties instance on which the listener is to be registered.

removeListener(instance, name)

De-register the named listener from the PropertyValue object managed by this property.

getConstraint(instance, constraint)

See getAttribute().

setConstraint(instance, constraint, value)

See setAttribute().

getAttribute(instance, att, *arg)

Returns the value of the named attribute for the specified HasProperties instance, or the default attribute value if instance is None. See PropertiesValue.getAttribute().

setAttribute(instance, att, value)

Sets the value of the named attribute for the specified HasProperties instance,or the default value if instance is None. See PropertiesValue.setAttribute().

getPropVal(instance)

Return the PropertyValue instance(s) for this property, associated with the given HasProperties instance, or None if there is no value for the given instance.

validate(instance, attributes, value)

Called when an attempt is made to set the property value on the given instance.

Called by PropertyValue objects when their value changes. The sole purpose of this method is to determine whether a given value is valid or invalid; it should not do anything else. In particular, it should not modify any other property values on the instance, as bad things will probably happen.

If the given value is invalid, subclass implementations should raise a ValueError containing a useful message as to why the value is invalid. Otherwise, they should not return any value. The default implementation does nothing, unless a custom validate function, and/or required=True, was passed to the constructor. If required is True, and the value is None, a ValueError is raised. If a custom validate function was set, it is called and, if it returns False, a ValueError is raised. It may also raise a ValueError of its own for invalid values.

Subclasses which override this method should therefore call this superclass implementation in addition to performing their own validation.

Parameters:

• instance – The HasProperties instance which owns this PropertyBase instance, or None for an unbound property value.

• attributes (dict) – Attributes of the PropertyValue object, which are used to store type-specific attributes for PropertyBase subclasses.

• value – The value to be validated.

cast(instance, attributes, value)

This method is called when a value is assigned to this PropertyBase instance through a HasProperties attribute access. The default implementaton just returns the given value. Subclasses may override this method to perform any required implicit casting or conversion rules.

revalidate(instance)

Forces validation of this property value, for the current instance. This will result in any registered listeners being notified, but only if the validity of the value has changed.

class fsleyes_props.properties.ListPropertyBase(listType, **kwargs)

Bases: PropertyBase

A PropertyBase for properties which encapsulate more than one value.

Define a ListPropertyBase property.

Parameters:

listType – An unbound PropertyBase instance, defining the type of value allowed in the list. This is optional; if not provided, values of any type will be allowed in the list, but no validation or casting will be performed.

getListType()

Returns a reference to the PropertyBase instance which defines the value types allowsed in this ListPropertyBase. This may be None.

enableItem(instance, index)

Enables the item at the given index. See disableItem().

disableItem(instance, index)

Disables the item at the given index. See PropertyBase.disable().

Note

ListPropertyBase items cannot actually be disabled at this point in time - all this method does is set the 'enabled' attribute of the item to False.

getPropValList(instance)

Returns the list of PropertyValue objects which represent the items stored in this list.

Note that this is a list of PropertyValue instances; it is not the PropertyValueList instance. The latter can be accessed through the owning HasProperties instance with a simple attribute access.

class fsleyes_props.properties.PropertyOwner(name, bases, attrs)

Bases: type

Deprecated.

class fsleyes_props.properties.HasProperties(*args, **kwargs)

Bases: object

Base class for classes which contain PropertyBase instances. All classes which contain PropertyBase objects must subclass this class.

Note

HasProperties is also available via an alias called HasProps.

Create a HasProperties instance.

If no arguments need to be passed in, HasProperties.__init__ does not need to be called.

Parameters:

• validateOnChange – Defaults to False. If set to True, whenever any property value is changed, the value of every property is re-validated. This functionality is accomplished by using the preNotify listener on all PropertyValue instances - see the PropertyValue.setPreNotifyFunction() method.

• kwargs – All other arguments are assumed to be name=value pairs, containing initial values for the properties defined on this HasProperties instance.

Note

The validateOnChange argument warrants some explanation.

The point of validating all other properties when one property changes is to handle the scenario where the validity of one property is dependent upon the values of other properties.

Currently, the only option is to enable this globally; i.e. whenever the value of any property changes, all other properties are validated.

At some stage, I may allow more fine grained control; e.g. validation could only occur when specific properties change, and/or only specific properties are validated. This should be fairly straightforward - we could just maintain a dict of {propName : [propNames ..]} mappings, where the key is the name of a property that should trigger validation, and the value is a list of properties that need to be validated when that property changes.

bindProps(*args, **kwargs)

See bindable.bindProps().

unbindProps(*args, **kwargs)

See bindable.unbindProps().

bind(*args, **kwargs)

Alias for bindProps().

unbind(*args, **kwargs)

Alias for unbindProps().

isBound(*args, **kwargs)

See bindable.isBound().

addProperty(propName, propObj)

Add the given PropertyBase` instance as an attribute of this HasProperties instance.

classmethod getAllProperties()

Returns two lists, the first containing the names of all properties of this object, and the second containing the corresponding PropertyBase objects.

Properties which have a name beginning with an underscore are not returned by this method

classmethod getProp(propName)

Return the PropertyBase object for the given property.

getPropVal(propName)

Return the PropertyValue object(s) for the given property.

getLastValue(propName)

Returns the most recent value of the specified property before its current one.

See the PropertyValue.getLast() method.

serialise(propName)

Returns a string containing the value of the named property, serialsied via the serialise module.

deserialise(propName, value)

Deserialises the given value (assumed to have been serialised via the serialise module), and sets the named property to the deserialised value.

enableNotification(propName, *args, **kwargs)

Enables notification of listeners on the given property.

See the PropertyValue.enableNotification() method.

disableNotification(propName, *args, **kwargs)

Disables notification of listeners on the given property.

See the PropertyValue.disableNotification() method.

getNotificationState(propName)

Returns the notification state of the given property.

See the PropertyValue.getNotificationState() method.

setNotificationState(propName, value)

Sets the notification state of the given property.

See the PropertyValue.setNotificationState() method.

enableAllNotification()

Enables notification of listeners on all properties.

disableAllNotification()

Disables notification of listeners on all properties.

enableProperty(propName, index=None)

Enables the given property.

If an index is provided, it is assumed that the property is a list property (a ListPropertyBase).

See PropertyBase.enable() and ListPropertyBase.enableItem().

disableProperty(propName, index=None)

Disables the given property - see PropertyBase.disable().

If an index is provided, it is assumed that the property is a list property (a ListPropertyBase).

See PropertyBase.disable() and ListPropertyBase.disableItem().

propertyIsEnabled(propName)

Returns the enabled state of the given property - see PropertyBase.isEnabled().

propNotify(propName)

Force notification of listeners on the given property. This will have no effect if notification for the property is disabled.

See the PropertyValue.propNotify() method.

getConstraint(propName, constraint)

See getAttribute().

setConstraint(propName, constraint, value)

See setAttribute().

getAttribute(propName, *args)

Convenience method, returns the value of the named attributes for the named property. See PropertyBase.getAttribute().

setAttribute(propName, *args)

Convenience method, sets the value of the named attribute for the named property. See PropertyBase.setAttribute().

setatt(*args, **kwargs)

Alias for setAttribute().

getatt(*args, **kwargs)

Alias for getAttribute().

listen(*args, **kwargs)

Alias for addListener().

ilisten(*args, **kwargs)

Calls addListener(immediate=True).

wlisten(*args, **kwargs)

Calls addListener(weak=False).

remove(*args, **kwargs)

Alias for removeListener().

addListener(propName, *args, **kwargs)

Convenience method, adds the specified listener to the specified property. See PropertyValue.addListener().

removeListener(propName, listenerName)

Convenience method, removes the specified listener from the specified property. See PropertyValue.removeListener().

enableListener(propName, name)

(Re-)Enables the listener on the specified property with the specified name.

disableListener(propName, name)

Disables the listener on the specified property with the specified name, but does not remove it from the list of listeners.

getListenerState(propName, name)

See PropertyValue.getListenerState().

setListenerState(propName, name, state)

See PropertyValue.setListenerState().

hasListener(propName, name)

Returns True if a listener is registered on the given property, False otherwise.

addGlobalListener(*args, **kwargs)

Registers the given listener so that it will be notified of changes to any of the properties of this HasProperties instance.

removeGlobalListener(listenerName)

De-registers the specified global listener (see addGlobalListener()).

isValid(propName)

Returns True if the current value of the specified property is valid, False otherwise.

validateAll()

Validates all of the properties of this HasProperties object. A list of tuples is returned, with each tuple containing a property name, and an associated error string. The error string is a message about the property which failed validation. If all property values are valid, the returned list will be empty.

fsleyes_props.properties.HasProps

HasProps is simply an alias for HasProperties.

fsleyes_props.properties.Props

Props is simply an alias for HasProperties.