LSSTApplications  10.0-2-g4f67435,11.0.rc2+1,11.0.rc2+12,11.0.rc2+3,11.0.rc2+4,11.0.rc2+5,11.0.rc2+6,11.0.rc2+7,11.0.rc2+8
LSSTDataManagementBasePackage
dictField.py
Go to the documentation of this file.
1 #
2 # LSST Data Management System
3 # Copyright 2008, 2009, 2010 LSST Corporation.
4 #
5 # This product includes software developed by the
6 # LSST Project (http://www.lsst.org/).
7 #
8 # This program is free software: you can redistribute it and/or modify
9 # it under the terms of the GNU General Public License as published by
10 # the Free Software Foundation, either version 3 of the License, or
11 # (at your option) any later version.
12 #
13 # This program is distributed in the hope that it will be useful,
14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 # GNU General Public License for more details.
17 #
18 # You should have received a copy of the LSST License Statement and
19 # the GNU General Public License along with this program. If not,
20 # see <http://www.lsstcorp.org/LegalNotices/>.
21 #
22 import traceback
23 import collections
24 
25 from .config import Field, FieldValidationError, _typeStr, _autocast, _joinNamePath
26 from .comparison import getComparisonName, compareScalars
27 
28 __all__=["DictField"]
29 
30 class Dict(collections.MutableMapping):
31  """
32  Config-Internal mapping container
33  Emulates a dict, but adds validation and provenance.
34  """
35 
36  def __init__(self, config, field, value, at, label, setHistory=True):
37  self._field = field
38  self._config = config
39  self._dict = {}
40  self._history = self._config._history.setdefault(self._field.name, [])
41  self.__doc__=field.doc
42  if value is not None:
43  try:
44  for k in value:
45  #do not set history per-item
46  self.__setitem__(k, value[k], at=at, label=label, setHistory=False)
47  except TypeError:
48  msg = "Value %s is of incorrect type %s. Mapping type expected."%\
49  (value, _typeStr(value))
50  raise FieldValidationError(self._field, self._config, msg)
51  if setHistory:
52  self._history.append((dict(self._dict), at, label))
53 
54 
55  """
56  Read-only history
57  """
58  history = property(lambda x: x._history)
59 
60  def __getitem__(self, k): return self._dict[k]
61 
62  def __len__(self): return len(self._dict)
63 
64  def __iter__(self): return iter(self._dict)
65 
66  def __contains__(self, k): return k in self._dict
67 
68  def __setitem__(self, k, x, at=None, label="setitem", setHistory=True):
69  if self._config._frozen:
70  msg = "Cannot modify a frozen Config. "\
71  "Attempting to set item at key %r to value %s"%(k, x)
72  raise FieldValidationError(self._field, self._config, msg)
73 
74  #validate keytype
75  k = _autocast(k, self._field.keytype)
76  if type(k) != self._field.keytype:
77  msg = "Key %r is of type %s, expected type %s"%\
78  (k, _typeStr(k), _typeStr(self._field.keytype))
79  raise FieldValidationError(self._field, self._config, msg)
80 
81  #validate itemtype
82  x = _autocast(x, self._field.itemtype)
83  if self._field.itemtype is None:
84  if type(x) not in self._field.supportedTypes and x is not None:
85  msg ="Value %s at key %r is of invalid type %s" % (x, k, _typeStr(x))
86  raise FieldValidationError(self._field, self._config, msg)
87  else:
88  if type(x) != self._field.itemtype and x is not None:
89  msg ="Value %s at key %r is of incorrect type %s. Expected type %s"%\
90  (x, k, _typeStr(x), _typeStr(self._field.itemtype))
91  raise FieldValidationError(self._field, self._config, msg)
92 
93  #validate item using itemcheck
94  if self._field.itemCheck is not None and not self._field.itemCheck(x):
95  msg="Item at key %r is not a valid value: %s"%(k, x)
96  raise FieldValidationError(self._field, self._config, msg)
97 
98  if at is None:
99  at = traceback.extract_stack()[:-1]
100 
101  self._dict[k]=x
102  if setHistory:
103  self._history.append((dict(self._dict), at, label))
104 
105  def __delitem__(self, k, at=None, label="delitem", setHistory=True):
106  if self._config._frozen:
107  raise FieldValidationError(self._field, self._config,
108  "Cannot modify a frozen Config")
109 
110  del self._dict[k]
111  if setHistory:
112  if at is None:
113  at = traceback.extract_stack()[:-1]
114  self._history.append((dict(self._dict), at, label))
115 
116  def __repr__(self): return repr(self._dict)
117 
118  def __str__(self): return str(self._dict)
119 
120  def __setattr__(self, attr, value, at=None, label="assignment"):
121  if hasattr(getattr(self.__class__, attr, None), '__set__'):
122  # This allows properties to work.
123  object.__setattr__(self, attr, value)
124  elif attr in self.__dict__ or attr in ["_field", "_config", "_history", "_dict", "__doc__"]:
125  # This allows specific private attributes to work.
126  object.__setattr__(self, attr, value)
127  else:
128  # We throw everything else.
129  msg = "%s has no attribute %s"%(_typeStr(self._field), attr)
130  raise FieldValidationError(self._field, self._config, msg)
131 
132 
133 class DictField(Field):
134  """
135  Defines a field which is a mapping of values
136 
137  Both key and item types are restricted to builtin POD types:
138  (int, float, complex, bool, str)
139 
140  Users can provide two check functions:
141  dictCheck: used to validate the dict as a whole, and
142  itemCheck: used to validate each item individually
143 
144  For example to define a field which is a mapping from names to int values:
145 
146  class MyConfig(Config):
147  field = DictField(
148  doc="example string-to-int mapping field",
149  keytype=str, itemtype=int,
150  default= {})
151  """
152  DictClass = Dict
153 
154  def __init__(self, doc, keytype, itemtype, default=None, optional=False, dictCheck=None, itemCheck=None):
155  source = traceback.extract_stack(limit=2)[0]
156  self._setup( doc=doc, dtype=Dict, default=default, check=None,
157  optional=optional, source=source)
158  if keytype not in self.supportedTypes:
159  raise ValueError("'keytype' %s is not a supported type"%\
160  _typeStr(keytype))
161  elif itemtype is not None and itemtype not in self.supportedTypes:
162  raise ValueError("'itemtype' %s is not a supported type"%\
163  _typeStr(itemtype))
164  if dictCheck is not None and not hasattr(dictCheck, "__call__"):
165  raise ValueError("'dictCheck' must be callable")
166  if itemCheck is not None and not hasattr(itemCheck, "__call__"):
167  raise ValueError("'itemCheck' must be callable")
168 
169  self.keytype = keytype
170  self.itemtype = itemtype
171  self.dictCheck = dictCheck
172  self.itemCheck = itemCheck
173 
174  def validate(self, instance):
175  """
176  DictField validation ensures that non-optional fields are not None,
177  and that non-None values comply with dictCheck.
178  Individual Item checks are applied at set time and are not re-checked.
179  """
180  Field.validate(self, instance)
181  value = self.__get__(instance)
182  if value is not None and self.dictCheck is not None \
183  and not self.dictCheck(value):
184  msg = "%s is not a valid value"%str(value)
185  raise FieldValidationError(self, instance, msg)
186 
187 
188  def __set__(self, instance, value, at=None, label="assignment"):
189  if instance._frozen:
190  msg = "Cannot modify a frozen Config. "\
191  "Attempting to set field to value %s"%value
192  raise FieldValidationError(self, instance, msg)
193 
194  if at is None:
195  at = traceback.extract_stack()[:-1]
196  if value is not None:
197  value = self.DictClass(instance, self, value, at=at, label=label)
198  else:
199  history = instance._history.setdefault(self.name, [])
200  history.append((value, at, label))
201 
202  instance._storage[self.name] = value
203 
204  def toDict(self, instance):
205  value = self.__get__(instance)
206  return dict(value) if value is not None else None
207 
208  def _compare(self, instance1, instance2, shortcut, rtol, atol, output):
209  """Helper function for Config.compare; used to compare two fields for equality.
210 
211  @param[in] instance1 LHS Config instance to compare.
212  @param[in] instance2 RHS Config instance to compare.
213  @param[in] shortcut If True, return as soon as an inequality is found.
214  @param[in] rtol Relative tolerance for floating point comparisons.
215  @param[in] atol Absolute tolerance for floating point comparisons.
216  @param[in] output If not None, a callable that takes a string, used (possibly repeatedly)
217  to report inequalities.
218 
219  Floating point comparisons are performed by numpy.allclose; refer to that for details.
220  """
221  d1 = getattr(instance1, self.name)
222  d2 = getattr(instance2, self.name)
223  name = getComparisonName(
224  _joinNamePath(instance1._name, self.name),
225  _joinNamePath(instance2._name, self.name)
226  )
227  if not compareScalars("isnone for %s" % name, d1 is None, d2 is None, output=output):
228  return False
229  if d1 is None and d2 is None:
230  return True
231  if not compareScalars("keys for %s" % name, d1.keys(), d2.keys(), output=output):
232  return False
233  equal = True
234  for k, v1 in d1.iteritems():
235  v2 = d2[k]
236  result = compareScalars("%s[%r]" % (name, k), v1, v2, dtype=self.itemtype,
237  rtol=rtol, atol=atol, output=output)
238  if not result and shortcut:
239  return False
240  equal = equal and result
241  return equal