/
parameterized.py
2387 lines (1914 loc) · 87.2 KB
/
parameterized.py
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
"""
Generic support for objects with full-featured Parameters and
messaging.
"""
import copy
import re
import sys
import inspect
import random
from collections import namedtuple
from operator import itemgetter,attrgetter
from types import FunctionType
from functools import partial, wraps, reduce
import logging
from contextlib import contextmanager
from logging import DEBUG, INFO, WARNING, ERROR, CRITICAL
try:
# In case the optional ipython module is unavailable
from .ipython import ParamPager
param_pager = ParamPager(metaclass=True) # Generates param description
except:
param_pager = None
VERBOSE = INFO - 1
logging.addLevelName(VERBOSE, "VERBOSE")
# Logger instance to use for param; if "logger" is set to None, the root logger
# will be used.
logger = None
def get_logger():
if logger is None:
# If it was not configured before, do default initialization
if not logging.getLogger().handlers:
logging.basicConfig(level=INFO)
return logging.getLogger()
else:
return logger
# Indicates whether warnings should be raised as errors, stopping
# processing.
warnings_as_exceptions = False
docstring_signature = True # Add signature to class docstrings
docstring_describe_params = True # Add parameter description to class
# docstrings (requires ipython module)
object_count = 0
warning_count = 0
@contextmanager
def logging_level(level):
"""
Temporarily modify param's logging level.
"""
level = level.upper()
levels = [DEBUG, INFO, WARNING, ERROR, CRITICAL, VERBOSE]
level_names = ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL', 'VERBOSE']
if level not in level_names:
raise Exception("Level %r not in %r" % (level, levels))
param_logger = get_logger()
logging_level = param_logger.getEffectiveLevel()
param_logger.setLevel(levels[level_names.index(level)])
try:
yield None
finally:
param_logger.setLevel(logging_level)
def classlist(class_):
"""
Return a list of the class hierarchy above (and including) the given class.
Same as inspect.getmro(class_)[::-1]
"""
return inspect.getmro(class_)[::-1]
def descendents(class_):
"""
Return a list of the class hierarchy below (and including) the given class.
The list is ordered from least- to most-specific. Can be useful for
printing the contents of an entire class hierarchy.
"""
assert isinstance(class_,type)
q = [class_]
out = []
while len(q):
x = q.pop(0)
out.insert(0,x)
for b in x.__subclasses__():
if b not in q and b not in out:
q.append(b)
return out[::-1]
def get_all_slots(class_):
"""
Return a list of slot names for slots defined in class_ and its
superclasses.
"""
# A subclass's __slots__ attribute does not contain slots defined
# in its superclass (the superclass' __slots__ end up as
# attributes of the subclass).
all_slots = []
parent_param_classes = [c for c in classlist(class_)[1::]]
for c in parent_param_classes:
if hasattr(c,'__slots__'):
all_slots+=c.__slots__
return all_slots
def get_occupied_slots(instance):
"""
Return a list of slots for which values have been set.
(While a slot might be defined, if a value for that slot hasn't
been set, then it's an AttributeError to request the slot's
value.)
"""
return [slot for slot in get_all_slots(type(instance))
if hasattr(instance,slot)]
def all_equal(arg1,arg2):
"""
Return a single boolean for arg1==arg2, even for numpy arrays
using element-wise comparison.
Uses all(arg1==arg2) for sequences, and arg1==arg2 otherwise.
If both objects have an '_infinitely_iterable' attribute, they are
not be zipped together and are compared directly instead.
"""
if all(hasattr(el, '_infinitely_iterable') for el in [arg1,arg2]):
return arg1==arg2
try:
return all(a1 == a2 for a1, a2 in zip(arg1, arg2))
except TypeError:
return arg1==arg2
# For Python 2 compatibility.
#
# The syntax to use a metaclass changed incompatibly between 2 and
# 3. The add_metaclass() class decorator below creates a class using a
# specified metaclass in a way that works on both 2 and 3. For 3, can
# remove this decorator and specify metaclasses in a simpler way
# (https://docs.python.org/3/reference/datamodel.html#customizing-class-creation)
#
# Code from six (https://bitbucket.org/gutworth/six; version 1.4.1).
def add_metaclass(metaclass):
"""Class decorator for creating a class with a metaclass."""
def wrapper(cls):
orig_vars = cls.__dict__.copy()
orig_vars.pop('__dict__', None)
orig_vars.pop('__weakref__', None)
for slots_var in orig_vars.get('__slots__', ()):
orig_vars.pop(slots_var)
return metaclass(cls.__name__, cls.__bases__, orig_vars)
return wrapper
class bothmethod(object): # pylint: disable-msg=R0903
"""
'optional @classmethod'
A decorator that allows a method to receive either the class
object (if called on the class) or the instance object
(if called on the instance) as its first argument.
Code (but not documentation) copied from:
http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/523033.
"""
# pylint: disable-msg=R0903
def __init__(self, func):
self.func = func
# i.e. this is also a non-data descriptor
def __get__(self, obj, type_=None):
if obj is None:
return wraps(self.func)(partial(self.func, type_))
else:
return wraps(self.func)(partial(self.func, obj))
def _getattrr(obj, attr, *args):
def _getattr(obj, attr):
return getattr(obj, attr, *args)
return reduce(_getattr, [obj] + attr.split('.'))
# (thought I was going to have a few decorators following this pattern)
def accept_arguments(f):
@wraps(f)
def _f(*args, **kwargs):
return lambda actual_f: f(actual_f, *args, **kwargs)
return _f
@accept_arguments
def depends(func, *dependencies, **kw):
# python3 would allow kw-only args
# (i.e. "func,*dependencies,watch=False" rather than **kw and the check below)
watch = kw.pop("watch",False)
assert len(kw)==0, "@depends accepts only 'watch' kw"
# TODO: rename dinfo
_dinfo = {'dependencies': dependencies,
'watch': watch}
@wraps(func)
def _depends(*args,**kw):
return func(*args,**kw)
# storing here risks it being tricky to find if other libraries
# mess around with methods
_depends._dinfo = _dinfo
return _depends
def _params_depended_on(minfo):
params = []
dinfo = getattr(minfo.method,"_dinfo", {})
for d in dinfo.get('dependencies',list(minfo.cls.param.params())):
things = (minfo.inst or minfo.cls).param._spec_to_obj(d)
for thing in things:
if isinstance(thing,PInfo):
params.append(thing)
else:
params += _params_depended_on(thing)
return params
def _m_caller(self,n):
return lambda change: getattr(self,n)()
PInfo = namedtuple("PInfo","inst cls name pobj what")
MInfo = namedtuple("MInfo","inst cls name method")
Change = namedtuple("Change","what name obj cls old new")
Subscriber = namedtuple("Subscriber","fn mode")
class ParameterMetaclass(type):
"""
Metaclass allowing control over creation of Parameter classes.
"""
def __new__(mcs,classname,bases,classdict):
# store the class's docstring in __classdoc
if '__doc__' in classdict:
classdict['__classdoc']=classdict['__doc__']
# when asking for help on Parameter *object*, return the doc
# slot
classdict['__doc__']=property(attrgetter('doc'))
# To get the benefit of slots, subclasses must themselves define
# __slots__, whether or not they define attributes not present in
# the base Parameter class. That's because a subclass will have
# a __dict__ unless it also defines __slots__.
if '__slots__' not in classdict:
classdict['__slots__']=[]
return type.__new__(mcs,classname,bases,classdict)
def __getattribute__(mcs,name):
if name=='__doc__':
# when asking for help on Parameter *class*, return the
# stored class docstring
return type.__getattribute__(mcs,'__classdoc')
else:
return type.__getattribute__(mcs,name)
# CEBALERT: we break some aspects of slot handling for Parameter and
# Parameterized. The __new__ methods in the metaclasses for those two
# classes omit to handle the case where __dict__ is passed in
# __slots__ (and they possibly omit other things too). Additionally,
# various bits of code in the Parameterized class assumes that all
# Parameterized instances have a __dict__, but I'm not sure that's
# guaranteed to be true (although it's true at the moment).
# CB: we could maybe reduce the complexity by doing something to allow
# a parameter to discover things about itself when created (would also
# allow things like checking a Parameter is owned by a
# Parameterized). I have some vague ideas about what to do.
@add_metaclass(ParameterMetaclass)
class Parameter(object):
"""
An attribute descriptor for declaring parameters.
Parameters are a special kind of class attribute. Setting a
Parameterized class attribute to be a Parameter instance causes
that attribute of the class (and the class's instances) to be
treated as a Parameter. This allows special behavior, including
dynamically generated parameter values, documentation strings,
constant and read-only parameters, and type or range checking at
assignment time.
For example, suppose someone wants to define two new kinds of
objects Foo and Bar, such that Bar has a parameter delta, Foo is a
subclass of Bar, and Foo has parameters alpha, sigma, and gamma
(and delta inherited from Bar). She would begin her class
definitions with something like this:
class Bar(Parameterized):
delta = Parameter(default=0.6, doc='The difference between steps.')
...
class Foo(Bar):
alpha = Parameter(default=0.1, doc='The starting value.')
sigma = Parameter(default=0.5, doc='The standard deviation.',
constant=True)
gamma = Parameter(default=1.0, doc='The ending value.')
...
Class Foo would then have four parameters, with delta defaulting
to 0.6.
Parameters have several advantages over plain attributes:
1. Parameters can be set automatically when an instance is
constructed: The default constructor for Foo (and Bar) will
accept arbitrary keyword arguments, each of which can be used
to specify the value of a Parameter of Foo (or any of Foo's
superclasses). E.g., if a script does this:
myfoo = Foo(alpha=0.5)
myfoo.alpha will return 0.5, without the Foo constructor
needing special code to set alpha.
If Foo implements its own constructor, keyword arguments will
still be accepted if the constructor accepts a dictionary of
keyword arguments (as in ``def __init__(self,**params):``), and
then each class calls its superclass (as in
``super(Foo,self).__init__(**params)``) so that the
Parameterized constructor will process the keywords.
2. A Parameterized class need specify only the attributes of a
Parameter whose values differ from those declared in
superclasses; the other values will be inherited. E.g. if Foo
declares
delta = Parameter(default=0.2)
the default value of 0.2 will override the 0.6 inherited from
Bar, but the doc will be inherited from Bar.
3. The Parameter descriptor class can be subclassed to provide
more complex behavior, allowing special types of parameters
that, for example, require their values to be numbers in
certain ranges, generate their values dynamically from a random
distribution, or read their values from a file or other
external source.
4. The attributes associated with Parameters provide enough
information for automatically generating property sheets in
graphical user interfaces, allowing Parameterized instances to
be edited by users.
Note that Parameters can only be used when set as class attributes
of Parameterized classes. Parameters used as standalone objects,
or as class attributes of non-Parameterized classes, will not have
the behavior described here.
"""
# Because they implement __get__ and __set__, Parameters are known
# as 'descriptors' in Python; see "Implementing Descriptors" and
# "Invoking Descriptors" in the 'Customizing attribute access'
# section of the Python reference manual:
# http://docs.python.org/ref/attribute-access.html
#
# Overview of Parameters for programmers
# ======================================
#
# Consider the following code:
#
#
# class A(Parameterized):
# p = Parameter(default=1)
#
# a1 = A()
# a2 = A()
#
#
# * a1 and a2 share one Parameter object (A.__dict__['p']).
#
# * The default (class) value of p is stored in this Parameter
# object (A.__dict__['p'].default).
#
# * If the value of p is set on a1 (e.g. a1.p=2), a1's value of p
# is stored in a1 itself (a1.__dict__['_p_param_value'])
#
# * When a1.p is requested, a1.__dict__['_p_param_value'] is
# returned. When a2.p is requested, '_p_param_value' is not
# found in a2.__dict__, so A.__dict__['p'].default (i.e. A.p) is
# returned instead.
#
#
# Be careful when referring to the 'name' of a Parameter:
#
# * A Parameterized class has a name for the attribute which is
# being represented by the Parameter ('p' in the example above);
# in the code, this is called the 'attrib_name'.
#
# * When a Parameterized instance has its own local value for a
# parameter, it is stored as '_X_param_value' (where X is the
# attrib_name for the Parameter); in the code, this is called
# the internal_name.
# So that the extra features of Parameters do not require a lot of
# overhead, Parameters are implemented using __slots__ (see
# http://www.python.org/doc/2.4/ref/slots.html). Instead of having
# a full Python dictionary associated with each Parameter instance,
# Parameter instances have an enumerated list (named __slots__) of
# attributes, and reserve just enough space to store these
# attributes. Using __slots__ requires special support for
# operations to copy and restore Parameters (e.g. for Python
# persistent storage pickling); see __getstate__ and __setstate__.
__slots__ = ['_attrib_name','_internal_name','default','doc',
'precedence','instantiate','constant','readonly',
'pickle_default_value','allow_None',
'subscribers','_owner']
# Note: When initially created, a Parameter does not know which
# Parameterized class owns it, nor does it know its names
# (attribute name, internal name). Once the owning Parmaeterized
# class is created, _owner, _attrib_name, and _internal name are
# set.
# TODO regarding _attrib_name, _owner: what if someone re-uses
# a parameter object across different classes? we should raise
# an error if attrib name,owner already set
def __init__(self,default=None,doc=None,precedence=None, # pylint: disable-msg=R0913
instantiate=False,constant=False,readonly=False,
pickle_default_value=True, allow_None=False):
"""
Initialize a new Parameter object: store the supplied attributes.
default: the owning class's value for the attribute
represented by this Parameter.
precedence is a value, usually in the range 0.0 to 1.0, that
allows the order of Parameters in a class to be defined (for
e.g. in GUI menus). A negative precedence indicates a
parameter that should be hidden in e.g. GUI menus.
default, doc, and precedence default to None. This is to allow
inheritance of Parameter slots (attributes) from the owning-class'
class hierarchy (see ParameterizedMetaclass).
In rare cases where the default value should not be pickled,
set pickle_default_value=False (e.g. for file search paths).
"""
self._attrib_name = None
self._internal_name = None
self._owner = None
self.precedence = precedence
self.default = default
self.doc = doc
self.constant = constant or readonly # readonly => constant
self.readonly = readonly
self._set_instantiate(instantiate)
self.pickle_default_value = pickle_default_value
self.allow_None = (default is None or allow_None)
self.subscribers = {}
def _set_instantiate(self,instantiate):
"""Constant parameters must be instantiated."""
# CB: instantiate doesn't actually matter for read-only
# parameters, since they can't be set even on a class. But
# this avoids needless instantiation.
if self.readonly:
self.instantiate = False
else:
self.instantiate = instantiate or self.constant # pylint: disable-msg=W0201
# TODO: quick trick to allow subscription to the setting of
# parameter metadata. ParameterParameter?
# Note that unlike with parameter value setting, there's no access
# to the Parameterized instance, so no per-instance subscription.
def __setattr__(self,attribute,value):
implemented = (attribute!="default" and hasattr(self,'subscribers') and attribute in self.subscribers)
try:
old = getattr(self,attribute) if implemented else NotImplemented
except AttributeError as e:
if attribute in self.__slots__:
# If Parameter slot is defined but an AttributeError was raised
# we are in __setstate__ and subscribers should not be triggered
old = NotImplemented
else:
raise e
super(Parameter, self).__setattr__(attribute, value)
if old is not NotImplemented:
change = Change(what=attribute,name=self._attrib_name,obj=None,cls=self._owner,old=old,new=value)
for subscriber in self.subscribers[attribute]:
self._owner.param._call_subscriber(subscriber, change)
def __get__(self,obj,objtype): # pylint: disable-msg=W0613
"""
Return the value for this Parameter.
If called for a Parameterized class, produce that
class's value (i.e. this Parameter object's 'default'
attribute).
If called for a Parameterized instance, produce that
instance's value, if one has been set - otherwise produce the
class's value (default).
"""
# NB: obj can be None (when __get__ called for a
# Parameterized class); objtype is never None
if obj is None:
result = self.default
else:
result = obj.__dict__.get(self._internal_name,self.default)
return result
def __set__(self,obj,val):
"""
Set the value for this Parameter.
If called for a Parameterized class, set that class's
value (i.e. set this Parameter object's 'default' attribute).
If called for a Parameterized instance, set the value of
this Parameter on that instance (i.e. in the instance's
__dict__, under the parameter's internal_name).
If the Parameter's constant attribute is True, only allows
the value to be set for a Parameterized class or on
uninitialized Parameterized instances.
If the Parameter's readonly attribute is True, only allows the
value to be specified in the Parameter declaration inside the
Parameterized source code. A read-only parameter also
cannot be set on a Parameterized class.
Note that until we support some form of read-only
object, it is still possible to change the attributes of the
object stored in a constant or read-only Parameter (e.g. the
left bound of a BoundingBox).
"""
# TODO: simplify this method!
_old = NotImplemented
# NB: obj can be None (when __set__ called for a
# Parameterized class)
if self.constant or self.readonly:
if self.readonly:
raise TypeError("Read-only parameter '%s' cannot be modified"%self._attrib_name)
elif obj is None: #not obj
_old = self.default
self.default = val
elif not obj.initialized:
_old = obj.__dict__.get(self._internal_name,self.default)
obj.__dict__[self._internal_name] = val
else:
raise TypeError("Constant parameter '%s' cannot be modified"%self._attrib_name)
else:
if obj is None:
_old = self.default
self.default = val
else:
_old = obj.__dict__.get(self._internal_name,self.default)
obj.__dict__[self._internal_name] = val
if obj is None:
subscribers = self.subscribers.get("value",[])
else:
subscribers = getattr(obj,"_param_subscribers",{}).get(self._attrib_name,{}).get('value',self.subscribers.get("value",[]))
change = Change(what='value',name=self._attrib_name,obj=obj,cls=self._owner,old=_old,new=val)
for s in subscribers:
self._owner.param._call_subscriber(s, change)
def __delete__(self,obj):
raise TypeError("Cannot delete '%s': Parameters deletion not allowed."%self._attrib_name)
def _set_names(self,attrib_name):
self._attrib_name = attrib_name
self._internal_name = "_%s_param_value"%attrib_name
def __getstate__(self):
"""
All Parameters have slots, not a dict, so we have to support
pickle and deepcopy ourselves.
"""
state = {}
for slot in get_occupied_slots(self):
state[slot] = getattr(self,slot)
return state
def __setstate__(self,state):
# set values of __slots__ (instead of in non-existent __dict__)
for (k,v) in state.items():
setattr(self,k,v)
# Define one particular type of Parameter that is used in this file
class String(Parameter):
"""
A String Parameter, with a default value and optional regular expression (regex) matching.
Example of using a regex to implement IPv4 address matching::
class IPAddress(String):
'''IPv4 address as a string (dotted decimal notation)'''
def __init__(self, default="0.0.0.0", allow_None=False, **kwargs):
ip_regex = '^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$'
super(IPAddress, self).__init__(default=default, regex=ip_regex, **kwargs)
"""
__slots__ = ['regex']
basestring = basestring if sys.version_info[0]==2 else str # noqa: it is defined
def __init__(self, default="", regex=None, allow_None=False, **kwargs):
super(String, self).__init__(default=default, allow_None=allow_None, **kwargs)
self.regex = regex
self.allow_None = (default is None or allow_None)
self._check_value(default)
def _check_value(self,val):
if self.allow_None and val is None:
return
if not isinstance(val, self.basestring):
raise ValueError("String '%s' only takes a string value."%self._attrib_name)
if self.regex is not None and re.match(self.regex, val) is None:
raise ValueError("String '%s': '%s' does not match regex '%s'."%(self._attrib_name,val,self.regex))
def __set__(self,obj,val):
self._check_value(val)
super(String,self).__set__(obj,val)
class shared_parameters(object):
"""
Context manager to share parameter instances when creating
multiple Parameterized objects of the same type. Parameter default
values are instantiated once and cached to be reused when another
Parameterized object of the same type is instantiated.
Can be useful to easily modify large collections of Parameterized
objects at once and can provide a significant speedup.
"""
_share = False
_shared_cache = {}
def __enter__(self):
shared_parameters._share = True
def __exit__(self, exc_type, exc_val, exc_tb):
shared_parameters._share = False
shared_parameters._shared_cache = {}
def as_uninitialized(fn):
"""
Decorator: call fn with the parameterized_instance's
initialization flag set to False, then revert the flag.
(Used to decorate Parameterized methods that must alter
a constant Parameter.)
"""
@wraps(fn)
def override_initialization(self_,*args,**kw):
parameterized_instance = self_.self
original_initialized=parameterized_instance.initialized
parameterized_instance.initialized=False
fn(parameterized_instance,*args,**kw)
parameterized_instance.initialized=original_initialized
return override_initialization
class Parameters(object):
"""Object that holds the namespace and implementation of Parameterized
methods as well as any state that is not in __slots__ or the
Parameters themselves.
Exists at both the metaclass level (instantiated by the metaclass)
and at the instance level. Can contain state specific to either the
class or the instance as necessary.
"""
_disable_stubs = None # Flag used to disable stubs in the API1 tests
# None for no action, True to raise and False to warn.
def __init__(self_, cls, self=None):
"""
cls is the Parameterized class which is always set.
self is the instance if set.
"""
self_.cls = cls
self_.self = self
@property
def self_or_cls(self_):
return self_.cls if self_.self is None else self_.self
@as_uninitialized
def _set_name(self_, name):
self = self_.param.self
self.name=name
@as_uninitialized
def _generate_name(self_):
self = self_.param.self
self.param._set_name('%s%05d' % (self.__class__.__name__ ,object_count))
@as_uninitialized
def _setup_params(self_,**params):
"""
Initialize default and keyword parameter values.
First, ensures that all Parameters with 'instantiate=True'
(typically used for mutable Parameters) are copied directly
into each object, to ensure that there is an independent copy
(to avoid suprising aliasing errors). Then sets each of the
keyword arguments, warning when any of them are not defined as
parameters.
Constant Parameters can be set during calls to this method.
"""
self = self_.param.self
## Deepcopy all 'instantiate=True' parameters
# (build a set of names first to avoid redundantly instantiating
# a later-overridden parent class's parameter)
params_to_instantiate = {}
for class_ in classlist(type(self)):
if not issubclass(class_, Parameterized):
continue
for (k,v) in class_.__dict__.items():
# (avoid replacing name with the default of None)
if isinstance(v,Parameter) and v.instantiate and k!="name":
params_to_instantiate[k]=v
for p in params_to_instantiate.values():
self.param._instantiate_param(p)
## keyword arg setting
for name,val in params.items():
desc = self.__class__.get_param_descriptor(name)[0] # pylint: disable-msg=E1101
if not desc:
self.param.warning("Setting non-parameter attribute %s=%s using a mechanism intended only for parameters",name,val)
# i.e. if not desc it's setting an attribute in __dict__, not a Parameter
setattr(self,name,val)
@classmethod
def deprecate(cls, fn):
"""
Decorator to issue warnings for API moving onto the param
namespace and to add a docstring directing people to the
appropriate method.
"""
def inner(*args, **kwargs):
info = (args[0].__class__.__name__, fn.__name__)
if cls._disable_stubs:
raise AssertionError('Stubs supporting old API disabled')
elif cls._disable_stubs is None:
pass
elif cls._disable_stubs is False:
get_logger().log(WARNING,
'%s: Use method %r via param namespace ' % info)
return fn(*args, **kwargs)
inner.__doc__= "Inspect .param.%s method for the full docstring" % fn.__name__
return inner
@classmethod
def _changed(cls, change):
"""
Predicate that determines whether a Change object has actually
changed such that old!=new.
"""
try: # To be improved by adding better machinery to test equality for complex types
return (change.old != change.new)
except:
return True
@classmethod
def _call_subscriber(cls, subscriber, change):
"""
Invoke the given the subscriber appropriately given a Change object.
"""
if not cls._changed(change):
return
if subscriber.mode == 'args':
subscriber.fn(change)
else:
subscriber.fn(**{change.name: change.new})
# CEBALERT: this is a bit ugly
def _instantiate_param(self_,param_obj,dict_=None,key=None):
# deepcopy param_obj.default into self.__dict__ (or dict_ if supplied)
# under the parameter's _internal_name (or key if supplied)
self = self_.self
dict_ = dict_ or self.__dict__
key = key or param_obj._internal_name
param_key = (str(type(self)), param_obj._attrib_name)
if shared_parameters._share:
if param_key in shared_parameters._shared_cache:
new_object = shared_parameters._shared_cache[param_key]
else:
new_object = copy.deepcopy(param_obj.default)
shared_parameters._shared_cache[param_key] = new_object
else:
new_object = copy.deepcopy(param_obj.default)
dict_[key]=new_object
if isinstance(new_object,Parameterized):
global object_count
object_count+=1
# CB: writes over name given to the original object;
# should it instead keep the same name?
new_object.param._generate_name()
# Classmethods
def print_param_defaults(self_):
"""Print the default values of all cls's Parameters."""
cls = self_.cls
for key,val in cls.__dict__.items():
if isinstance(val,Parameter):
print(cls.__name__+'.'+key+ '='+ repr(val.default))
def set_default(self_,param_name,value):
"""
Set the default value of param_name.
Equivalent to setting param_name on the class.
"""
cls = self_.cls
setattr(cls,param_name,value)
def _add_parameter(self_, param_name,param_obj):
"""
Add a new Parameter object into this object's class.
Supposed to result in a Parameter equivalent to one declared
in the class's source code.
"""
# CEBALERT: can't we just do
# setattr(cls,param_name,param_obj)? The metaclass's
# __setattr__ is actually written to handle that. (Would also
# need to do something about the params() cache. That cache
# is a pain, but it definitely improved the startup time; it
# would be worthwhile making sure no method except for one
# "add_param()" method has to deal with it (plus any future
# remove_param() method.)
cls = self_.cls
type.__setattr__(cls,param_name,param_obj)
ParameterizedMetaclass._initialize_parameter(cls,param_name,param_obj)
# delete cached params()
try:
delattr(cls,'_%s__params'%cls.__name__)
except AttributeError:
pass
def params(self_, parameter_name=None):
"""
Return the Parameters of this class as the
dictionary {name: parameter_object}
Includes Parameters from this class and its
superclasses.
"""
cls = self_.cls
# CB: we cache the parameters because this method is called often,
# and parameters are rarely added (and cannot be deleted)
try:
pdict=getattr(cls,'_%s__params'%cls.__name__)
except AttributeError:
paramdict = {}
for class_ in classlist(cls):
for name,val in class_.__dict__.items():
if isinstance(val,Parameter):
paramdict[name] = val
# We only want the cache to be visible to the cls on which
# params() is called, so we mangle the name ourselves at
# runtime (if we were to mangle it now, it would be
# _Parameterized.__params for all classes).
setattr(cls,'_%s__params'%cls.__name__,paramdict)
pdict= paramdict
if parameter_name is None:
return pdict
else:
return pdict[parameter_name]
# Bothmethods
def set_param(self_, *args,**kwargs):
"""
For each param=value keyword argument, sets the corresponding
parameter of this object or class to the given value.
For backwards compatibility, also accepts
set_param("param",value) for a single parameter value using
positional arguments, but the keyword interface is preferred
because it is more compact and can set multiple values.
"""
self_or_cls = self_.self_or_cls
if args:
if len(args)==2 and not args[0] in kwargs and not kwargs:
kwargs[args[0]]=args[1]
else:
raise ValueError("Invalid positional arguments for %s.set_param" %
(self_or_cls.name))
for (k,v) in kwargs.items():
if k not in self_or_cls.param.params():
raise ValueError("'%s' is not a parameter of %s"%(k,self_or_cls.name))
setattr(self_or_cls,k,v)
def set_dynamic_time_fn(self_,time_fn,sublistattr=None):
"""
Set time_fn for all Dynamic Parameters of this class or
instance object that are currently being dynamically
generated.
Additionally, sets _Dynamic_time_fn=time_fn on this class or
instance object, so that any future changes to Dynamic
Parmeters can inherit time_fn (e.g. if a Number is changed
from a float to a number generator, the number generator will
inherit time_fn).
If specified, sublistattr is the name of an attribute of this
class or instance that contains an iterable collection of
subobjects on which set_dynamic_time_fn should be called. If
the attribute sublistattr is present on any of the subobjects,
set_dynamic_time_fn() will be called for those, too.
"""
self_or_cls = self_.self_or_cls
self_or_cls._Dynamic_time_fn = time_fn
if isinstance(self_or_cls,type):
a = (None,self_or_cls)
else:
a = (self_or_cls,)
for n,p in self_or_cls.param.params().items():
if hasattr(p,'_value_is_dynamic'):
if p._value_is_dynamic(*a):
g = self_or_cls.param.get_value_generator(n)
g._Dynamic_time_fn = time_fn
if sublistattr:
try:
sublist = getattr(self_or_cls,sublistattr)
except AttributeError:
sublist = []
for obj in sublist:
obj.param.set_dynamic_time_fn(time_fn,sublistattr)
def get_param_values(self_,onlychanged=False):
"""
Return a list of name,value pairs for all Parameters of this