traitlets.py
1761 lines
| 58.3 KiB
| text/x-python
|
PythonLexer
|
r2157 | # encoding: utf-8 | ||
""" | ||||
A lightweight Traits like module. | ||||
|
r2175 | This is designed to provide a lightweight, simple, pure Python version of | ||
many of the capabilities of enthought.traits. This includes: | ||||
* Validation | ||||
* Type specification with defaults | ||||
* Static and dynamic notification | ||||
* Basic predefined types | ||||
* An API that is similar to enthought.traits | ||||
We don't support: | ||||
* Delegation | ||||
* Automatic GUI generation | ||||
|
r2179 | * A full set of trait types. Most importantly, we don't provide container | ||
|
r2385 | traits (list, dict, tuple) that can trigger notifications if their | ||
|
r2179 | contents change. | ||
|
r2175 | * API compatibility with enthought.traits | ||
|
r2179 | There are also some important difference in our design: | ||
* enthought.traits does not validate default values. We do. | ||||
|
r2175 | We choose to create this module because we need these capabilities, but | ||
we need them to be pure Python so they work in all Python implementations, | ||||
including Jython and IronPython. | ||||
|
r8795 | Inheritance diagram: | ||
.. inheritance-diagram:: IPython.utils.traitlets | ||||
:parts: 3 | ||||
|
r2157 | """ | ||
|
r16216 | # Copyright (c) IPython Development Team. | ||
# Distributed under the terms of the Modified BSD License. | ||||
|
r2157 | # | ||
|
r16216 | # Adapted from enthought.traits, Copyright (c) Enthought, Inc., | ||
# also under the terms of the Modified BSD License. | ||||
|
r2157 | |||
|
r15008 | import contextlib | ||
|
r2157 | import inspect | ||
|
r4047 | import re | ||
|
r2177 | import sys | ||
|
r2157 | import types | ||
|
r4732 | from types import FunctionType | ||
try: | ||||
from types import ClassType, InstanceType | ||||
ClassTypes = (ClassType, type) | ||||
except: | ||||
ClassTypes = (type,) | ||||
|
r4872 | |||
|
r3108 | from .importstring import import_item | ||
|
r4732 | from IPython.utils import py3compat | ||
|
r17560 | from IPython.utils import eventful | ||
|
r18124 | from IPython.utils.py3compat import iteritems, string_types | ||
|
r15011 | from IPython.testing.skipdoctest import skip_doctest | ||
|
r2229 | |||
|
r4732 | SequenceTypes = (list, tuple, set, frozenset) | ||
|
r2204 | |||
|
r2157 | #----------------------------------------------------------------------------- | ||
# Basic classes | ||||
#----------------------------------------------------------------------------- | ||||
class NoDefaultSpecified ( object ): pass | ||||
NoDefaultSpecified = NoDefaultSpecified() | ||||
class Undefined ( object ): pass | ||||
Undefined = Undefined() | ||||
|
r2384 | class TraitError(Exception): | ||
pass | ||||
|
r2157 | |||
#----------------------------------------------------------------------------- | ||||
# Utilities | ||||
#----------------------------------------------------------------------------- | ||||
def class_of ( object ): | ||||
""" Returns a string containing the class name of an object with the | ||||
correct indefinite article ('a' or 'an') preceding it (e.g., 'an Image', | ||||
'a PlotValue'). | ||||
""" | ||||
|
r13353 | if isinstance( object, py3compat.string_types ): | ||
|
r2157 | return add_article( object ) | ||
return add_article( object.__class__.__name__ ) | ||||
def add_article ( name ): | ||||
""" Returns a string containing the correct indefinite article ('a' or 'an') | ||||
prefixed to the specified string. | ||||
""" | ||||
if name[:1].lower() in 'aeiou': | ||||
return 'an ' + name | ||||
return 'a ' + name | ||||
def repr_type(obj): | ||||
""" Return a string representation of a value and its type for readable | ||||
error messages. | ||||
""" | ||||
the_type = type(obj) | ||||
|
r4732 | if (not py3compat.PY3) and the_type is InstanceType: | ||
|
r2157 | # Old-style class. | ||
the_type = obj.__class__ | ||||
msg = '%r %r' % (obj, the_type) | ||||
return msg | ||||
|
r8407 | def is_trait(t): | ||
""" Returns whether the given value is an instance or subclass of TraitType. | ||||
""" | ||||
return (isinstance(t, TraitType) or | ||||
(isinstance(t, type) and issubclass(t, TraitType))) | ||||
|
r2157 | def parse_notifier_name(name): | ||
|
r2175 | """Convert the name argument to a list of names. | ||
|
r4872 | |||
|
r2175 | Examples | ||
-------- | ||||
|
r4872 | |||
|
r2175 | >>> parse_notifier_name('a') | ||
['a'] | ||||
>>> parse_notifier_name(['a','b']) | ||||
['a', 'b'] | ||||
>>> parse_notifier_name(None) | ||||
|
r2384 | ['anytrait'] | ||
|
r2175 | """ | ||
|
r18124 | if isinstance(name, string_types): | ||
|
r2157 | return [name] | ||
elif name is None: | ||||
|
r2384 | return ['anytrait'] | ||
|
r2157 | elif isinstance(name, (list, tuple)): | ||
for n in name: | ||||
|
r18124 | assert isinstance(n, string_types), "names must be strings" | ||
|
r2157 | return name | ||
|
r2184 | |||
class _SimpleTest: | ||||
def __init__ ( self, value ): self.value = value | ||||
def __call__ ( self, test ): | ||||
return test == self.value | ||||
def __repr__(self): | ||||
return "<SimpleTest(%r)" % self.value | ||||
def __str__(self): | ||||
return self.__repr__() | ||||
|
r2287 | def getmembers(object, predicate=None): | ||
"""A safe version of inspect.getmembers that handles missing attributes. | ||||
|
r4872 | This is useful when there are descriptor based attributes that for | ||
|
r2287 | some reason raise AttributeError even though they exist. This happens | ||
in zope.inteface with the __provides__ attribute. | ||||
""" | ||||
results = [] | ||||
for key in dir(object): | ||||
try: | ||||
value = getattr(object, key) | ||||
except AttributeError: | ||||
pass | ||||
else: | ||||
if not predicate or predicate(value): | ||||
results.append((key, value)) | ||||
results.sort() | ||||
return results | ||||
|
r20076 | def _validate_link(*tuples): | ||
"""Validate arguments for traitlet link functions""" | ||||
for t in tuples: | ||||
if not len(t) == 2: | ||||
raise TypeError("Each linked traitlet must be specified as (HasTraits, 'trait_name'), not %r" % t) | ||||
obj, trait_name = t | ||||
if not isinstance(obj, HasTraits): | ||||
raise TypeError("Each object must be HasTraits, not %r" % type(obj)) | ||||
if not trait_name in obj.traits(): | ||||
raise TypeError("%r has no trait %r" % (obj, trait_name)) | ||||
|
r15011 | @skip_doctest | ||
|
r15163 | class link(object): | ||
"""Link traits from different objects together so they remain in sync. | ||||
|
r15008 | |||
Parameters | ||||
---------- | ||||
|
r20076 | *args : pairs of objects/attributes | ||
|
r15008 | |||
Examples | ||||
-------- | ||||
|
r15163 | >>> c = link((obj1, 'value'), (obj2, 'value'), (obj3, 'value')) | ||
|
r15008 | >>> obj1.value = 5 # updates other objects as well | ||
""" | ||||
updating = False | ||||
def __init__(self, *args): | ||||
|
r15013 | if len(args) < 2: | ||
raise TypeError('At least two traitlets must be provided.') | ||||
|
r20076 | _validate_link(*args) | ||
|
r15013 | |||
|
r15018 | self.objects = {} | ||
|
r18989 | |||
|
r15018 | initial = getattr(args[0][0], args[0][1]) | ||
|
r18989 | for obj, attr in args: | ||
setattr(obj, attr, initial) | ||||
|
r15008 | |||
|
r18989 | callback = self._make_closure(obj, attr) | ||
|
r15018 | obj.on_trait_change(callback, attr) | ||
|
r18989 | self.objects[(obj, attr)] = callback | ||
|
r15013 | |||
|
r15008 | @contextlib.contextmanager | ||
def _busy_updating(self): | ||||
self.updating = True | ||||
|
r15009 | try: | ||
yield | ||||
finally: | ||||
self.updating = False | ||||
|
r15008 | |||
|
r15018 | def _make_closure(self, sending_obj, sending_attr): | ||
def update(name, old, new): | ||||
self._update(sending_obj, sending_attr, new) | ||||
return update | ||||
def _update(self, sending_obj, sending_attr, new): | ||||
|
r15008 | if self.updating: | ||
return | ||||
with self._busy_updating(): | ||||
|
r18989 | for obj, attr in self.objects.keys(): | ||
setattr(obj, attr, new) | ||||
|
r15163 | def unlink(self): | ||
|
r15018 | for key, callback in self.objects.items(): | ||
|
r18989 | (obj, attr) = key | ||
|
r15018 | obj.on_trait_change(callback, attr, remove=True) | ||
|
r2287 | |||
|
r17627 | @skip_doctest | ||
|
r17629 | class directional_link(object): | ||
|
r17627 | """Link the trait of a source object with traits of target objects. | ||
Parameters | ||||
---------- | ||||
source : pair of object, name | ||||
targets : pairs of objects/attributes | ||||
Examples | ||||
-------- | ||||
|
r17629 | >>> c = directional_link((src, 'value'), (tgt1, 'value'), (tgt2, 'value')) | ||
|
r17627 | >>> src.value = 5 # updates target objects | ||
>>> tgt1.value = 6 # does not update other objects | ||||
""" | ||||
updating = False | ||||
def __init__(self, source, *targets): | ||||
|
r20076 | if len(targets) < 1: | ||
raise TypeError('At least two traitlets must be provided.') | ||||
_validate_link(source, *targets) | ||||
|
r17627 | self.source = source | ||
self.targets = targets | ||||
# Update current value | ||||
src_attr_value = getattr(source[0], source[1]) | ||||
for obj, attr in targets: | ||||
|
r18989 | setattr(obj, attr, src_attr_value) | ||
|
r17627 | |||
# Wire | ||||
self.source[0].on_trait_change(self._update, self.source[1]) | ||||
@contextlib.contextmanager | ||||
def _busy_updating(self): | ||||
self.updating = True | ||||
try: | ||||
yield | ||||
finally: | ||||
self.updating = False | ||||
def _update(self, name, old, new): | ||||
if self.updating: | ||||
return | ||||
with self._busy_updating(): | ||||
for obj, attr in self.targets: | ||||
setattr(obj, attr, new) | ||||
def unlink(self): | ||||
|
r17628 | self.source[0].on_trait_change(self._update, self.source[1], remove=True) | ||
|
r17627 | self.source = None | ||
self.targets = [] | ||||
|
r20076 | dlink = directional_link | ||
|
r17629 | |||
|
r2157 | #----------------------------------------------------------------------------- | ||
|
r2385 | # Base TraitType for all traits | ||
|
r2157 | #----------------------------------------------------------------------------- | ||
|
r2385 | class TraitType(object): | ||
"""A base class for all trait descriptors. | ||||
|
r2183 | |||
Notes | ||||
----- | ||||
|
r2385 | Our implementation of traits is based on Python's descriptor | ||
|
r2183 | prototol. This class is the base class for all such descriptors. The | ||
|
r2384 | only magic we use is a custom metaclass for the main :class:`HasTraits` | ||
|
r2183 | class that does the following: | ||
|
r2385 | 1. Sets the :attr:`name` attribute of every :class:`TraitType` | ||
|
r2183 | instance in the class dict to the name of the attribute. | ||
|
r2385 | 2. Sets the :attr:`this_class` attribute of every :class:`TraitType` | ||
instance in the class dict to the *class* that declared the trait. | ||||
This is used by the :class:`This` trait to allow subclasses to | ||||
|
r2183 | accept superclasses for :class:`This` values. | ||
""" | ||||
|
r4872 | |||
|
r2157 | |||
metadata = {} | ||||
|
r2177 | default_value = Undefined | ||
|
r16453 | allow_none = False | ||
|
r2157 | info_text = 'any value' | ||
|
r16453 | def __init__(self, default_value=NoDefaultSpecified, allow_none=None, **metadata): | ||
|
r2385 | """Create a TraitType. | ||
|
r2177 | """ | ||
|
r2157 | if default_value is not NoDefaultSpecified: | ||
self.default_value = default_value | ||||
|
r16453 | if allow_none is not None: | ||
self.allow_none = allow_none | ||||
|
r2184 | |||
if len(metadata) > 0: | ||||
if len(self.metadata) > 0: | ||||
self._metadata = self.metadata.copy() | ||||
self._metadata.update(metadata) | ||||
else: | ||||
self._metadata = metadata | ||||
else: | ||||
self._metadata = self.metadata | ||||
|
r2177 | self.init() | ||
|
r2157 | |||
|
r2177 | def init(self): | ||
pass | ||||
def get_default_value(self): | ||||
"""Create a new instance of the default value.""" | ||||
|
r2742 | return self.default_value | ||
|
r2177 | |||
|
r2229 | def instance_init(self, obj): | ||
|
r2384 | """This is called by :meth:`HasTraits.__new__` to finish init'ing. | ||
|
r2229 | |||
Some stages of initialization must be delayed until the parent | ||||
|
r2384 | :class:`HasTraits` instance has been created. This method is | ||
called in :meth:`HasTraits.__new__` after the instance has been | ||||
|
r2229 | created. | ||
This method trigger the creation and validation of default values | ||||
|
r4872 | and also things like the resolution of str given class names in | ||
|
r2229 | :class:`Type` and :class`Instance`. | ||
Parameters | ||||
---------- | ||||
|
r2384 | obj : :class:`HasTraits` instance | ||
The parent :class:`HasTraits` instance that has just been | ||||
|
r2229 | created. | ||
""" | ||||
self.set_default_value(obj) | ||||
|
r2182 | def set_default_value(self, obj): | ||
|
r2229 | """Set the default value on a per instance basis. | ||
This method is called by :meth:`instance_init` to create and | ||||
|
r4872 | validate the default value. The creation and validation of | ||
|
r2384 | default values must be delayed until the parent :class:`HasTraits` | ||
|
r2229 | class has been instantiated. | ||
""" | ||||
|
r3207 | # Check for a deferred initializer defined in the same class as the | ||
# trait declaration or above. | ||||
mro = type(obj).mro() | ||||
meth_name = '_%s_default' % self.name | ||||
for cls in mro[:mro.index(self.this_class)+1]: | ||||
if meth_name in cls.__dict__: | ||||
break | ||||
else: | ||||
# We didn't find one. Do static initialization. | ||||
dv = self.get_default_value() | ||||
newdv = self._validate(obj, dv) | ||||
obj._trait_values[self.name] = newdv | ||||
return | ||||
# Complete the dynamic initialization. | ||||
|
r16216 | obj._trait_dyn_inits[self.name] = meth_name | ||
|
r2182 | def __get__(self, obj, cls=None): | ||
|
r2385 | """Get the value of the trait by self.name for the instance. | ||
|
r2180 | |||
|
r2384 | Default values are instantiated when :meth:`HasTraits.__new__` | ||
|
r4872 | is called. Thus by the time this method gets called either the | ||
|
r2182 | default value or a user defined value (they called :meth:`__set__`) | ||
|
r2384 | is in the :class:`HasTraits` instance. | ||
|
r2177 | """ | ||
if obj is None: | ||||
|
r2157 | return self | ||
else: | ||||
|
r2182 | try: | ||
|
r2385 | value = obj._trait_values[self.name] | ||
|
r3207 | except KeyError: | ||
# Check for a dynamic initializer. | ||||
|
r3336 | if self.name in obj._trait_dyn_inits: | ||
|
r16216 | method = getattr(obj, obj._trait_dyn_inits[self.name]) | ||
value = method() | ||||
|
r3207 | # FIXME: Do we really validate here? | ||
value = self._validate(obj, value) | ||||
obj._trait_values[self.name] = value | ||||
return value | ||||
else: | ||||
raise TraitError('Unexpected error in TraitType: ' | ||||
'both default value and dynamic initializer are ' | ||||
'absent.') | ||||
except Exception: | ||||
|
r2384 | # HasTraits should call set_default_value to populate | ||
|
r2182 | # this. So this should never be reached. | ||
|
r2385 | raise TraitError('Unexpected error in TraitType: ' | ||
|
r2182 | 'default value not set properly') | ||
|
r2177 | else: | ||
|
r2182 | return value | ||
|
r2177 | |||
|
r2182 | def __set__(self, obj, value): | ||
|
r2177 | new_value = self._validate(obj, value) | ||
|
r19121 | try: | ||
old_value = obj._trait_values[self.name] | ||||
except KeyError: | ||||
old_value = None | ||||
|
r8230 | obj._trait_values[self.name] = new_value | ||
|
r15436 | try: | ||
|
r15462 | silent = bool(old_value == new_value) | ||
|
r15436 | except: | ||
# if there is an error in comparing, default to notify | ||||
|
r15462 | silent = False | ||
if silent is not True: | ||||
# we explicitly compare silent to True just in case the equality | ||||
# comparison above returns something other than True/False | ||||
|
r2385 | obj._notify_trait(self.name, old_value, new_value) | ||
|
r2157 | |||
|
r2177 | def _validate(self, obj, value): | ||
|
r16453 | if value is None and self.allow_none: | ||
return value | ||||
|
r2157 | if hasattr(self, 'validate'): | ||
|
r2177 | return self.validate(obj, value) | ||
|
r2157 | elif hasattr(self, 'is_valid_for'): | ||
valid = self.is_valid_for(value) | ||||
if valid: | ||||
return value | ||||
else: | ||||
|
r2385 | raise TraitError('invalid value for type: %r' % value) | ||
|
r2157 | elif hasattr(self, 'value_for'): | ||
return self.value_for(value) | ||||
else: | ||||
return value | ||||
|
r18977 | def __or__(self, other): | ||
if isinstance(other, Union): | ||||
return Union([self] + other.trait_types) | ||||
else: | ||||
return Union([self, other]) | ||||
|
r2157 | def info(self): | ||
return self.info_text | ||||
def error(self, obj, value): | ||||
if obj is not None: | ||||
|
r2385 | e = "The '%s' trait of %s instance must be %s, but a value of %s was specified." \ | ||
|
r2157 | % (self.name, class_of(obj), | ||
self.info(), repr_type(value)) | ||||
else: | ||||
|
r2385 | e = "The '%s' trait must be %s, but a value of %r was specified." \ | ||
|
r3870 | % (self.name, self.info(), repr_type(value)) | ||
|
r2385 | raise TraitError(e) | ||
|
r2157 | |||
|
r17673 | def get_metadata(self, key, default=None): | ||
return getattr(self, '_metadata', {}).get(key, default) | ||||
|
r2184 | |||
def set_metadata(self, key, value): | ||||
getattr(self, '_metadata', {})[key] = value | ||||
|
r2157 | |||
#----------------------------------------------------------------------------- | ||||
|
r2384 | # The HasTraits implementation | ||
|
r2157 | #----------------------------------------------------------------------------- | ||
|
r2384 | class MetaHasTraits(type): | ||
"""A metaclass for HasTraits. | ||||
|
r4872 | |||
|
r2385 | This metaclass makes sure that any TraitType class attributes are | ||
|
r2157 | instantiated and sets their name attribute. | ||
""" | ||||
|
r4872 | |||
|
r2157 | def __new__(mcls, name, bases, classdict): | ||
|
r2384 | """Create the HasTraits class. | ||
|
r4872 | |||
|
r2385 | This instantiates all TraitTypes in the class dict and sets their | ||
|
r2183 | :attr:`name` attribute. | ||
""" | ||||
|
r2287 | # print "MetaHasTraitlets (mcls, name): ", mcls, name | ||
# print "MetaHasTraitlets (bases): ", bases | ||||
# print "MetaHasTraitlets (classdict): ", classdict | ||||
|
r13361 | for k,v in iteritems(classdict): | ||
|
r2385 | if isinstance(v, TraitType): | ||
|
r2157 | v.name = k | ||
elif inspect.isclass(v): | ||||
|
r2385 | if issubclass(v, TraitType): | ||
|
r2157 | vinst = v() | ||
vinst.name = k | ||||
classdict[k] = vinst | ||||
|
r2384 | return super(MetaHasTraits, mcls).__new__(mcls, name, bases, classdict) | ||
|
r2157 | |||
|
r2183 | def __init__(cls, name, bases, classdict): | ||
|
r2384 | """Finish initializing the HasTraits class. | ||
|
r4872 | |||
|
r2385 | This sets the :attr:`this_class` attribute of each TraitType in the | ||
|
r2183 | class dict to the newly created class ``cls``. | ||
""" | ||||
|
r13361 | for k, v in iteritems(classdict): | ||
|
r2385 | if isinstance(v, TraitType): | ||
|
r2183 | v.this_class = cls | ||
|
r2384 | super(MetaHasTraits, cls).__init__(name, bases, classdict) | ||
|
r2157 | |||
|
r13359 | class HasTraits(py3compat.with_metaclass(MetaHasTraits, object)): | ||
|
r2157 | |||
|
r10257 | def __new__(cls, *args, **kw): | ||
|
r16320 | # This is needed because object.__new__ only accepts | ||
|
r2255 | # the cls argument. | ||
|
r2384 | new_meth = super(HasTraits, cls).__new__ | ||
|
r2255 | if new_meth is object.__new__: | ||
inst = new_meth(cls) | ||||
else: | ||||
|
r2739 | inst = new_meth(cls, **kw) | ||
|
r2385 | inst._trait_values = {} | ||
inst._trait_notifiers = {} | ||||
|
r3336 | inst._trait_dyn_inits = {} | ||
|
r2385 | # Here we tell all the TraitType instances to set their default | ||
|
r4872 | # values on the instance. | ||
|
r2182 | for key in dir(cls): | ||
|
r2287 | # Some descriptors raise AttributeError like zope.interface's | ||
# __provides__ attributes even though they exist. This causes | ||||
# AttributeErrors even though they are listed in dir(cls). | ||||
try: | ||||
value = getattr(cls, key) | ||||
except AttributeError: | ||||
pass | ||||
else: | ||||
|
r2469 | if isinstance(value, TraitType): | ||
|
r2287 | value.instance_init(inst) | ||
|
r2469 | |||
|
r2182 | return inst | ||
|
r10257 | def __init__(self, *args, **kw): | ||
|
r2740 | # Allow trait values to be set using keyword arguments. | ||
|
r2745 | # We need to use setattr for this to trigger validation and | ||
# notifications. | ||||
|
r13361 | for key, value in iteritems(kw): | ||
|
r2739 | setattr(self, key, value) | ||
|
r2157 | |||
|
r2385 | def _notify_trait(self, name, old_value, new_value): | ||
|
r2175 | |||
# First dynamic ones | ||||
|
r13148 | callables = [] | ||
callables.extend(self._trait_notifiers.get(name,[])) | ||||
callables.extend(self._trait_notifiers.get('anytrait',[])) | ||||
|
r2175 | |||
# Now static ones | ||||
try: | ||||
cb = getattr(self, '_%s_changed' % name) | ||||
except: | ||||
pass | ||||
else: | ||||
callables.append(cb) | ||||
# Call them all now | ||||
|
r2157 | for c in callables: | ||
# Traits catches and logs errors here. I allow them to raise | ||||
|
r2175 | if callable(c): | ||
argspec = inspect.getargspec(c) | ||||
nargs = len(argspec[0]) | ||||
# Bound methods have an additional 'self' argument | ||||
# I don't know how to treat unbound methods, but they | ||||
# can't really be used for callbacks. | ||||
if isinstance(c, types.MethodType): | ||||
offset = -1 | ||||
else: | ||||
offset = 0 | ||||
if nargs + offset == 0: | ||||
c() | ||||
elif nargs + offset == 1: | ||||
c(name) | ||||
elif nargs + offset == 2: | ||||
c(name, new_value) | ||||
elif nargs + offset == 3: | ||||
c(name, old_value, new_value) | ||||
else: | ||||
|
r2385 | raise TraitError('a trait changed callback ' | ||
|
r2175 | 'must have 0-3 arguments.') | ||
else: | ||||
|
r2385 | raise TraitError('a trait changed callback ' | ||
|
r2175 | 'must be callable.') | ||
|
r4872 | |||
|
r2157 | |||
def _add_notifiers(self, handler, name): | ||||
|
r7859 | if name not in self._trait_notifiers: | ||
|
r2157 | nlist = [] | ||
|
r2385 | self._trait_notifiers[name] = nlist | ||
|
r2157 | else: | ||
|
r2385 | nlist = self._trait_notifiers[name] | ||
|
r2157 | if handler not in nlist: | ||
nlist.append(handler) | ||||
def _remove_notifiers(self, handler, name): | ||||
|
r7859 | if name in self._trait_notifiers: | ||
|
r2385 | nlist = self._trait_notifiers[name] | ||
|
r2157 | try: | ||
index = nlist.index(handler) | ||||
except ValueError: | ||||
pass | ||||
else: | ||||
del nlist[index] | ||||
|
r2384 | def on_trait_change(self, handler, name=None, remove=False): | ||
|
r2385 | """Setup a handler to be called when a trait changes. | ||
|
r2175 | |||
|
r2385 | This is used to setup dynamic notifications of trait changes. | ||
|
r4872 | |||
|
r2384 | Static handlers can be created by creating methods on a HasTraits | ||
|
r2385 | subclass with the naming convention '_[traitname]_changed'. Thus, | ||
to create static handler for the trait 'a', create the method | ||||
|
r2175 | _a_changed(self, name, old, new) (fewer arguments can be used, see | ||
below). | ||||
|
r4872 | |||
|
r2175 | Parameters | ||
---------- | ||||
|
r2277 | handler : callable | ||
|
r4872 | A callable that is called when a trait changes. Its | ||
|
r2277 | signature can be handler(), handler(name), handler(name, new) | ||
or handler(name, old, new). | ||||
name : list, str, None | ||||
|
r2385 | If None, the handler will apply to all traits. If a list | ||
|
r2277 | of str, handler will apply to all names in the list. If a | ||
str, the handler will apply just to that name. | ||||
remove : bool | ||||
If False (the default), then install the handler. If True | ||||
then unintall it. | ||||
|
r2175 | """ | ||
|
r2157 | if remove: | ||
names = parse_notifier_name(name) | ||||
for n in names: | ||||
self._remove_notifiers(handler, n) | ||||
else: | ||||
names = parse_notifier_name(name) | ||||
for n in names: | ||||
self._add_notifiers(handler, n) | ||||
|
r3789 | @classmethod | ||
def class_trait_names(cls, **metadata): | ||||
|
r15487 | """Get a list of all the names of this class' traits. | ||
|
r3789 | |||
|
r15487 | This method is just like the :meth:`trait_names` method, | ||
but is unbound. | ||||
|
r3789 | """ | ||
return cls.class_traits(**metadata).keys() | ||||
@classmethod | ||||
def class_traits(cls, **metadata): | ||||
|
r15487 | """Get a `dict` of all the traits of this class. The dictionary | ||
is keyed on the name and the values are the TraitType objects. | ||||
|
r3789 | |||
This method is just like the :meth:`traits` method, but is unbound. | ||||
The TraitTypes returned don't know anything about the values | ||||
that the various HasTrait's instances are holding. | ||||
|
r15487 | The metadata kwargs allow functions to be passed in which | ||
filter traits based on metadata values. The functions should | ||||
take a single value as an argument and return a boolean. If | ||||
any function returns False, then the trait is not included in | ||||
the output. This does not allow for any simple way of | ||||
testing that a metadata name exists and has any | ||||
value because get_metadata returns None if a metadata key | ||||
doesn't exist. | ||||
|
r3789 | """ | ||
|
r15487 | traits = dict([memb for memb in getmembers(cls) if | ||
|
r3789 | isinstance(memb[1], TraitType)]) | ||
if len(metadata) == 0: | ||||
return traits | ||||
for meta_name, meta_eval in metadata.items(): | ||||
if type(meta_eval) is not FunctionType: | ||||
metadata[meta_name] = _SimpleTest(meta_eval) | ||||
result = {} | ||||
for name, trait in traits.items(): | ||||
for meta_name, meta_eval in metadata.items(): | ||||
if not meta_eval(trait.get_metadata(meta_name)): | ||||
break | ||||
else: | ||||
result[name] = trait | ||||
return result | ||||
|
r2384 | def trait_names(self, **metadata): | ||
|
r15487 | """Get a list of all the names of this class' traits.""" | ||
|
r2384 | return self.traits(**metadata).keys() | ||
|
r2184 | |||
|
r2384 | def traits(self, **metadata): | ||
|
r15487 | """Get a `dict` of all the traits of this class. The dictionary | ||
is keyed on the name and the values are the TraitType objects. | ||||
|
r2184 | |||
|
r2385 | The TraitTypes returned don't know anything about the values | ||
that the various HasTrait's instances are holding. | ||||
|
r2245 | |||
|
r15487 | The metadata kwargs allow functions to be passed in which | ||
filter traits based on metadata values. The functions should | ||||
take a single value as an argument and return a boolean. If | ||||
any function returns False, then the trait is not included in | ||||
the output. This does not allow for any simple way of | ||||
testing that a metadata name exists and has any | ||||
value because get_metadata returns None if a metadata key | ||||
doesn't exist. | ||||
|
r2184 | """ | ||
|
r15487 | traits = dict([memb for memb in getmembers(self.__class__) if | ||
|
r2385 | isinstance(memb[1], TraitType)]) | ||
|
r2184 | |||
|
r2245 | if len(metadata) == 0: | ||
|
r2385 | return traits | ||
|
r2200 | |||
|
r2184 | for meta_name, meta_eval in metadata.items(): | ||
if type(meta_eval) is not FunctionType: | ||||
metadata[meta_name] = _SimpleTest(meta_eval) | ||||
result = {} | ||||
|
r2385 | for name, trait in traits.items(): | ||
|
r2184 | for meta_name, meta_eval in metadata.items(): | ||
|
r2385 | if not meta_eval(trait.get_metadata(meta_name)): | ||
|
r2184 | break | ||
else: | ||||
|
r2385 | result[name] = trait | ||
|
r2184 | |||
return result | ||||
|
r2179 | |||
|
r17673 | def trait_metadata(self, traitname, key, default=None): | ||
|
r2385 | """Get metadata values for trait by key.""" | ||
|
r2184 | try: | ||
|
r2385 | trait = getattr(self.__class__, traitname) | ||
|
r2184 | except AttributeError: | ||
|
r2385 | raise TraitError("Class %s does not have a trait named %s" % | ||
(self.__class__.__name__, traitname)) | ||||
|
r2184 | else: | ||
|
r17673 | return trait.get_metadata(key, default) | ||
|
r2177 | |||
|
r2157 | #----------------------------------------------------------------------------- | ||
|
r2385 | # Actual TraitTypes implementations/subclasses | ||
|
r2157 | #----------------------------------------------------------------------------- | ||
|
r2177 | |||
#----------------------------------------------------------------------------- | ||||
|
r2385 | # TraitTypes subclasses for handling classes and instances of classes | ||
|
r2177 | #----------------------------------------------------------------------------- | ||
|
r16453 | class ClassBasedTraitType(TraitType): | ||
|
r18777 | """ | ||
A trait with error reporting and string -> type resolution for Type, | ||||
Instance and This. | ||||
""" | ||||
|
r2177 | |||
|
r18775 | def _resolve_string(self, string): | ||
""" | ||||
Resolve a string supplied for a type into an actual object. | ||||
""" | ||||
return import_item(string) | ||||
|
r2182 | def error(self, obj, value): | ||
|
r2177 | kind = type(value) | ||
|
r4732 | if (not py3compat.PY3) and kind is InstanceType: | ||
|
r2177 | msg = 'class %s' % value.__class__.__name__ | ||
else: | ||||
msg = '%s (i.e. %s)' % ( str( kind )[1:-1], repr( value ) ) | ||||
|
r3870 | if obj is not None: | ||
e = "The '%s' trait of %s instance must be %s, but a value of %s was specified." \ | ||||
% (self.name, class_of(obj), | ||||
self.info(), msg) | ||||
else: | ||||
e = "The '%s' trait must be %s, but a value of %r was specified." \ | ||||
% (self.name, self.info(), msg) | ||||
raise TraitError(e) | ||||
|
r2177 | |||
|
r2385 | class Type(ClassBasedTraitType): | ||
"""A trait whose value must be a subclass of a specified class.""" | ||||
|
r2177 | |||
def __init__ (self, default_value=None, klass=None, allow_none=True, **metadata ): | ||||
|
r2385 | """Construct a Type trait | ||
|
r2177 | |||
|
r2385 | A Type trait specifies that its values must be subclasses of | ||
|
r2177 | a particular class. | ||
|
r2229 | If only ``default_value`` is given, it is used for the ``klass`` as | ||
well. | ||||
|
r2177 | Parameters | ||
---------- | ||||
|
r2229 | default_value : class, str or None | ||
The default value must be a subclass of klass. If an str, | ||||
the str must be a fully specified class name, like 'foo.bar.Bah'. | ||||
|
r4872 | The string is resolved into real class, when the parent | ||
|
r2384 | :class:`HasTraits` class is instantiated. | ||
|
r2177 | klass : class, str, None | ||
|
r2385 | Values of this trait must be a subclass of klass. The klass | ||
|
r2177 | may be specified in a string like: 'foo.bar.MyClass'. | ||
|
r4872 | The string is resolved into real class, when the parent | ||
|
r2384 | :class:`HasTraits` class is instantiated. | ||
|
r2177 | allow_none : boolean | ||
Indicates whether None is allowed as an assignable value. Even if | ||||
``False``, the default value may be ``None``. | ||||
""" | ||||
if default_value is None: | ||||
if klass is None: | ||||
klass = object | ||||
elif klass is None: | ||||
klass = default_value | ||||
|
r13353 | if not (inspect.isclass(klass) or isinstance(klass, py3compat.string_types)): | ||
|
r2385 | raise TraitError("A Type trait must specify a class.") | ||
|
r2177 | |||
self.klass = klass | ||||
|
r16544 | super(Type, self).__init__(default_value, allow_none=allow_none, **metadata) | ||
|
r2177 | |||
def validate(self, obj, value): | ||||
"""Validates that the value is a valid object instance.""" | ||||
|
r16961 | if isinstance(value, py3compat.string_types): | ||
try: | ||||
|
r18776 | value = self._resolve_string(value) | ||
|
r16961 | except ImportError: | ||
raise TraitError("The '%s' trait of %s instance must be a type, but " | ||||
"%r could not be imported" % (self.name, obj, value)) | ||||
|
r2177 | try: | ||
if issubclass(value, self.klass): | ||||
return value | ||||
except: | ||||
|
r16453 | pass | ||
|
r2177 | |||
self.error(obj, value) | ||||
def info(self): | ||||
""" Returns a description of the trait.""" | ||||
|
r13353 | if isinstance(self.klass, py3compat.string_types): | ||
|
r2229 | klass = self.klass | ||
else: | ||||
klass = self.klass.__name__ | ||||
|
r2177 | result = 'a subclass of ' + klass | ||
|
r16453 | if self.allow_none: | ||
|
r2177 | return result + ' or None' | ||
return result | ||||
|
r2229 | def instance_init(self, obj): | ||
self._resolve_classes() | ||||
super(Type, self).instance_init(obj) | ||||
def _resolve_classes(self): | ||||
|
r13353 | if isinstance(self.klass, py3compat.string_types): | ||
|
r18775 | self.klass = self._resolve_string(self.klass) | ||
|
r13353 | if isinstance(self.default_value, py3compat.string_types): | ||
|
r18775 | self.default_value = self._resolve_string(self.default_value) | ||
|
r2229 | |||
def get_default_value(self): | ||||
return self.default_value | ||||
|
r2177 | |||
class DefaultValueGenerator(object): | ||||
"""A class for generating new default value instances.""" | ||||
|
r2229 | def __init__(self, *args, **kw): | ||
|
r2177 | self.args = args | ||
self.kw = kw | ||||
|
r2229 | def generate(self, klass): | ||
return klass(*self.args, **self.kw) | ||||
|
r2177 | |||
|
r2182 | |||
|
r2385 | class Instance(ClassBasedTraitType): | ||
|
r2177 | """A trait whose value must be an instance of a specified class. | ||
|
r4872 | |||
|
r2177 | The value can also be an instance of a subclass of the specified class. | ||
|
r17238 | |||
Subclasses can declare default classes by overriding the klass attribute | ||||
|
r2177 | """ | ||
|
r17238 | klass = None | ||
|
r4872 | def __init__(self, klass=None, args=None, kw=None, | ||
|
r2182 | allow_none=True, **metadata ): | ||
|
r2385 | """Construct an Instance trait. | ||
|
r2177 | |||
|
r2385 | This trait allows values that are instances of a particular | ||
|
r18972 | class or its subclasses. Our implementation is quite different | ||
|
r2182 | from that of enthough.traits as we don't allow instances to be used | ||
for klass and we handle the ``args`` and ``kw`` arguments differently. | ||||
|
r2177 | Parameters | ||
---------- | ||||
|
r2229 | klass : class, str | ||
|
r2385 | The class that forms the basis for the trait. Class names | ||
|
r2229 | can also be specified as strings, like 'foo.bar.Bar'. | ||
|
r2177 | args : tuple | ||
Positional arguments for generating the default value. | ||||
kw : dict | ||||
Keyword arguments for generating the default value. | ||||
allow_none : bool | ||||
Indicates whether None is allowed as a value. | ||||
|
r13587 | Notes | ||
----- | ||||
|
r2182 | If both ``args`` and ``kw`` are None, then the default value is None. | ||
If ``args`` is a tuple and ``kw`` is a dict, then the default is | ||||
|
r17238 | created as ``klass(*args, **kw)``. If exactly one of ``args`` or ``kw`` is | ||
None, the None is replaced by ``()`` or ``{}``, respectively. | ||||
|
r2177 | """ | ||
|
r17238 | if klass is None: | ||
klass = self.klass | ||||
if (klass is not None) and (inspect.isclass(klass) or isinstance(klass, py3compat.string_types)): | ||||
self.klass = klass | ||||
else: | ||||
raise TraitError('The klass attribute must be a class' | ||||
' not: %r' % klass) | ||||
|
r4872 | |||
|
r2182 | # self.klass is a class, so handle default_value | ||
if args is None and kw is None: | ||||
|
r2177 | default_value = None | ||
else: | ||||
if args is None: | ||||
|
r2182 | # kw is not None | ||
|
r2177 | args = () | ||
|
r2182 | elif kw is None: | ||
# args is not None | ||||
kw = {} | ||||
|
r4872 | |||
|
r2177 | if not isinstance(kw, dict): | ||
|
r2385 | raise TraitError("The 'kw' argument must be a dict or None.") | ||
|
r2177 | if not isinstance(args, tuple): | ||
|
r2385 | raise TraitError("The 'args' argument must be a tuple or None.") | ||
|
r4872 | |||
|
r2229 | default_value = DefaultValueGenerator(*args, **kw) | ||
|
r2177 | |||
|
r16544 | super(Instance, self).__init__(default_value, allow_none=allow_none, **metadata) | ||
|
r2177 | |||
def validate(self, obj, value): | ||||
if isinstance(value, self.klass): | ||||
return value | ||||
else: | ||||
|
r2182 | self.error(obj, value) | ||
|
r2177 | |||
|
r2182 | def info(self): | ||
|
r13353 | if isinstance(self.klass, py3compat.string_types): | ||
|
r2229 | klass = self.klass | ||
else: | ||||
klass = self.klass.__name__ | ||||
|
r2177 | result = class_of(klass) | ||
|
r16453 | if self.allow_none: | ||
|
r2177 | return result + ' or None' | ||
return result | ||||
|
r2229 | def instance_init(self, obj): | ||
self._resolve_classes() | ||||
super(Instance, self).instance_init(obj) | ||||
def _resolve_classes(self): | ||||
|
r13353 | if isinstance(self.klass, py3compat.string_types): | ||
|
r18775 | self.klass = self._resolve_string(self.klass) | ||
|
r2229 | |||
|
r2182 | def get_default_value(self): | ||
|
r2177 | """Instantiate a default value instance. | ||
|
r4872 | |||
|
r2384 | This is called when the containing HasTraits classes' | ||
|
r2182 | :meth:`__new__` method is called to ensure that a unique instance | ||
|
r2384 | is created for each HasTraits instance. | ||
|
r2177 | """ | ||
dv = self.default_value | ||||
if isinstance(dv, DefaultValueGenerator): | ||||
|
r2229 | return dv.generate(self.klass) | ||
|
r2177 | else: | ||
return dv | ||||
|
r18745 | class ForwardDeclaredMixin(object): | ||
""" | ||||
Mixin for forward-declared versions of Instance and Type. | ||||
""" | ||||
|
r18775 | def _resolve_string(self, string): | ||
|
r18745 | """ | ||
Find the specified class name by looking for it in the module in which | ||||
our this_class attribute was defined. | ||||
""" | ||||
|
r18819 | modname = self.this_class.__module__ | ||
return import_item('.'.join([modname, string])) | ||||
|
r18745 | |||
|
r18746 | |||
|
r18745 | class ForwardDeclaredType(ForwardDeclaredMixin, Type): | ||
""" | ||||
Forward-declared version of Type. | ||||
""" | ||||
pass | ||||
|
r18746 | |||
|
r18745 | class ForwardDeclaredInstance(ForwardDeclaredMixin, Instance): | ||
""" | ||||
Forward-declared version of Instance. | ||||
""" | ||||
pass | ||||
|
r18746 | |||
|
r2385 | class This(ClassBasedTraitType): | ||
"""A trait for instances of the class containing this trait. | ||||
|
r2180 | |||
|
r2182 | Because how how and when class bodies are executed, the ``This`` | ||
|
r4872 | trait can only have a default value of None. This, and because we | ||
|
r2182 | always validate default values, ``allow_none`` is *always* true. | ||
""" | ||||
|
r2180 | |||
|
r2182 | info_text = 'an instance of the same type as the receiver or None' | ||
|
r2180 | |||
|
r2182 | def __init__(self, **metadata): | ||
super(This, self).__init__(None, **metadata) | ||||
|
r2180 | |||
|
r2182 | def validate(self, obj, value): | ||
|
r2183 | # What if value is a superclass of obj.__class__? This is | ||
# complicated if it was the superclass that defined the This | ||||
|
r2385 | # trait. | ||
|
r2183 | if isinstance(value, self.this_class) or (value is None): | ||
|
r2180 | return value | ||
else: | ||||
|
r2182 | self.error(obj, value) | ||
|
r2180 | |||
|
r18972 | class Union(TraitType): | ||
"""A trait type representing a Union type.""" | ||||
def __init__(self, trait_types, **metadata): | ||||
"""Construct a Union trait. | ||||
This trait allows values that are allowed by at least one of the | ||||
specified trait types. | ||||
Parameters | ||||
---------- | ||||
trait_types: sequence | ||||
The list of trait types of length at least 1. | ||||
Notes | ||||
----- | ||||
Union([Float(), Bool(), Int()]) attempts to validate the provided values | ||||
with the validation function of Float, then Bool, and finally Int. | ||||
""" | ||||
self.trait_types = trait_types | ||||
self.info_text = " or ".join([tt.info_text for tt in self.trait_types]) | ||||
self.default_value = self.trait_types[0].get_default_value() | ||||
super(Union, self).__init__(**metadata) | ||||
|
r20455 | def _resolve_classes(self): | ||
|
r18973 | for trait_type in self.trait_types: | ||
trait_type.name = self.name | ||||
trait_type.this_class = self.this_class | ||||
|
r18976 | if hasattr(trait_type, '_resolve_classes'): | ||
trait_type._resolve_classes() | ||||
|
r20455 | |||
def instance_init(self, obj): | ||||
self._resolve_classes() | ||||
|
r18973 | super(Union, self).instance_init(obj) | ||
|
r18972 | def validate(self, obj, value): | ||
for trait_type in self.trait_types: | ||||
try: | ||||
|
r20081 | v = trait_type._validate(obj, value) | ||
self._metadata = trait_type._metadata | ||||
return v | ||||
|
r18977 | except TraitError: | ||
|
r18972 | continue | ||
self.error(obj, value) | ||||
|
r18977 | def __or__(self, other): | ||
if isinstance(other, Union): | ||||
return Union(self.trait_types + other.trait_types) | ||||
else: | ||||
return Union(self.trait_types + [other]) | ||||
|
r2177 | #----------------------------------------------------------------------------- | ||
|
r2385 | # Basic TraitTypes implementations/subclasses | ||
|
r2177 | #----------------------------------------------------------------------------- | ||
|
r2157 | |||
|
r2385 | class Any(TraitType): | ||
|
r2157 | default_value = None | ||
info_text = 'any value' | ||||
|
r16453 | class Int(TraitType): | ||
|
r5344 | """An int trait.""" | ||
|
r2157 | |||
default_value = 0 | ||||
|
r5344 | info_text = 'an int' | ||
|
r2157 | |||
def validate(self, obj, value): | ||||
|
r16453 | if isinstance(value, int): | ||
|
r2157 | return value | ||
self.error(obj, value) | ||||
|
r2178 | class CInt(Int): | ||
|
r2385 | """A casting version of the int trait.""" | ||
|
r2178 | |||
def validate(self, obj, value): | ||||
try: | ||||
return int(value) | ||||
except: | ||||
self.error(obj, value) | ||||
|
r4764 | if py3compat.PY3: | ||
Long, CLong = Int, CInt | ||||
|
r5344 | Integer = Int | ||
|
r4764 | else: | ||
|
r16453 | class Long(TraitType): | ||
|
r4732 | """A long integer trait.""" | ||
|
r2157 | |||
|
r13352 | default_value = 0 | ||
|
r4732 | info_text = 'a long' | ||
|
r2157 | |||
|
r4732 | def validate(self, obj, value): | ||
|
r16453 | if isinstance(value, long): | ||
|
r4732 | return value | ||
if isinstance(value, int): | ||||
return long(value) | ||||
self.error(obj, value) | ||||
|
r2157 | |||
|
r4732 | class CLong(Long): | ||
"""A casting version of the long integer trait.""" | ||||
|
r2178 | |||
|
r4732 | def validate(self, obj, value): | ||
try: | ||||
return long(value) | ||||
except: | ||||
self.error(obj, value) | ||||
|
r2178 | |||
|
r16453 | class Integer(TraitType): | ||
|
r5344 | """An integer trait. | ||
Longs that are unnecessary (<= sys.maxint) are cast to ints.""" | ||||
default_value = 0 | ||||
info_text = 'an integer' | ||||
def validate(self, obj, value): | ||||
|
r16453 | if isinstance(value, int): | ||
|
r5344 | return value | ||
|
r8500 | if isinstance(value, long): | ||
|
r5344 | # downcast longs that fit in int: | ||
# note that int(n > sys.maxint) returns a long, so | ||||
# we don't need a condition on this cast | ||||
return int(value) | ||||
|
r8500 | if sys.platform == "cli": | ||
from System import Int64 | ||||
if isinstance(value, Int64): | ||||
return int(value) | ||||
|
r5344 | self.error(obj, value) | ||
|
r2178 | |||
|
r16453 | class Float(TraitType): | ||
|
r2385 | """A float trait.""" | ||
|
r2157 | |||
default_value = 0.0 | ||||
info_text = 'a float' | ||||
def validate(self, obj, value): | ||||
|
r16453 | if isinstance(value, float): | ||
|
r2157 | return value | ||
if isinstance(value, int): | ||||
return float(value) | ||||
self.error(obj, value) | ||||
|
r2178 | class CFloat(Float): | ||
|
r2385 | """A casting version of the float trait.""" | ||
|
r2178 | |||
def validate(self, obj, value): | ||||
try: | ||||
return float(value) | ||||
except: | ||||
self.error(obj, value) | ||||
|
r16453 | class Complex(TraitType): | ||
|
r2385 | """A trait for complex numbers.""" | ||
|
r2157 | |||
default_value = 0.0 + 0.0j | ||||
info_text = 'a complex number' | ||||
def validate(self, obj, value): | ||||
|
r16453 | if isinstance(value, complex): | ||
|
r2157 | return value | ||
if isinstance(value, (float, int)): | ||||
return complex(value) | ||||
self.error(obj, value) | ||||
|
r2178 | class CComplex(Complex): | ||
|
r2385 | """A casting version of the complex number trait.""" | ||
|
r2178 | |||
def validate (self, obj, value): | ||||
try: | ||||
return complex(value) | ||||
except: | ||||
self.error(obj, value) | ||||
|
r4046 | # We should always be explicit about whether we're using bytes or unicode, both | ||
# for Python 3 conversion and for reliable unicode behaviour on Python 2. So | ||||
# we don't have a Str type. | ||||
|
r16453 | class Bytes(TraitType): | ||
|
r4732 | """A trait for byte strings.""" | ||
|
r2157 | |||
|
r5287 | default_value = b'' | ||
|
r13429 | info_text = 'a bytes object' | ||
|
r2157 | |||
def validate(self, obj, value): | ||||
|
r16453 | if isinstance(value, bytes): | ||
|
r2157 | return value | ||
self.error(obj, value) | ||||
|
r4044 | class CBytes(Bytes): | ||
|
r4732 | """A casting version of the byte string trait.""" | ||
|
r2178 | |||
def validate(self, obj, value): | ||||
try: | ||||
|
r4044 | return bytes(value) | ||
|
r2178 | except: | ||
|
r4045 | self.error(obj, value) | ||
|
r2178 | |||
|
r16453 | class Unicode(TraitType): | ||
|
r2385 | """A trait for unicode strings.""" | ||
|
r2157 | |||
default_value = u'' | ||||
info_text = 'a unicode string' | ||||
def validate(self, obj, value): | ||||
|
r16453 | if isinstance(value, py3compat.unicode_type): | ||
|
r2157 | return value | ||
|
r4044 | if isinstance(value, bytes): | ||
|
r13734 | try: | ||
return value.decode('ascii', 'strict') | ||||
except UnicodeDecodeError: | ||||
msg = "Could not decode {!r} for unicode trait '{}' of {} instance." | ||||
raise TraitError(msg.format(value, self.name, class_of(obj))) | ||||
|
r2157 | self.error(obj, value) | ||
|
r2178 | class CUnicode(Unicode): | ||
|
r2385 | """A casting version of the unicode trait.""" | ||
|
r2178 | |||
def validate(self, obj, value): | ||||
try: | ||||
|
r13353 | return py3compat.unicode_type(value) | ||
|
r2178 | except: | ||
self.error(obj, value) | ||||
|
r4872 | |||
|
r21138 | class _CoercedString(TraitType): | ||
|
r4047 | |||
|
r4740 | if py3compat.PY3: | ||
# Python 3: | ||||
|
r21138 | _coerce_str = staticmethod(lambda _,s: s) | ||
|
r4740 | else: | ||
|
r4047 | # Python 2: | ||
|
r21138 | def _coerce_str(self, obj, value): | ||
|
r4047 | "In Python 2, coerce ascii-only unicode to str" | ||
if isinstance(value, unicode): | ||||
try: | ||||
return str(value) | ||||
except UnicodeEncodeError: | ||||
self.error(obj, value) | ||||
return value | ||||
|
r4872 | |||
|
r21138 | |||
class ObjectName(_CoercedString): | ||||
"""A string holding a valid object name in this version of Python. | ||||
This does not check that the name exists in any scope.""" | ||||
info_text = "a valid object identifier in Python" | ||||
|
r4047 | def validate(self, obj, value): | ||
|
r21138 | value = self._coerce_str(obj, value) | ||
|
r4872 | |||
|
r18124 | if isinstance(value, string_types) and py3compat.isidentifier(value): | ||
|
r4047 | return value | ||
self.error(obj, value) | ||||
|
r21138 | |||
|
r4047 | class DottedObjectName(ObjectName): | ||
"""A string holding a valid dotted object name in Python, such as A.b3._c""" | ||||
|
r21138 | |||
|
r4047 | def validate(self, obj, value): | ||
|
r21138 | value = self._coerce_str(obj, value) | ||
|
r4872 | |||
|
r18124 | if isinstance(value, string_types) and py3compat.isidentifier(value, dotted=True): | ||
|
r4047 | return value | ||
self.error(obj, value) | ||||
|
r2178 | |||
|
r2157 | |||
|
r21138 | _color_names = ['aliceblue', 'antiquewhite', 'aqua', 'aquamarine', 'azure', 'beige', 'bisque', 'black', 'blanchedalmond', 'blue', 'blueviolet', 'brown', 'burlywood', 'cadetblue', 'chartreuse', 'chocolate', 'coral', 'cornflowerblue', 'cornsilk', 'crimson', 'cyan', 'darkblue', 'darkcyan', 'darkgoldenrod', 'darkgray', 'darkgreen', 'darkkhaki', 'darkmagenta', 'darkolivegreen', 'darkorange', 'darkorchid', 'darkred', 'darksalmon', 'darkseagreen', 'darkslateblue', 'darkslategray', 'darkturquoise', 'darkviolet', 'deeppink', 'deepskyblue', 'dimgray', 'dodgerblue', 'firebrick', 'floralwhite', 'forestgreen', 'fuchsia', 'gainsboro', 'ghostwhite', 'gold', 'goldenrod', 'gray', 'green', 'greenyellow', 'honeydew', 'hotpink', 'indianred ', 'indigo ', 'ivory', 'khaki', 'lavender', 'lavenderblush', 'lawngreen', 'lemonchiffon', 'lightblue', 'lightcoral', 'lightcyan', 'lightgoldenrodyellow', 'lightgray', 'lightgreen', 'lightpink', 'lightsalmon', 'lightseagreen', 'lightskyblue', 'lightslategray', 'lightsteelblue', 'lightyellow', 'lime', 'limegreen', 'linen', 'magenta', 'maroon', 'mediumaquamarine', 'mediumblue', 'mediumorchid', 'mediumpurple', 'mediumseagreen', 'mediumslateblue', 'mediumspringgreen', 'mediumturquoise', 'mediumvioletred', 'midnightblue', 'mintcream', 'mistyrose', 'moccasin', 'navajowhite', 'navy', 'oldlace', 'olive', 'olivedrab', 'orange', 'orangered', 'orchid', 'palegoldenrod', 'palegreen', 'paleturquoise', 'palevioletred', 'papayawhip', 'peachpuff', 'peru', 'pink', 'plum', 'powderblue', 'purple', 'rebeccapurple', 'red', 'rosybrown', 'royalblue', 'saddlebrown', 'salmon', 'sandybrown', 'seagreen', 'seashell', 'sienna', 'silver', 'skyblue', 'slateblue', 'slategray', 'snow', 'springgreen', 'steelblue', 'tan', 'teal', 'thistle', 'tomato', 'turquoise', 'violet', 'wheat', 'white', 'whitesmoke', 'yellow', 'yellowgreen'] | ||
_color_re = re.compile(r'#[a-fA-F0-9]{3}(?:[a-fA-F0-9]{3})?$') | ||||
class Color(_CoercedString): | ||||
"""A string holding a valid HTML color such as 'blue', '#060482', '#A80'""" | ||||
info_text = 'a valid HTML color' | ||||
def validate(self, obj, value): | ||||
value = self._coerce_str(obj, value) | ||||
if value.lower() in _color_names or _color_re.match(value): | ||||
return value | ||||
self.error(obj, value) | ||||
|
r16453 | class Bool(TraitType): | ||
|
r2385 | """A boolean (True, False) trait.""" | ||
|
r2742 | |||
|
r2157 | default_value = False | ||
info_text = 'a boolean' | ||||
def validate(self, obj, value): | ||||
|
r16453 | if isinstance(value, bool): | ||
|
r2157 | return value | ||
self.error(obj, value) | ||||
|
r2178 | |||
class CBool(Bool): | ||||
|
r2385 | """A casting version of the boolean trait.""" | ||
|
r2178 | |||
def validate(self, obj, value): | ||||
try: | ||||
return bool(value) | ||||
except: | ||||
|
r2203 | self.error(obj, value) | ||
|
r2204 | |||
|
r2385 | class Enum(TraitType): | ||
|
r2204 | """An enum that whose value must be in a given sequence.""" | ||
|
r2203 | |||
def __init__(self, values, default_value=None, allow_none=True, **metadata): | ||||
self.values = values | ||||
|
r16544 | super(Enum, self).__init__(default_value, allow_none=allow_none, **metadata) | ||
|
r2203 | |||
def validate(self, obj, value): | ||||
if value in self.values: | ||||
return value | ||||
self.error(obj, value) | ||||
def info(self): | ||||
""" Returns a description of the trait.""" | ||||
result = 'any of ' + repr(self.values) | ||||
|
r16453 | if self.allow_none: | ||
|
r2203 | return result + ' or None' | ||
return result | ||||
class CaselessStrEnum(Enum): | ||||
|
r2204 | """An enum of strings that are caseless in validate.""" | ||
|
r2203 | |||
def validate(self, obj, value): | ||||
|
r13353 | if not isinstance(value, py3compat.string_types): | ||
|
r2203 | self.error(obj, value) | ||
for v in self.values: | ||||
if v.lower() == value.lower(): | ||||
return v | ||||
|
r2204 | self.error(obj, value) | ||
|
r3870 | class Container(Instance): | ||
"""An instance of a container (list, set, etc.) | ||||
|
r2204 | |||
|
r3870 | To be subclassed by overriding klass. | ||
""" | ||||
klass = None | ||||
|
r15472 | _cast_types = () | ||
|
r3870 | _valid_defaults = SequenceTypes | ||
_trait = None | ||||
|
r2204 | |||
|
r3870 | def __init__(self, trait=None, default_value=None, allow_none=True, | ||
**metadata): | ||||
"""Create a container trait type from a list, set, or tuple. | ||||
|
r2204 | |||
|
r3870 | The default value is created by doing ``List(default_value)``, | ||
|
r2204 | which creates a copy of the ``default_value``. | ||
|
r3870 | |||
``trait`` can be specified, which restricts the type of elements | ||||
in the container to that TraitType. | ||||
If only one arg is given and it is not a Trait, it is taken as | ||||
``default_value``: | ||||
``c = List([1,2,3])`` | ||||
Parameters | ||||
---------- | ||||
trait : TraitType [ optional ] | ||||
the type for restricting the contents of the Container. If unspecified, | ||||
types are not checked. | ||||
default_value : SequenceType [ optional ] | ||||
The default value for the Trait. Must be list/tuple/set, and | ||||
will be cast to the container type. | ||||
allow_none : Bool [ default True ] | ||||
Whether to allow the value to be None | ||||
**metadata : any | ||||
further keys for extensions to the Trait (e.g. config) | ||||
|
r2204 | """ | ||
|
r3870 | # allow List([values]): | ||
|
r8407 | if default_value is None and not is_trait(trait): | ||
|
r3870 | default_value = trait | ||
trait = None | ||||
|
r2204 | if default_value is None: | ||
|
r3870 | args = () | ||
elif isinstance(default_value, self._valid_defaults): | ||||
|
r2204 | args = (default_value,) | ||
|
r2380 | else: | ||
|
r3870 | raise TypeError('default value of %s was %s' %(self.__class__.__name__, default_value)) | ||
|
r8407 | if is_trait(trait): | ||
self._trait = trait() if isinstance(trait, type) else trait | ||||
|
r3870 | self._trait.name = 'element' | ||
elif trait is not None: | ||||
raise TypeError("`trait` must be a Trait or None, got %s"%repr_type(trait)) | ||||
|
r2204 | |||
|
r3870 | super(Container,self).__init__(klass=self.klass, args=args, | ||
|
r2204 | allow_none=allow_none, **metadata) | ||
|
r2742 | |||
|
r3870 | def element_error(self, obj, element, validator): | ||
e = "Element of the '%s' trait of %s instance must be %s, but a value of %s was specified." \ | ||||
% (self.name, class_of(obj), validator.info(), repr_type(element)) | ||||
raise TraitError(e) | ||||
|
r2742 | |||
|
r3870 | def validate(self, obj, value): | ||
|
r15472 | if isinstance(value, self._cast_types): | ||
value = self.klass(value) | ||||
|
r3870 | value = super(Container, self).validate(obj, value) | ||
if value is None: | ||||
return value | ||||
|
r3604 | |||
|
r3870 | value = self.validate_elements(obj, value) | ||
return value | ||||
def validate_elements(self, obj, value): | ||||
validated = [] | ||||
if self._trait is None or isinstance(self._trait, Any): | ||||
return value | ||||
for v in value: | ||||
try: | ||||
|
r16546 | v = self._trait._validate(obj, v) | ||
|
r3870 | except TraitError: | ||
self.element_error(obj, v, self._trait) | ||||
else: | ||||
validated.append(v) | ||||
return self.klass(validated) | ||||
|
r16545 | def instance_init(self, obj): | ||
|
r18744 | if isinstance(self._trait, TraitType): | ||
self._trait.this_class = self.this_class | ||||
|
r20407 | if hasattr(self._trait, '_resolve_classes'): | ||
self._trait._resolve_classes() | ||||
|
r16545 | super(Container, self).instance_init(obj) | ||
|
r3870 | |||
class List(Container): | ||||
"""An instance of a Python list.""" | ||||
klass = list | ||||
|
r15472 | _cast_types = (tuple,) | ||
|
r3604 | |||
|
r8494 | def __init__(self, trait=None, default_value=None, minlen=0, maxlen=sys.maxsize, | ||
|
r3870 | allow_none=True, **metadata): | ||
"""Create a List trait type from a list, set, or tuple. | ||||
The default value is created by doing ``List(default_value)``, | ||||
|
r3604 | which creates a copy of the ``default_value``. | ||
|
r3870 | |||
``trait`` can be specified, which restricts the type of elements | ||||
in the container to that TraitType. | ||||
If only one arg is given and it is not a Trait, it is taken as | ||||
``default_value``: | ||||
``c = List([1,2,3])`` | ||||
Parameters | ||||
---------- | ||||
trait : TraitType [ optional ] | ||||
the type for restricting the contents of the Container. If unspecified, | ||||
types are not checked. | ||||
default_value : SequenceType [ optional ] | ||||
The default value for the Trait. Must be list/tuple/set, and | ||||
will be cast to the container type. | ||||
minlen : Int [ default 0 ] | ||||
The minimum length of the input list | ||||
|
r8494 | maxlen : Int [ default sys.maxsize ] | ||
|
r3870 | The maximum length of the input list | ||
allow_none : Bool [ default True ] | ||||
Whether to allow the value to be None | ||||
**metadata : any | ||||
further keys for extensions to the Trait (e.g. config) | ||||
|
r3604 | """ | ||
|
r3870 | self._minlen = minlen | ||
self._maxlen = maxlen | ||||
super(List, self).__init__(trait=trait, default_value=default_value, | ||||
allow_none=allow_none, **metadata) | ||||
def length_error(self, obj, value): | ||||
e = "The '%s' trait of %s instance must be of length %i <= L <= %i, but a value of %s was specified." \ | ||||
% (self.name, class_of(obj), self._minlen, self._maxlen, value) | ||||
raise TraitError(e) | ||||
def validate_elements(self, obj, value): | ||||
length = len(value) | ||||
if length < self._minlen or length > self._maxlen: | ||||
self.length_error(obj, value) | ||||
return super(List, self).validate_elements(obj, value) | ||||
|
r16453 | |||
|
r15472 | def validate(self, obj, value): | ||
value = super(List, self).validate(obj, value) | ||||
value = self.validate_elements(obj, value) | ||||
return value | ||||
|
r16453 | |||
|
r3870 | |||
|
r15472 | class Set(List): | ||
|
r3870 | """An instance of a Python set.""" | ||
klass = set | ||||
|
r15472 | _cast_types = (tuple, list) | ||
|
r3870 | |||
class Tuple(Container): | ||||
"""An instance of a Python tuple.""" | ||||
klass = tuple | ||||
|
r15472 | _cast_types = (list,) | ||
|
r3870 | |||
def __init__(self, *traits, **metadata): | ||||
"""Tuple(*traits, default_value=None, allow_none=True, **medatata) | ||||
Create a tuple from a list, set, or tuple. | ||||
Create a fixed-type tuple with Traits: | ||||
``t = Tuple(Int, Str, CStr)`` | ||||
would be length 3, with Int,Str,CStr for each element. | ||||
If only one arg is given and it is not a Trait, it is taken as | ||||
default_value: | ||||
``t = Tuple((1,2,3))`` | ||||
Otherwise, ``default_value`` *must* be specified by keyword. | ||||
Parameters | ||||
---------- | ||||
*traits : TraitTypes [ optional ] | ||||
|
r20880 | the types for restricting the contents of the Tuple. If unspecified, | ||
|
r3870 | types are not checked. If specified, then each positional argument | ||
corresponds to an element of the tuple. Tuples defined with traits | ||||
are of fixed length. | ||||
default_value : SequenceType [ optional ] | ||||
The default value for the Tuple. Must be list/tuple/set, and | ||||
will be cast to a tuple. If `traits` are specified, the | ||||
`default_value` must conform to the shape and type they specify. | ||||
allow_none : Bool [ default True ] | ||||
Whether to allow the value to be None | ||||
**metadata : any | ||||
further keys for extensions to the Trait (e.g. config) | ||||
""" | ||||
default_value = metadata.pop('default_value', None) | ||||
allow_none = metadata.pop('allow_none', True) | ||||
# allow Tuple((values,)): | ||||
|
r8407 | if len(traits) == 1 and default_value is None and not is_trait(traits[0]): | ||
|
r3870 | default_value = traits[0] | ||
traits = () | ||||
|
r3604 | if default_value is None: | ||
|
r3870 | args = () | ||
elif isinstance(default_value, self._valid_defaults): | ||||
|
r3604 | args = (default_value,) | ||
else: | ||||
|
r3870 | raise TypeError('default value of %s was %s' %(self.__class__.__name__, default_value)) | ||
self._traits = [] | ||||
for trait in traits: | ||||
|
r8407 | t = trait() if isinstance(trait, type) else trait | ||
|
r3870 | t.name = 'element' | ||
self._traits.append(t) | ||||
if self._traits and default_value is None: | ||||
# don't allow default to be an empty container if length is specified | ||||
args = None | ||||
super(Container,self).__init__(klass=self.klass, args=args, | ||||
|
r3604 | allow_none=allow_none, **metadata) | ||
|
r3870 | def validate_elements(self, obj, value): | ||
if not self._traits: | ||||
# nothing to validate | ||||
return value | ||||
if len(value) != len(self._traits): | ||||
e = "The '%s' trait of %s instance requires %i elements, but a value of %s was specified." \ | ||||
% (self.name, class_of(obj), len(self._traits), repr_type(value)) | ||||
raise TraitError(e) | ||||
validated = [] | ||||
for t,v in zip(self._traits, value): | ||||
try: | ||||
|
r16547 | v = t._validate(obj, v) | ||
|
r3870 | except TraitError: | ||
self.element_error(obj, v, t) | ||||
else: | ||||
validated.append(v) | ||||
return tuple(validated) | ||||
|
r20408 | def instance_init(self, obj): | ||
for trait in self._traits: | ||||
if isinstance(trait, TraitType): | ||||
trait.this_class = self.this_class | ||||
if hasattr(trait, '_resolve_classes'): | ||||
trait._resolve_classes() | ||||
super(Container, self).instance_init(obj) | ||||
|
r3604 | |||
|
r2738 | class Dict(Instance): | ||
"""An instance of a Python dict.""" | ||||
|
r20308 | def __init__(self, default_value={}, allow_none=True, **metadata): | ||
|
r2738 | """Create a dict trait type from a dict. | ||
|
r4872 | The default value is created by doing ``dict(default_value)``, | ||
|
r2738 | which creates a copy of the ``default_value``. | ||
""" | ||||
if default_value is None: | ||||
|
r20308 | args = None | ||
|
r2738 | elif isinstance(default_value, dict): | ||
args = (default_value,) | ||||
elif isinstance(default_value, SequenceTypes): | ||||
args = (default_value,) | ||||
else: | ||||
raise TypeError('default value of Dict was %s' % default_value) | ||||
|
r4872 | super(Dict,self).__init__(klass=dict, args=args, | ||
|
r2738 | allow_none=allow_none, **metadata) | ||
|
r2752 | |||
|
r17560 | |||
class EventfulDict(Instance): | ||||
"""An instance of an EventfulDict.""" | ||||
|
r20308 | def __init__(self, default_value={}, allow_none=True, **metadata): | ||
|
r17560 | """Create a EventfulDict trait type from a dict. | ||
|
r20308 | The default value is created by doing | ||
``eventful.EvenfulDict(default_value)``, which creates a copy of the | ||||
|
r17560 | ``default_value``. | ||
""" | ||||
if default_value is None: | ||||
|
r20308 | args = None | ||
|
r17560 | elif isinstance(default_value, dict): | ||
args = (default_value,) | ||||
elif isinstance(default_value, SequenceTypes): | ||||
args = (default_value,) | ||||
else: | ||||
raise TypeError('default value of EventfulDict was %s' % default_value) | ||||
super(EventfulDict, self).__init__(klass=eventful.EventfulDict, args=args, | ||||
allow_none=allow_none, **metadata) | ||||
class EventfulList(Instance): | ||||
"""An instance of an EventfulList.""" | ||||
def __init__(self, default_value=None, allow_none=True, **metadata): | ||||
"""Create a EventfulList trait type from a dict. | ||||
The default value is created by doing | ||||
``eventful.EvenfulList(default_value)``, which creates a copy of the | ||||
``default_value``. | ||||
""" | ||||
if default_value is None: | ||||
args = ((),) | ||||
else: | ||||
args = (default_value,) | ||||
super(EventfulList, self).__init__(klass=eventful.EventfulList, args=args, | ||||
allow_none=allow_none, **metadata) | ||||
|
r16453 | class TCPAddress(TraitType): | ||
|
r2742 | """A trait for an (ip, port) tuple. | ||
This allows for both IPv4 IP addresses as well as hostnames. | ||||
""" | ||||
default_value = ('127.0.0.1', 0) | ||||
info_text = 'an (ip, port) tuple' | ||||
def validate(self, obj, value): | ||||
if isinstance(value, tuple): | ||||
if len(value) == 2: | ||||
|
r13353 | if isinstance(value[0], py3compat.string_types) and isinstance(value[1], int): | ||
|
r2742 | port = value[1] | ||
if port >= 0 and port <= 65535: | ||||
return value | ||||
self.error(obj, value) | ||||
|
r6732 | |||
|
r16453 | class CRegExp(TraitType): | ||
|
r6743 | """A casting compiled regular expression trait. | ||
Accepts both strings and compiled regular expressions. The resulting | ||||
attribute will be a compiled regular expression.""" | ||||
|
r6732 | |||
info_text = 'a regular expression' | ||||
def validate(self, obj, value): | ||||
try: | ||||
return re.compile(value) | ||||
except: | ||||
self.error(obj, value) | ||||