fsleyes_props.properties_value

Definitions of the PropertyValue and PropertyValueList classes.

PropertyValue	An object which encapsulates a value of some sort.
PropertyValueList	A PropertyValueList is a PropertyValue instance which stores other PropertyValue instance in a list.

PropertyValue and PropertyValueList instances are intended to be created and managed by PropertyBase and ListPropertyBase instances respectively, and are used to encapsulate attribute values of HasProperties instances.

These class definitions are really a part of the properties module - they are separated to keep file sizes down. However, the PropertyValue class definitions have no dependence upon the PropertyBase or HasProperties definitions.

class fsleyes_props.properties_value.Listener(propVal, name, function, enabled, immediate)

Bases: object

The Listener class is used by PropertyValue instances to manage their listeners - see PropertyValue.addListener().

Create a Listener.

Parameters:

• propVal – The PropertyValue that owns this Listener.

• name – The listener name.

• function – The callback function.

• enabled – Whether the listener is enabled/disabled.

• immediate – Whether the listener is to be called immediately, or via the PropertyValue.queue.

makeQueueName()

Returns a more descriptive name for this Listener, which is used as its name when passed to the CallQueue.

property expectsArguments

Returns True if the listener function needs to be passed arguments, False otherwise. Property listener functions can be defined to accept either zero arguments, or a set of positional arguments - see PropertyValue.addListener() and PropertyValue.addAttributeListener() for more details.

class fsleyes_props.properties_value.PropertyValue(context, name=None, value=None, castFunc=None, validateFunc=None, equalityFunc=None, preNotifyFunc=None, postNotifyFunc=None, allowInvalid=True, parent=None, **attributes)

Bases: object

An object which encapsulates a value of some sort.

The value may be subjected to casting and validation rules, and listeners may be registered for notification of value and validity changes.

Notification of value and attribute listeners is performed by the bindable module - see the bindable.syncAndNotify() and bindable.syncAndNotifyAtts() functions.

Create a PropertyValue object.

Parameters:

• context – An object which is passed as the first argument to the validateFunc, preNotifyFunc, postNotifyFunc, and any registered listeners. Can technically be anything, but will nearly always be a HasProperties instance.

• name – Value name - if not provided, a default, unique name is created.

• value – Initial value.

• castFunc – Function which performs type casting or data conversion. Must accept three parameters - the context, a dictionary containing the attributes of this object, and the value to cast. Must return that value, cast/converted appropriately.

• validateFunc – Function which accepts three parameters - the context, a dictionary containing the attributes of this object, and a value. This function should test the provided value, and raise a ValueError if it is invalid.

• equalityFunc – Function which accepts two values, and should return True if they are equal, False otherwise. If not provided, the python equailty operator (i.e. ==) is used.

• preNotifyFunc – Function to be called whenever the property value changes, but before any registered listeners are called. See the addListener() method for details of the parameters this function must accept.

• postNotifyFunc – Function to be called whenever the property value changes, but after any registered listeners are called. Must accept the same parameters as the preNotifyFunc.

• allowInvalid – If False, any attempt to set the value to something invalid will result in a ValueError. Note that this does not guarantee that the property will never have an invalid value, as the definition of ‘valid’ depends on external factors (i.e. the validateFunc). Therefore, the validity of a value may change, even if the value itself has not changed.

• parent – If this PV instance is a member of a PropertyValueList instance, the latter sets itself as the parent of this PV. Whenever the value of this PV changes, the PropertyValueList._listPVChanged() method is called.

• attributes – Any key-value pairs which are to be associated with this PropertyValue object, and passed to the castFunc and validateFunc functions. Attributes are not used by the PropertyValue or PropertyValueList classes, however they are used by the PropertyBase and ListPropertyBase classes to store per-instance property attributes. Listeners may register to be notified when attribute values change.

queue = <fsleyes_props.callqueue.CallQueue object>

A CallQueue instance which is shared by all PropertyValue instances, and used for notifying listeners of value and attribute changes.

A queue is used for notification so that listeners are notified in the order that values were changed.

getParent()

If this PropertyValue is an item in a PropertyValueList, this method returns a reference to the owning PropertyValueList. Otherwise, this method returns None.

allowInvalid(allow=None)

Query/set the allow invalid state of this value.

If no arguments are passed, returns the current allow invalid state. Otherwise, sets the current allow invalid state. to the given argument.

enableNotification(bound=False, att=False)

Enables notification of property value and attribute listeners for this PropertyValue object.

Parameters:

• bound – If True, notification is enabled on all other PropertyValue instances that are bound to this one (see the bindable module). If False (the default), notification is only enabled on this PropertyValue.

• att – If True, notification is enabled on all attribute listeners as well as property value listeners.

disableNotification(bound=False, att=False)

Disables notification of property value and attribute listeners for this PropertyValue object. Notification can be re-enabled via the enableNotification() or setNotificationState() methods.

Parameters:

• bound – If True, notification is disabled on all other PropertyValue instances that are bound to this one (see the bindable module). If False (the default), notification is only disabled on this PropertyValue.

• att – If True, notification is disabled on all attribute listeners as well as property value listeners.

getNotificationState()

Returns True if notification is currently enabled, False otherwise.

setNotificationState(value)

Sets the current notification state.

addAttributeListener(name, listener, weak=True, immediate=False)

Adds an attribute listener for this PropertyValue. The listener callback function must accept either no arguments, or the following arguments:

• context: The context associated with this PropertyValue.

• attribute: The name of the attribute that changed.

• value: The new attribute value.

• name: The name of this PropertyValue instance.

Parameters:

• name – A unique name for the listener. If a listener with the specified name already exists, it will be overwritten.

• listener – The callback function.

• weak – If True (the default), a weak reference to the callback function is used.

• immediate – If False (the default), the listener is called immediately; otherwise, it is called via the queue.

disableAttributeListener(name)

Disables the attribute listener with the specified name.

enableAttributeListener(name)

Enables the attribute listener with the specified name.

removeAttributeListener(name)

Removes the attribute listener of the given name.

getAttributes()

Returns a dictionary containing all the attributes of this PropertyValue object.

setAttributes(atts)

Sets all the attributes of this PropertyValue object. from the given dictionary.

getAttribute(name, *arg)

Returns the value of the named attribute.

Parameters:

default – If provided, the default value to use if name is not an attribute. If not provided, and name is not an attribute, a KeyError is raised.

setAttribute(name, value)

Sets the named attribute to the given value, and notifies any registered attribute listeners of the change.

prepareListeners(att, name=None, value=None)

Prepares a list of Listener instances ready to be called, and a list of arguments to pass to them.

Parameters:

• att – If True, attribute listeners are returned, otherwise value listeners are returned.

• name – If att == True, the attribute name.

• value – If att == True, the attribute value.

notifyAttributeListeners(name, value)

Notifies all registered attribute listeners of an attribute changed - see the bindable.syncAndNotifyAtts() function.

addListener(name, callback, overwrite=False, weak=True, immediate=False)

Adds a listener for this value.

When the value changes, the listener callback function is called. The callback function may either be defined to accept no arguments, or to accept the following arguments:

• value: The property value

• valid: Whether the value is valid or invalid

• context: The context object passed to __init__().

• name: The name of this PropertyValue instance.

Listener names prenotify and postnotify are reserved - if either of these are passed in for the listener name, a :exc`ValueError` is raised.

Parameters:

• name (str) – A unique name for this listener. If a listener with the name already exists, a :exc`RuntimeError` will be raised, or it will be overwritten, depending upon the value of the overwrite argument.

• callback – The callback function.

• overwrite – If True any previous listener with the same name will be overwritten.

• weak – If True (the default), a weak reference to the callback function is retained, meaning that it can be garbage-collected. If passing in a lambda or inner function, you will probably want to set weak to False, in which case a strong reference will be used.

• immediate – If False (the default), this listener will be notified through the CallQueue - listeners for all PropertyValue instances are queued, and notified in turn. If True, If True, the CallQueue will not be used, and this listener will be notified as soon as this PropertyValue changes.

removeListener(name)

Removes the listener with the given name from this PropertyValue.

enableListener(name)

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

disableListener(name)

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

getListenerState(name)

Returns True if the specified listener is currently enabled, False otherwise.

An AttributeError is raised if a listener with the specified name does not exist.

setListenerState(name, state)

Enables/disables the specified listener.

hasListener(name)

Returns True if a listener with the given name is registered, False otherwise.

setPreNotifyFunction(preNotifyFunc)

Sets the function to be called on value changes, before any registered listeners.

setPostNotifyFunction(postNotifyFunc)

Sets the function to be called on value changes, after any registered listeners.

getLast()

Returns the most recent property value before the current one.

get()

Returns the current property value.

set(newValue)

Sets the property value.

The property is validated and, if the property value or its validity has changed, any registered listeners are called through the propNotify() method. If allowInvalid was set to False, and the new value is not valid, a ValueError is raised, and listeners are not notified.

propNotify()

Notifies registered listeners - see the bindable.syncAndNotify() function.

revalidate()

Revalidates the current property value, and re-notifies any registered listeners if the value validity has changed.

isValid()

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

class fsleyes_props.properties_value.PropertyValueList(context, name=None, values=None, itemCastFunc=None, itemEqualityFunc=None, itemValidateFunc=None, listValidateFunc=None, itemAllowInvalid=True, preNotifyFunc=None, postNotifyFunc=None, listAttributes=None, itemAttributes=None)

Bases: PropertyValue

A PropertyValueList is a PropertyValue instance which stores other PropertyValue instance in a list. Instances of this class are generally managed by a ListPropertyBase instance.

When created, separate validation functions may be passed in for individual items, and for the list as a whole. Listeners may be registered on individual PropertyValue instances (accessible via the getPropertyValueList() method), or on the entire list.

The values contained in this PropertyValueList may be accessed through standard Python list operations, including slice-based access and assignment, append(), insert(), extend(), pop(), index(), count(), move(), insertAll(), removeAll(), and reorder() (these last few are non-standard).

Because the values contained in this list are PropertyValue instances themselves, some limitations are present on list modifying operations:

class MyObj(props.HasProperties):
  mylist = props.List(default[1, 2, 3])

myobj = MyObj()

Simple list-slicing modifications work as expected:

# the value after this will be [5, 2, 3]
myobj.mylist[0]  = 5

# the value after this will be [5, 6, 7]
myobj.mylist[1:] = [6, 7]

However, modifications which would change the length of the list are not supported:

# This will result in an IndexError
myobj.mylist[0:2] = [6, 7, 8]

The exception to this rule concerns modifications which would replace every value in the list:

# These assignments are equivalent
myobj.mylist[:] = [1, 2, 3, 4, 5]
myobj.mylist    = [1, 2, 3, 4, 5]

While the simple list modifications described above will change the value(s) of the existing PropertyValue instances in the list, modifications which replace the entire list contents will result in existing PropertyValue instances being destroyed, and new ones being created. This is a very important point to remember if you have registered listeners on individual PropertyValue items.

A listener registered on a PropertyValueList will be notified whenever the list is modified (e.g. additions, removals, reorderings), and whenever any individual value in the list changes. Alternately, listeners may be registered on the individual PropertyValue instances (which are accessible through the getPropertyValueList() method) to be nofitied of changes to those values only.

There are some interesting type-specific subclasses of the PropertyValueList, which provide additional functionality:

• The PointValueList, for Point properties.

• The BoundsValueList, for Bounds properties.

Create a PropertyValueList.

Parameters:

• context – See PropertyValue.__init__().

• name – See PropertyValue.__init__().

• values – Initial list values.

• itemCastFunc – Function which casts a single list item.

• itemEqualityFunc – Function which tests equality of two values.

• itemValidateFunc – Function which validates a single list item.

• listValidateFunc – Function which validates the list as a whole.

• itemAllowInvalid – Whether items are allowed to containg invalid values.

• preNotifyFunc – See PropertyValue.__init__().

• postNotifyFunc – See PropertyValue.__init__().

• listAttributes – Attributes to be associated with this PropertyValueList.

• itemAttributes – Attributes to be associated with new PropertyValue items added to the list.

getPropertyValueList()

Return (a copy of) the underlying property value list, allowing access to the PropertyValue instances which manage each list item.

get()

Overrides PropertyValue.get(). Returns this PropertyValueList object.

set(newValues)

Overrides PropertyValue.set().

Sets the values stored in this PropertyValueList. If the length of the newValues argument does not match the current list length, an IndexError is raised.

getLast()

Overrides PropertyValue.getLast(). Returns the most recent list values.

index(item)

count(item)

insert(index, item)

Inserts the given item before the given index.

insertAll(index, items)

Inserts all of the given items before the given index.

append(item)

Appends the given item to the end of the list.

extend(iterable)

Appends all items in the given iterable to the end of the list.

pop(index=-1)

Remove and return the specified value in the list (default: last).

move(from_, to)

Move the item from from_ to to.

remove(value)

Remove the first item in the list with the specified value.

removeAll(values)

Removes the first occurrence in the list of all of the specified values.

reorder(idxs)

Reorders the list according to the given sequence of indices.

fsleyes_props.properties_value.safeCall(func, *args, **kwargs)

This function is may be used to “safely” run a function which may trigger PropertyValue notifications. Any notifications are queued and executed in the correct order.