Skip to content
Navigation Menu
{{ message }}
forked from ipython/ipython
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathtraitlets.py
More file actions
1531 lines (1206 loc) · 49.4 KB
/
Copy pathtraitlets.py
File metadata and controls
1531 lines (1206 loc) · 49.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# encoding: utf-8
"""
A lightweight Traits like module.
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
* A full set of trait types. Most importantly, we don't provide container
traits (list, dict, tuple) that can trigger notifications if their
contents change.
* API compatibility with enthought.traits
There are also some important difference in our design:
* enthought.traits does not validate default values. We do.
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.
Inheritance diagram:
.. inheritance-diagram:: IPython.utils.traitlets
:parts: 3
Authors:
* Brian Granger
* Enthought, Inc. Some of the code in this file comes from enthought.traits
and is licensed under the BSD license. Also, many of the ideas also come
from enthought.traits even though our implementation is very different.
"""
#-----------------------------------------------------------------------------
# Copyright (C) 2008-2011 The IPython Development Team
#
# Distributed under the terms of the BSD License. The full license is in
# the file COPYING, distributed as part of this software.
#-----------------------------------------------------------------------------
#-----------------------------------------------------------------------------
# Imports
#-----------------------------------------------------------------------------
import contextlib
import inspect
import re
import sys
import types
from types import FunctionType
try:
from types import ClassType, InstanceType
ClassTypes = (ClassType, type)
except:
ClassTypes = (type,)
from .importstring import import_item
from IPython.utils import py3compat
from IPython.utils.py3compat import iteritems
from IPython.testing.skipdoctest import skip_doctest
SequenceTypes = (list, tuple, set, frozenset)
#-----------------------------------------------------------------------------
# Basic classes
#-----------------------------------------------------------------------------
class NoDefaultSpecified ( object ): pass
NoDefaultSpecified = NoDefaultSpecified()
class Undefined ( object ): pass
Undefined = Undefined()
class TraitError(Exception):
pass
#-----------------------------------------------------------------------------
# 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').
"""
if isinstance( object, py3compat.string_types ):
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)
if (not py3compat.PY3) and the_type is InstanceType:
# Old-style class.
the_type = obj.__class__
msg = '%r %r' % (obj, the_type)
return msg
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)))
def parse_notifier_name(name):
"""Convert the name argument to a list of names.
Examples
--------
>>> parse_notifier_name('a')
['a']
>>> parse_notifier_name(['a','b'])
['a', 'b']
>>> parse_notifier_name(None)
['anytrait']
"""
if isinstance(name, str):
return [name]
elif name is None:
return ['anytrait']
elif isinstance(name, (list, tuple)):
for n in name:
assert isinstance(n, str), "names must be strings"
return name
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__()
def getmembers(object, predicate=None):
"""A safe version of inspect.getmembers that handles missing attributes.
This is useful when there are descriptor based attributes that for
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
@skip_doctest
class link(object):
"""Link traits from different objects together so they remain in sync.
Parameters
----------
obj : pairs of objects/attributes
Examples
--------
>>> c = link((obj1, 'value'), (obj2, 'value'), (obj3, 'value'))
>>> obj1.value = 5 # updates other objects as well
"""
updating = False
def __init__(self, *args):
if len(args) < 2:
raise TypeError('At least two traitlets must be provided.')
self.objects = {}
initial = getattr(args[0][0], args[0][1])
for obj,attr in args:
if getattr(obj, attr) != initial:
setattr(obj, attr, initial)
callback = self._make_closure(obj,attr)
obj.on_trait_change(callback, attr)
self.objects[(obj,attr)] = callback
@contextlib.contextmanager
def _busy_updating(self):
self.updating = True
try:
yield
finally:
self.updating = False
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):
if self.updating:
return
with self._busy_updating():
for obj,attr in self.objects.keys():
if obj is not sending_obj or attr != sending_attr:
setattr(obj, attr, new)
def unlink(self):
for key, callback in self.objects.items():
(obj,attr) = key
obj.on_trait_change(callback, attr, remove=True)
#-----------------------------------------------------------------------------
# Base TraitType for all traits
#-----------------------------------------------------------------------------
class TraitType(object):
"""A base class for all trait descriptors.
Notes
-----
Our implementation of traits is based on Python's descriptor
prototol. This class is the base class for all such descriptors. The
only magic we use is a custom metaclass for the main :class:`HasTraits`
class that does the following:
1. Sets the :attr:`name` attribute of every :class:`TraitType`
instance in the class dict to the name of the attribute.
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
accept superclasses for :class:`This` values.
"""
metadata = {}
default_value = Undefined
info_text = 'any value'
def __init__(self, default_value=NoDefaultSpecified, **metadata):
"""Create a TraitType.
"""
if default_value is not NoDefaultSpecified:
self.default_value = default_value
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
self.init()
def init(self):
pass
def get_default_value(self):
"""Create a new instance of the default value."""
return self.default_value
def instance_init(self, obj):
"""This is called by :meth:`HasTraits.__new__` to finish init'ing.
Some stages of initialization must be delayed until the parent
:class:`HasTraits` instance has been created. This method is
called in :meth:`HasTraits.__new__` after the instance has been
created.
This method trigger the creation and validation of default values
and also things like the resolution of str given class names in
:class:`Type` and :class`Instance`.
Parameters
----------
obj : :class:`HasTraits` instance
The parent :class:`HasTraits` instance that has just been
created.
"""
self.set_default_value(obj)
def set_default_value(self, obj):
"""Set the default value on a per instance basis.
This method is called by :meth:`instance_init` to create and
validate the default value. The creation and validation of
default values must be delayed until the parent :class:`HasTraits`
class has been instantiated.
"""
# 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.
obj._trait_dyn_inits[self.name] = cls.__dict__[meth_name]
def __get__(self, obj, cls=None):
"""Get the value of the trait by self.name for the instance.
Default values are instantiated when :meth:`HasTraits.__new__`
is called. Thus by the time this method gets called either the
default value or a user defined value (they called :meth:`__set__`)
is in the :class:`HasTraits` instance.
"""
if obj is None:
return self
else:
try:
value = obj._trait_values[self.name]
except KeyError:
# Check for a dynamic initializer.
if self.name in obj._trait_dyn_inits:
value = obj._trait_dyn_inits[self.name](obj)
# 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:
# HasTraits should call set_default_value to populate
# this. So this should never be reached.
raise TraitError('Unexpected error in TraitType: '
'default value not set properly')
else:
return value
def __set__(self, obj, value):
new_value = self._validate(obj, value)
old_value = self.__get__(obj)
obj._trait_values[self.name] = new_value
try:
silent = bool(old_value == new_value)
except:
# if there is an error in comparing, default to notify
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
obj._notify_trait(self.name, old_value, new_value)
def _validate(self, obj, value):
if hasattr(self, 'validate'):
return self.validate(obj, value)
elif hasattr(self, 'is_valid_for'):
valid = self.is_valid_for(value)
if valid:
return value
else:
raise TraitError('invalid value for type: %r' % value)
elif hasattr(self, 'value_for'):
return self.value_for(value)
else:
return value
def info(self):
return self.info_text
def error(self, obj, value):
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(), repr_type(value))
else:
e = "The '%s' trait must be %s, but a value of %r was specified." \
% (self.name, self.info(), repr_type(value))
raise TraitError(e)
def get_metadata(self, key):
return getattr(self, '_metadata', {}).get(key, None)
def set_metadata(self, key, value):
getattr(self, '_metadata', {})[key] = value
#-----------------------------------------------------------------------------
# The HasTraits implementation
#-----------------------------------------------------------------------------
class MetaHasTraits(type):
"""A metaclass for HasTraits.
This metaclass makes sure that any TraitType class attributes are
instantiated and sets their name attribute.
"""
def __new__(mcls, name, bases, classdict):
"""Create the HasTraits class.
This instantiates all TraitTypes in the class dict and sets their
:attr:`name` attribute.
"""
# print "MetaHasTraitlets (mcls, name): ", mcls, name
# print "MetaHasTraitlets (bases): ", bases
# print "MetaHasTraitlets (classdict): ", classdict
for k,v in iteritems(classdict):
if isinstance(v, TraitType):
v.name = k
elif inspect.isclass(v):
if issubclass(v, TraitType):
vinst = v()
vinst.name = k
classdict[k] = vinst
return super(MetaHasTraits, mcls).__new__(mcls, name, bases, classdict)
def __init__(cls, name, bases, classdict):
"""Finish initializing the HasTraits class.
This sets the :attr:`this_class` attribute of each TraitType in the
class dict to the newly created class ``cls``.
"""
for k, v in iteritems(classdict):
if isinstance(v, TraitType):
v.this_class = cls
super(MetaHasTraits, cls).__init__(name, bases, classdict)
class HasTraits(py3compat.with_metaclass(MetaHasTraits, object)):
def __new__(cls, *args, **kw):
# This is needed because in Python 2.6 object.__new__ only accepts
# the cls argument.
new_meth = super(HasTraits, cls).__new__
if new_meth is object.__new__:
inst = new_meth(cls)
else:
inst = new_meth(cls, **kw)
inst._trait_values = {}
inst._trait_notifiers = {}
inst._trait_dyn_inits = {}
# Here we tell all the TraitType instances to set their default
# values on the instance.
for key in dir(cls):
# 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:
if isinstance(value, TraitType):
value.instance_init(inst)
return inst
def __init__(self, *args, **kw):
# Allow trait values to be set using keyword arguments.
# We need to use setattr for this to trigger validation and
# notifications.
for key, value in iteritems(kw):
setattr(self, key, value)
def _notify_trait(self, name, old_value, new_value):
# First dynamic ones
callables = []
callables.extend(self._trait_notifiers.get(name,[]))
callables.extend(self._trait_notifiers.get('anytrait',[]))
# Now static ones
try:
cb = getattr(self, '_%s_changed' % name)
except:
pass
else:
callables.append(cb)
# Call them all now
for c in callables:
# Traits catches and logs errors here. I allow them to raise
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:
raise TraitError('a trait changed callback '
'must have 0-3 arguments.')
else:
raise TraitError('a trait changed callback '
'must be callable.')
def _add_notifiers(self, handler, name):
if name not in self._trait_notifiers:
nlist = []
self._trait_notifiers[name] = nlist
else:
nlist = self._trait_notifiers[name]
if handler not in nlist:
nlist.append(handler)
def _remove_notifiers(self, handler, name):
if name in self._trait_notifiers:
nlist = self._trait_notifiers[name]
try:
index = nlist.index(handler)
except ValueError:
pass
else:
del nlist[index]
def on_trait_change(self, handler, name=None, remove=False):
"""Setup a handler to be called when a trait changes.
This is used to setup dynamic notifications of trait changes.
Static handlers can be created by creating methods on a HasTraits
subclass with the naming convention '_[traitname]_changed'. Thus,
to create static handler for the trait 'a', create the method
_a_changed(self, name, old, new) (fewer arguments can be used, see
below).
Parameters
----------
handler : callable
A callable that is called when a trait changes. Its
signature can be handler(), handler(name), handler(name, new)
or handler(name, old, new).
name : list, str, None
If None, the handler will apply to all traits. If a list
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.
"""
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)
@classmethod
def class_trait_names(cls, **metadata):
"""Get a list of all the names of this class' traits.
This method is just like the :meth:`trait_names` method,
but is unbound.
"""
return cls.class_traits(**metadata).keys()
@classmethod
def class_traits(cls, **metadata):
"""Get a `dict` of all the traits of this class. The dictionary
is keyed on the name and the values are the TraitType objects.
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.
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.
"""
traits = dict([memb for memb in getmembers(cls) if
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
def trait_names(self, **metadata):
"""Get a list of all the names of this class' traits."""
return self.traits(**metadata).keys()
def traits(self, **metadata):
"""Get a `dict` of all the traits of this class. The dictionary
is keyed on the name and the values are the TraitType objects.
The TraitTypes returned don't know anything about the values
that the various HasTrait's instances are holding.
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.
"""
traits = dict([memb for memb in getmembers(self.__class__) if
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
def trait_metadata(self, traitname, key):
"""Get metadata values for trait by key."""
try:
trait = getattr(self.__class__, traitname)
except AttributeError:
raise TraitError("Class %s does not have a trait named %s" %
(self.__class__.__name__, traitname))
else:
return trait.get_metadata(key)
#-----------------------------------------------------------------------------
# Actual TraitTypes implementations/subclasses
#-----------------------------------------------------------------------------
#-----------------------------------------------------------------------------
# TraitTypes subclasses for handling classes and instances of classes
#-----------------------------------------------------------------------------
class ClassBasedTraitType(TraitType):
"""A trait with error reporting for Type, Instance and This."""
def error(self, obj, value):
kind = type(value)
if (not py3compat.PY3) and kind is InstanceType:
msg = 'class %s' % value.__class__.__name__
else:
msg = '%s (i.e. %s)' % ( str( kind )[1:-1], repr( value ) )
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)
class Type(ClassBasedTraitType):
"""A trait whose value must be a subclass of a specified class."""
def __init__ (self, default_value=None, klass=None, allow_none=True, **metadata ):
"""Construct a Type trait
A Type trait specifies that its values must be subclasses of
a particular class.
If only ``default_value`` is given, it is used for the ``klass`` as
well.
Parameters
----------
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'.
The string is resolved into real class, when the parent
:class:`HasTraits` class is instantiated.
klass : class, str, None
Values of this trait must be a subclass of klass. The klass
may be specified in a string like: 'foo.bar.MyClass'.
The string is resolved into real class, when the parent
:class:`HasTraits` class is instantiated.
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
if not (inspect.isclass(klass) or isinstance(klass, py3compat.string_types)):
raise TraitError("A Type trait must specify a class.")
self.klass = klass
self._allow_none = allow_none
super(Type, self).__init__(default_value, **metadata)
def validate(self, obj, value):
"""Validates that the value is a valid object instance."""
try:
if issubclass(value, self.klass):
return value
except:
if (value is None) and (self._allow_none):
return value
self.error(obj, value)
def info(self):
""" Returns a description of the trait."""
if isinstance(self.klass, py3compat.string_types):
klass = self.klass
else:
klass = self.klass.__name__
result = 'a subclass of ' + klass
if self._allow_none:
return result + ' or None'
return result
def instance_init(self, obj):
self._resolve_classes()
super(Type, self).instance_init(obj)
def _resolve_classes(self):
if isinstance(self.klass, py3compat.string_types):
self.klass = import_item(self.klass)
if isinstance(self.default_value, py3compat.string_types):
self.default_value = import_item(self.default_value)
def get_default_value(self):
return self.default_value
class DefaultValueGenerator(object):
"""A class for generating new default value instances."""
def __init__(self, *args, **kw):
self.args = args
self.kw = kw
def generate(self, klass):
return klass(*self.args, **self.kw)
class Instance(ClassBasedTraitType):
"""A trait whose value must be an instance of a specified class.
The value can also be an instance of a subclass of the specified class.
"""
def __init__(self, klass=None, args=None, kw=None,
allow_none=True, **metadata ):
"""Construct an Instance trait.
This trait allows values that are instances of a particular
class or its sublclasses. Our implementation is quite different
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.
Parameters
----------
klass : class, str
The class that forms the basis for the trait. Class names
can also be specified as strings, like 'foo.bar.Bar'.
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.
Notes
-----
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
created as ``klass(*args, **kw)``. If either ``args`` or ``kw`` is
not (but not both), None is replace by ``()`` or ``{}``.
"""
self._allow_none = allow_none
if (klass is None) or (not (inspect.isclass(klass) or isinstance(klass, py3compat.string_types))):
raise TraitError('The klass argument must be a class'
' you gave: %r' % klass)
self.klass = klass
# self.klass is a class, so handle default_value
if args is None and kw is None:
default_value = None
else:
if args is None:
# kw is not None
args = ()
elif kw is None:
# args is not None
kw = {}
if not isinstance(kw, dict):
raise TraitError("The 'kw' argument must be a dict or None.")
if not isinstance(args, tuple):
raise TraitError("The 'args' argument must be a tuple or None.")
default_value = DefaultValueGenerator(*args, **kw)
super(Instance, self).__init__(default_value, **metadata)
def validate(self, obj, value):
if value is None:
if self._allow_none:
return value
self.error(obj, value)
if isinstance(value, self.klass):
return value
else:
self.error(obj, value)
def info(self):
if isinstance(self.klass, py3compat.string_types):
klass = self.klass
else:
klass = self.klass.__name__
result = class_of(klass)
if self._allow_none:
return result + ' or None'
return result
def instance_init(self, obj):
self._resolve_classes()
super(Instance, self).instance_init(obj)
def _resolve_classes(self):
if isinstance(self.klass, py3compat.string_types):
self.klass = import_item(self.klass)
def get_default_value(self):
"""Instantiate a default value instance.
This is called when the containing HasTraits classes'
:meth:`__new__` method is called to ensure that a unique instance
is created for each HasTraits instance.
"""
dv = self.default_value
if isinstance(dv, DefaultValueGenerator):
return dv.generate(self.klass)
else:
return dv
class This(ClassBasedTraitType):
"""A trait for instances of the class containing this trait.
Because how how and when class bodies are executed, the ``This``
trait can only have a default value of None. This, and because we
always validate default values, ``allow_none`` is *always* true.
"""
info_text = 'an instance of the same type as the receiver or None'
def __init__(self, **metadata):
super(This, self).__init__(None, **metadata)
def validate(self, obj, value):
# What if value is a superclass of obj.__class__? This is
# complicated if it was the superclass that defined the This
# trait.
if isinstance(value, self.this_class) or (value is None):
return value
else:
self.error(obj, value)
#-----------------------------------------------------------------------------
# Basic TraitTypes implementations/subclasses
#-----------------------------------------------------------------------------
class Any(TraitType):
default_value = None
info_text = 'any value'
class Int(TraitType):
"""An int trait."""
default_value = 0
info_text = 'an int'
def validate(self, obj, value):
if isinstance(value, int):
return value
self.error(obj, value)
class CInt(Int):
"""A casting version of the int trait."""
def validate(self, obj, value):
try:
return int(value)
except:
self.error(obj, value)
if py3compat.PY3:
Long, CLong = Int, CInt
Integer = Int
else:
class Long(TraitType):
"""A long integer trait."""
default_value = 0
info_text = 'a long'
def validate(self, obj, value):
if isinstance(value, long):
return value
if isinstance(value, int):
return long(value)
self.error(obj, value)
class CLong(Long):
"""A casting version of the long integer trait."""
def validate(self, obj, value):
try:
return long(value)
except:
self.error(obj, value)
class Integer(TraitType):
"""An integer trait.
Longs that are unnecessary (<= sys.maxint) are cast to ints."""
You can’t perform that action at this time.