properties_types.py

#!/usr/bin/env python
#
# properties_types.py - Definitions for different property types.
#
# Author: Paul McCarthy <pauldmccarthy@gmail.com>
#
"""Definitions for different property types.

This module provides a number of :class:`.PropertyBase` subclasses which
define properties of different types. These classes are intended to be
added as attributes of a :class:`.HasProperties` class definition.

 .. autosummary::
    :nosignatures:

    Object
    Boolean
    Number
    Int
    Real
    Percentage
    String
    Choice
    FilePath
    List
    Colour
    ColourMap
    Bounds
    Point
    Array
"""


import os.path as op

import collections

import six

import numpy as np

from . import properties        as props
from . import properties_value  as propvals


class Object(props.PropertyBase):
    """A property which encapsulates any value. """

    def __init__(self, **kwargs):
        """Create a ``Object`` property. If an ``equalityFunc`` is not
        provided, any writes to this property will be treated as if the value
        has changed (and any listeners will be notified).
        """

        def defaultEquals(this, other):
            return False

        kwargs['equalityFunc'] = kwargs.get('equalityFunc', defaultEquals)
        props.PropertyBase.__init__(self, **kwargs)


class Boolean(props.PropertyBase):
    """A property which encapsulates a ``bool`` value."""

    def __init__(self, **kwargs):
        """Create a ``Boolean`` property.

        If the ``default`` ``kwarg`` is not provided, a default value of
        ``False`` is used.
        """

        kwargs['default'] = kwargs.get('default', False)
        props.PropertyBase.__init__(self, **kwargs)


    def cast(self, instance, attributes, value):
        """Overrides :meth:`.PropertyBase.cast`. Casts the given value to a
        ``bool``.
        """
        return bool(value)


class Number(props.PropertyBase):
    """Base class for the :class:`Int` and :class:`Real` classes.

    A property which represents a number.  Don't use/subclass this,
    use/subclass one of ``Int`` or ``Real``.
    """

    def __init__(self,
                 minval=None,
                 maxval=None,
                 clamped=False,
                 **kwargs):
        """Define a :class:`Number` property.

        :param minval:  Minimum valid value

        :param maxval:  Maximum valid value

        :param clamped: If ``True``, the value will be clamped to its
                        min/max bounds.

        :param kwargs:  Passed through to :meth:`.PropertyBase.__init__`.
                        If a ``default`` value is not provided, it is set
                        to something sensible.
        """

        default = kwargs.get('default', None)

        if default is None:
            if minval is not None and maxval is not None:
                default = (minval + maxval) / 2
            elif minval is not None:
                default = minval
            elif maxval is not None:
                default = maxval
            else:
                default = 0

        kwargs['default']    = default
        kwargs['minval']     = minval
        kwargs['maxval']     = maxval
        kwargs['clamped']    = clamped
        props.PropertyBase.__init__(self, **kwargs)


    def validate(self, instance, attributes, value):
        """Overrides :meth:`.PropertyBase.validate`. Validates the given
        number.

        Calls the :meth:`.PropertyBase.validate` method.
        Then, if the ``minval`` and/or ``maxval`` attributes have been set,
        and the given value is not within those values, a :exc:`ValueError` is
        raised.

        :param instance:   The owning :class:`.HasProperties` instance (or
                           ``None`` for unbound property values).

        :param attributes: Dictionary containing property constraints.

        :param value:      The value to validate.
        """

        props.PropertyBase.validate(self, instance, attributes, value)

        minval = attributes['minval']
        maxval = attributes['maxval']

        if minval is not None and value < minval:
            raise ValueError('Must be at least {}'.format(minval))

        if maxval is not None and value > maxval:
            raise ValueError('Must be at most {}'.format(maxval))


    def cast(self, instance, attributes, value):
        """Overrides :meth:`.PropertyBase.cast`.

        If the ``clamped`` constraint is ``True`` and the ``minval`` and/or
        ``maxval`` have been set, this function ensures that the given value
        lies within the ``minval`` and ``maxval`` limits. Otherwise the value
        is returned unchanged.
        """

        clamped = attributes['clamped']

        if not clamped: return value

        minval = attributes['minval']
        maxval = attributes['maxval']

        if minval is not None and value < minval: return minval
        if maxval is not None and value > maxval: return maxval

        return value


class Int(Number):
    """A :class:`Number` which encapsulates an integer."""

    def __init__(self, **kwargs):
        """Create an ``Int`` property. """
        Number.__init__(self, **kwargs)


    def cast(self, instance, attributes, value):
        """Overrides :meth:`Number.cast`. Casts the given value to an ``int``,
        and then passes the value to :meth:`Number.cast`.
        """
        return Number.cast(self, instance, attributes, int(value))


class Real(Number):
    """A :class:`.Number` which encapsulates a floating point number."""


    def __equals(self, a, b):
        """Custom equality function passed to :class`.PropertyBase.__init__`.

        Tests for equality according to the ``precision`` passed to
        :meth:`__init__`.
        """

        if any((a is None, b is None, self.__precision is None)):
            return a == b

        return abs(a - b) < self.__precision


    def __init__(self, precision=0.000000001, **kwargs):
        """Define a ``Real`` property.

        :param precision: Tolerance for equality testing. Set to ``None`` to
                          use exact equality.
        """
        self.__precision = precision

        Number.__init__(self, equalityFunc=self.__equals, **kwargs)


    def cast(self, instance, attributes, value):
        """Overrides :meth:`Number.cast`. Casts the given value to a ``float``,
        and then passes the value to :meth:`Number.cast`.
        """
        return Number.cast(self, instance, attributes, float(value))


class Percentage(Real):
    """A :class:`Real` property which represents a percentage.

    A ``Percentage`` property is just a ``Real`` property with
    a default minimum value of ``0`` and default maximum value of ``100``.
    """

    def __init__(self, **kwargs):
        """Create a ``Percentage`` property."""
        kwargs['minval']  = kwargs.get('minval',    0.0)
        kwargs['maxval']  = kwargs.get('maxval',  100.0)
        kwargs['default'] = kwargs.get('default',  50.0)
        Real.__init__(self, **kwargs)


class String(props.PropertyBase):
    """A property which encapsulates a string."""

    def __init__(self, minlen=None, maxlen=None, **kwargs):
        """Cteate a ``String`` property.

        :param int minlen: Minimum valid string length.
        :param int maxlen: Maximum valid string length.
        """

        kwargs['default'] = kwargs.get('default', None)
        kwargs['minlen']  = minlen
        kwargs['maxlen']  = maxlen
        props.PropertyBase.__init__(self, **kwargs)


    def cast(self, instance, attributes, value):
        """Overrides :meth:`.PropertyBase.cast`.

        Casts the given value to a string. If the given value is the empty
        string, it is replaced with ``None``.
        """

        if value == '': return None
        else:           return value


    def validate(self, instance, attributes, value):
        """Overrides :meth:`.PropertyBase.validate`.

        Passes the given value to
        :meth:`.PropertyBase.validate`. Then, if either the
        ``minlen`` or ``maxlen`` constraints have been set, and the given
        value has length less than ``minlen`` or greater than ``maxlen``,
        raises a :exc:`ValueError`.
        """

        if value == '': value = None

        props.PropertyBase.validate(self, instance, attributes, value)

        if value is None: return

        if not isinstance(value, six.string_types):
            raise ValueError('Must be a string')

        minlen = attributes['minlen']
        maxlen = attributes['maxlen']

        if minlen is not None and len(value) < minlen:
            raise ValueError('Must have length at least {}'.format(minlen))

        if maxlen is not None and len(value) > maxlen:
            raise ValueError('Must have length at most {}'.format(maxlen))


class Choice(props.PropertyBase):
    """A property which may only be set to one of a set of predefined values.

    Choices can be added/removed via the :meth:`addChoice`,
    :meth:`removeChoice` method, and :meth:`setChoices` methods. Existing
    choices can be modified with the :meth:`updateChoice` method.

    Individual choices can be enabled/disabled via the :meth:`enableChoice`
    and :meth:`disableChoice` methods. The ``choiceEnabled`` attribute
    contains a dictionary of ``{choice : boolean}`` mappings
    representing the enabled/disabled state of each choice.

    A set of alternate values can be provided for each choice - these
    alternates will be accepted when assigning to a ``Choice`` property.

    .. note:: If you create a ``Choice`` property with non-string choice and
              alternate values, you may run into problems when using
              :mod:`.serialise` and/or :mod:`.cli` functionality, unless you
              set ``allowStr`` to ``True``.
    """

    def __init__(self,
                 choices=None,
                 alternates=None,
                 allowStr=False,
                 **kwargs):
        """Create a ``Choice`` property.

        :arg choices:    List of values, the possible values that this property
                         can take. Can alternately be a ``dict`` - see the note
                         above.

        :arg alternates: A list of lists, specificying alternate acceptable
                         values for each choice. Can also be a dict of
                         ``{choice : [alternates]}`` mappings. All alternate
                         values must be unique - different choices cannot have
                         equivalent alternate values.

        :arg allowStr:   If ``True``, string versions of any non-string choice
                         values will be accepted - ``str`` versions of each
                         choice are added as alternate values for that choice.
                         Defaults to ``False``.
        """

        if choices is None:
            choices    = []
            alternates = {}

        # Alternates are stored twice:
        #
        #   - As a dict of { choice    : [alternate] } mappings
        #   - As a dict of { alternate : choice      } mappings
        #
        # We generate the first dict here
        if alternates is None:
            alternates = {c : [] for c in choices}

        elif isinstance(alternates, dict):
            alternates = dict(alternates)

        elif isinstance(alternates, (list, tuple)):
            alternates = {c : list(a) for (c, a) in zip(choices, alternates)}

        # Add stringified versions of all
        # choices if allowStr is True
        if allowStr:
            for c in choices:
                strc = str(c)
                alts = alternates[c]
                if strc not in alts:
                    alts.append(strc)

        # Generate the second alternates dict
        altLists   = alternates
        alternates = self.__generateAlternatesDict(altLists)

        # Enabled flags are stored as a dict
        # of {choice : bool} mappings
        enabled = {choice: True for choice in choices}

        if len(choices) > 0: default = choices[0]
        else:                default = None

        if len(choices) != len(altLists):
            raise ValueError('Alternates are required for every choice')

        kwargs['choices']       = list(choices)
        kwargs['alternates']    = dict(alternates)
        kwargs['altLists']      = dict(altLists)
        kwargs['choiceEnabled'] = enabled
        kwargs['allowStr']      = allowStr
        kwargs['default']       = kwargs.get('default',      default)
        kwargs['allowInvalid']  = kwargs.get('allowInvalid', False)

        props.PropertyBase.__init__(self, **kwargs)


    def setDefault(self, default, instance=None):
        """Sets the default choice value. """
        if default not in self.getChoices(instance):
            raise ValueError('{} is not a choice'.format(default))

        self.setConstraint(instance, 'default', default)


    def enableChoice(self, choice, instance=None):
        """Enables the given choice. """
        choiceEnabled = dict(self.getConstraint(instance, 'choiceEnabled'))
        choiceEnabled[choice] = True
        self.setConstraint(instance, 'choiceEnabled', choiceEnabled)


    def disableChoice(self, choice, instance=None):
        """Disables the given choice. An attempt to set the property to
        a disabled value will result in a :exc:`ValueError`.
        """
        choiceEnabled = dict(self.getConstraint(instance, 'choiceEnabled'))
        choiceEnabled[choice] = False
        self.setConstraint(instance, 'choiceEnabled', choiceEnabled)


    def choiceEnabled(self, choice, instance=None):
        """Returns ``True`` if the given choice is enabled, ``False``
        otherwise.
        """
        return self.getConstraint(instance, 'choiceEnabled')[choice]


    def getChoices(self, instance=None):
        """Returns a list of the current choices. """
        return list(self.getConstraint(instance, 'choices'))


    def getAlternates(self, instance=None):
        """Returns a list of the current acceptable alternate values for each
        choice.
        """
        choices  = self.getConstraint(instance, 'choices')
        altLists = self.getConstraint(instance, 'altLists')

        return [altLists[c] for c in choices]


    def updateChoice(self,
                     choice,
                     newChoice=None,
                     newAlt=None,
                     instance=None):
        """Updates the choice value and/or alternates for the specified choice.
        """

        choices    = list(self.getConstraint(instance, 'choices'))
        altLists   = dict(self.getConstraint(instance, 'altLists'))
        idx        = choices.index(choice)

        if newChoice is not None:
            choices[ idx]       = newChoice
            altLists[newChoice] = altLists[choice]

            altLists.pop(choice)
        else:
            newChoice = choice

        if newAlt is not None: altLists[newChoice] = list(newAlt)

        self.__updateChoices(choices, altLists, instance)


    def setChoices(self, choices, alternates=None, instance=None):
        """Sets the list of possible choices (and their alternate values, if
        not None).
        """

        if alternates is None:
            alternates = {c : [] for c in choices}
        elif isinstance(alternates, (list, tuple)):
            alternates = {c : a for (c, a) in zip(choices, alternates)}
        elif isinstance(alternates, dict):
            alternates = dict(alternates)

        # Add stringified versions of all
        # choices if allowStr is True
        if self.getConstraint(instance, 'allowStr'):
            for c in choices:
                strc = str(c)
                alts = alternates[c]
                if strc not in alts:
                    alts.append(strc)

        if len(choices) != len(alternates):
            raise ValueError('Alternates are required for every choice')

        self.__updateChoices(choices, alternates, instance)


    def addChoice(self, choice, alternate=None, instance=None):
        """Adds a new choice to the list of possible choices."""

        if alternate is None: alternate = []
        else:                 alternate = list(alternate)

        choices  = list(self.getConstraint(instance, 'choices'))
        altLists = dict(self.getConstraint(instance, 'altLists'))

        if self.getConstraint(instance, 'allowStr'):
            strc = str(choice)
            if strc not in alternate:
                alternate.append(strc)

        choices.append(choice)
        altLists[choice] = list(alternate)

        self.__updateChoices(choices, altLists, instance)


    def removeChoice(self, choice, instance=None):
        """Removes the specified choice from the list of possible choices. """

        choices   = list(self.getConstraint(instance, 'choices'))
        altLists  = dict(self.getConstraint(instance, 'altLists'))

        choices .remove(choice)
        altLists.pop(   choice)

        self.__updateChoices(choices, altLists, instance)


    def __generateAlternatesDict(self, altLists):
        """Given a dictionary containing ``{choice : [alternates]}``
        mappings, creates and returns a dictionary containing
        ``{alternate : choice}`` mappings.

        Raises a ``ValueError`` if there are any duplicate alternate values.
        """

        alternates = {}

        for choice, altList in altLists.items():
            for alt in altList:
                if alt in alternates:
                    raise ValueError('Duplicate alternate value '
                                     '(choice: {}): {}'.format(choice, alt))
                alternates[alt] = choice

        return alternates


    def __updateChoices(self, choices, alternates, instance=None):
        """Used by all of the public choice modifying methods. Updates
        all choices, labels, and altenrates.

        :param choices:    A list of choice values

        :param alternates: A dict of ``{choice :  [alternates]}`` mappings.
        """

        propVal    = self.getPropVal(   instance)
        default    = self.getConstraint(instance, 'default')
        oldEnabled = self.getConstraint(instance, 'choiceEnabled')
        newEnabled = {}

        # Prevent notification while
        # we're updating constraints
        if propVal is not None:
            oldChoice  = propVal.get()
            notifState = propVal.getNotificationState()
            validState = propVal.allowInvalid()
            propVal.disableNotification()
            propVal.allowInvalid(True)

        for choice in choices:
            if choice in oldEnabled: newEnabled[choice] = oldEnabled[choice]
            else:                    newEnabled[choice] = True

        if default not in choices:
            default = choices[0]

        altLists   = alternates
        alternates = self.__generateAlternatesDict(altLists)

        self.setConstraint(instance, 'choiceEnabled', newEnabled)
        self.setConstraint(instance, 'altLists',      altLists)
        self.setConstraint(instance, 'alternates',    alternates)
        self.setConstraint(instance, 'choices',       choices)
        self.setConstraint(instance, 'default',       default)

        if propVal is not None:

            if oldChoice not in choices:
                if   default in choices: propVal.set(default)
                elif len(choices) > 0:   propVal.set(choices[0])
                else:                    propVal.set(None)

            propVal.setNotificationState(notifState)
            propVal.allowInvalid(        validState)

            if notifState:
                propVal.notifyAttributeListeners('choices', choices)

            if propVal.get() != oldChoice:
                propVal.propNotify()


    def validate(self, instance, attributes, value):
        """Overrides :meth:`.PropertyBase.validate`.

        Raises a :exc:`ValueError` if the given value is not one of the
        possible values for this :class:`Choice` property.
        """
        props.PropertyBase.validate(self, instance, attributes, value)

        choices    = self.getConstraint(instance, 'choices')
        enabled    = self.getConstraint(instance, 'choiceEnabled')
        alternates = self.getConstraint(instance, 'alternates')

        if len(choices) == 0: return

        # Check to see if this is an
        # acceptable alternate value
        altValue = alternates.get(value, None)

        if value not in choices and altValue not in choices:
            raise ValueError('Invalid choice ({})'    .format(value))

        if not enabled.get(value, False):
            raise ValueError('Choice is disabled ({})'.format(value))


    def cast(self, instance, attributes, value):
        """Overrides :meth:`.PropertyBase.cast`.

        Checks to see if the given value is a valid alternate value for a
        choice. If so, the alternate value is replaced with the choice value.
        """
        alternates = self.getConstraint(instance, 'alternates')
        return alternates.get(value, value)



class FilePath(String):
    """A property which represents a file or directory path.

    There is currently no support for validating a path which may be either a
    file or a directory - only one or the other.
    """

    def __init__(self, exists=False, isFile=True, suffixes=[], **kwargs):
        """Create a ``FilePath`` property.

        :param bool exists:   If ``True``, the path must exist.

        :param bool isFile:   If ``True``, the path must be a file. If
                              ``False``, the path must be a directory. This
                              check is only performed if ``exists`` is
                              ``True``.

        :param list suffixes: List of acceptable file suffixes (only relevant
                              if ``isFile`` is ``True``).
        """

        kwargs['exists']   = exists
        kwargs['isFile']   = isFile
        kwargs['suffixes'] = suffixes

        String.__init__(self, **kwargs)


    def validate(self, instance, attributes, value):
        """Overrides :meth:`.PropertyBase.validate`.

        If the ``exists`` constraint is not ``True``, does nothing. Otherwise,
        if ``isFile`` is ``False`` and the given value is not a path to an
        existing directory, a :exc:`ValueError` is raised.

        If ``isFile`` is ``True``, and the given value is not a path to an
        existing file (which, if ``suffixes`` is not None, must end in one of
        the specified suffixes), a :exc:`ValueError` is raised.
        """

        String.validate(self, instance, attributes, value)

        exists   = attributes['exists']
        isFile   = attributes['isFile']
        suffixes = attributes['suffixes']

        if value is None: return
        if value == '':   return
        if not exists:    return

        if isFile:

            matchesSuffix = any([value.endswith(s) for s in suffixes])

            # If the file doesn't exist, it's bad
            if not op.isfile(value):
                raise ValueError('Must be a file ({})'.format(value))

            # if the file exists, and matches one of
            # the specified suffixes, then it's good
            if len(suffixes) == 0 or matchesSuffix: return

            # Otherwise it's bad
            else:
                raise ValueError(
                    'Must be a file ending in [{}] ({})'.format(
                        ','.join(suffixes), value))

        elif not op.isdir(value):
            raise ValueError('Must be a directory ({})'.format(value))


class List(props.ListPropertyBase):
    """A property which represents a list of items, of another property type.

    If you use ``List`` properties, you really should read the documentation
    for the :class:`.PropertyValueList`, as it contains important usage
    information.
    """

    def __init__(self, listType=None, minlen=None, maxlen=None, **kwargs):
        """Create a ``List`` property.

        :param listType:   A :class:`.PropertyBase` type, specifying the
                           values allowed in the list. If ``None``, anything
                           can be stored in the list, but no casting or
                           validation will occur.

        :param int minlen: Minimum list length.

        :param int maxlen: Maximum list length.
        """

        if (listType is not None) and \
           (not isinstance(listType, props.PropertyBase)):
            raise ValueError(
                'A list type (a PropertyBase instance) must be specified')

        kwargs['default'] = kwargs.get('default', [])
        kwargs['minlen']  = minlen
        kwargs['maxlen']  = maxlen

        # This needs to be removed when you update widgets_list.py
        self.embed = False

        props.ListPropertyBase.__init__(self, listType,  **kwargs)


    def validate(self, instance, attributes, value):
        """Overrides :meth:`.PropertyBase.validate`.

        Checks that the given value (which should be a list) meets the
        ``minlen``/``maxlen`` constraints. Raises a :exc:`ValueError` if it
        does not.
        """

        props.ListPropertyBase.validate(self, instance, attributes, value)

        minlen = attributes['minlen']
        maxlen = attributes['maxlen']

        if minlen is not None and len(value) < minlen:
            raise ValueError('Must have length at least {}'.format(minlen))
        if maxlen is not None and len(value) > maxlen:
            raise ValueError('Must have length at most {}'.format(maxlen))


class Colour(props.PropertyBase):
    """A property which represents a RGBA colour, stored as four floating
    point values in the range ``0.0 - 1.0``.

    RGB colours are also accepted - if an RGB colour is provided, the
    alpha channel is set to 1.0.
    """


    def __init__(self, **kwargs):
        """Create a ``Colour`` property.

        If the ``default`` ``kwarg`` is not provided, the default is set
        to white.
        """

        default = kwargs.get('default', (1.0, 1.0, 1.0, 1.0))

        if len(default) == 3:
            default = list(default) + [1.0]

        kwargs['default'] = default

        props.PropertyBase.__init__(self, **kwargs)


    def validate(self, instance, attributes, value):
        """Checks the given ``value``, and raises a :exc:`ValueError` if
        it does not consist of three or four floating point numbers in the
        range ``(0.0 - 1.0)``.
        """
        props.PropertyBase.validate(self, instance, attributes, value)

        if (not isinstance(value, collections.Sequence)) or \
           (len(value) not in (3, 4)):
            raise ValueError('Colour must be a sequence of three/four values')

        for v in value:
            if (v < 0.0) or (v > 1.0):
                raise ValueError('Colour values must be between 0.0 and 1.0')


    def cast(self, instance, attributes, value):
        """Ensures that the given ``value`` contains three or four floating
        point numbers, in the range ``(0.0 - 1.0)``.

        If the alpha channel is not provided, it is set to the current alpha
        value (which defaults to ``1.0``).
        """

        pv = self.getPropVal(instance)

        if pv is not None: currentVal = pv.get()
        else:              currentVal = self._defaultConstraints['default']

        value = [float(v) for v in value]

        if len(value) == 3:
            value = value + [currentVal[3]]

        value = value[:4]

        for i, v in enumerate(value):
            if v < 0.0: value[i] = 0.0
            if v > 1.0: value[i] = 1.0

        return value


class ColourMap(props.PropertyBase):
    """A property which encapsulates a :class:`matplotlib.colors.Colormap`.

    A ``ColourMap`` property can take any ``Colormap`` instance as its
    value. ColourMap values may be specified either as a
    ``Colormap`` instance, or as a string containing
    the name of a registered colour map instance.

    ``ColourMap`` properties also maintain an internal list of colour
    map names; while these names do not restrict the value that a ``ColourMap``
    property can take, they are used for display purposes - a widget which is
    created for a ``ColourMap`` instance will only display the options returned
    by the :meth:`getColourMaps` method. See the :func:`widgets._ColourMap`
    function.
    """

    def __init__(self, cmaps=None, **kwargs):
        """Define a ``ColourMap`` property. """

        default = kwargs.get('default', None)

        if cmaps is None:
            cmaps = []

        if default is None and len(cmaps) > 0:
            default = cmaps[0]

        kwargs['default'] = default
        kwargs['cmaps']   = list(cmaps)

        props.PropertyBase.__init__(self, **kwargs)


    def setColourMaps(self, cmaps, instance=None):
        """Set the colour maps for this property.

        :arg cmaps: a list of registered colour map names.
        """

        default = self.getConstraint(instance, 'default')

        if default not in cmaps:
            default = cmaps[0]

        self.setConstraint(instance, 'cmaps'  , cmaps)
        self.setConstraint(instance, 'default', default)


    def addColourMap(self, cmap, instance=None):
        """Add a colour map to the list.

        :arg cmap: The name of a registered colour map.
        """

        cmaps = self.getColourMaps(instance)

        if cmap not in cmaps:
            cmaps.append(cmap)
            self.setColourMaps(cmaps, instance)