lsst.pex.config  18.0.0-1-gc037db8+1
configurableField.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 __all__ = ('ConfigurableInstance', 'ConfigurableField')
23 
24 import copy
25 
26 from .config import Config, Field, _joinNamePath, _typeStr, FieldValidationError
27 from .comparison import compareConfigs, getComparisonName
28 from .callStack import getCallStack, getStackFrame
29 
30 
32  """A retargetable configuration in a `ConfigurableField` that proxies
33  a `~lsst.pex.config.Config`.
34 
35  Notes
36  -----
37  ``ConfigurableInstance`` implements ``__getattr__`` and ``__setattr__``
38  methods that forward to the `~lsst.pex.config.Config` it holds.
39  ``ConfigurableInstance`` adds a `retarget` method.
40 
41  The actual `~lsst.pex.config.Config` instance is accessed using the
42  ``value`` property (e.g. to get its documentation). The associated
43  configurable object (usually a `~lsst.pipe.base.Task`) is accessed
44  using the ``target`` property.
45  """
46 
47  def __initValue(self, at, label):
48  """Construct value of field.
49 
50  Notes
51  -----
52  If field.default is an instance of `lsst.pex.config.ConfigClass`,
53  custom construct ``_value`` with the correct values from default.
54  Otherwise, call ``ConfigClass`` constructor
55  """
56  name = _joinNamePath(self._config._name, self._field.name)
57  if type(self._field.default) == self.ConfigClass:
58  storage = self._field.default._storage
59  else:
60  storage = {}
61  value = self._ConfigClass(__name=name, __at=at, __label=label, **storage)
62  object.__setattr__(self, "_value", value)
63 
64  def __init__(self, config, field, at=None, label="default"):
65  object.__setattr__(self, "_config", config)
66  object.__setattr__(self, "_field", field)
67  object.__setattr__(self, "__doc__", config)
68  object.__setattr__(self, "_target", field.target)
69  object.__setattr__(self, "_ConfigClass", field.ConfigClass)
70  object.__setattr__(self, "_value", None)
71 
72  if at is None:
73  at = getCallStack()
74  at += [self._field.source]
75  self.__initValue(at, label)
76 
77  history = config._history.setdefault(field.name, [])
78  history.append(("Targeted and initialized from defaults", at, label))
79 
80  target = property(lambda x: x._target)
81  """The targeted configurable (read-only).
82  """
83 
84  ConfigClass = property(lambda x: x._ConfigClass)
85  """The configuration class (read-only)
86  """
87 
88  value = property(lambda x: x._value)
89  """The `ConfigClass` instance (`lsst.pex.config.ConfigClass`-type,
90  read-only).
91  """
92 
93  def apply(self, *args, **kw):
94  """Call the configurable.
95 
96  Notes
97  -----
98  In addition to the user-provided positional and keyword arguments,
99  the configurable is also provided a keyword argument ``config`` with
100  the value of `ConfigurableInstance.value`.
101  """
102  return self.target(*args, config=self.value, **kw)
103 
104  def retarget(self, target, ConfigClass=None, at=None, label="retarget"):
105  """Target a new configurable and ConfigClass
106  """
107  if self._config._frozen:
108  raise FieldValidationError(self._field, self._config, "Cannot modify a frozen Config")
109 
110  try:
111  ConfigClass = self._field.validateTarget(target, ConfigClass)
112  except BaseException as e:
113  raise FieldValidationError(self._field, self._config, e.message)
114 
115  if at is None:
116  at = getCallStack()
117  object.__setattr__(self, "_target", target)
118  if ConfigClass != self.ConfigClass:
119  object.__setattr__(self, "_ConfigClass", ConfigClass)
120  self.__initValue(at, label)
121 
122  history = self._config._history.setdefault(self._field.name, [])
123  msg = "retarget(target=%s, ConfigClass=%s)" % (_typeStr(target), _typeStr(ConfigClass))
124  history.append((msg, at, label))
125 
126  def __getattr__(self, name):
127  return getattr(self._value, name)
128 
129  def __setattr__(self, name, value, at=None, label="assignment"):
130  """Pretend to be an instance of ConfigClass.
131 
132  Attributes defined by ConfigurableInstance will shadow those defined in ConfigClass
133  """
134  if self._config._frozen:
135  raise FieldValidationError(self._field, self._config, "Cannot modify a frozen Config")
136 
137  if name in self.__dict__:
138  # attribute exists in the ConfigurableInstance wrapper
139  object.__setattr__(self, name, value)
140  else:
141  if at is None:
142  at = getCallStack()
143  self._value.__setattr__(name, value, at=at, label=label)
144 
145  def __delattr__(self, name, at=None, label="delete"):
146  """
147  Pretend to be an isntance of ConfigClass.
148  Attributes defiend by ConfigurableInstance will shadow those defined in ConfigClass
149  """
150  if self._config._frozen:
151  raise FieldValidationError(self._field, self._config, "Cannot modify a frozen Config")
152 
153  try:
154  # attribute exists in the ConfigurableInstance wrapper
155  object.__delattr__(self, name)
156  except AttributeError:
157  if at is None:
158  at = getCallStack()
159  self._value.__delattr__(name, at=at, label=label)
160 
161 
163  """A configuration field (`~lsst.pex.config.Field` subclass) that can be
164  can be retargeted towards a different configurable (often a
165  `lsst.pipe.base.Task` subclass).
166 
167  The ``ConfigurableField`` is often used to configure subtasks, which are
168  tasks (`~lsst.pipe.base.Task`) called by a parent task.
169 
170  Parameters
171  ----------
172  doc : `str`
173  A description of the configuration field.
174  target : configurable class
175  The configurable target. Configurables have a ``ConfigClass``
176  attribute. Within the task framework, configurables are
177  `lsst.pipe.base.Task` subclasses)
178  ConfigClass : `lsst.pex.config.Config`-type, optional
179  The subclass of `lsst.pex.config.Config` expected as the configuration
180  class of the ``target``. If ``ConfigClass`` is unset then
181  ``target.ConfigClass`` is used.
182  default : ``ConfigClass``-type, optional
183  The default configuration class. Normally this parameter is not set,
184  and defaults to ``ConfigClass`` (or ``target.ConfigClass``).
185  check : callable, optional
186  Callable that takes the field's value (the ``target``) as its only
187  positional argument, and returns `True` if the ``target`` is valid (and
188  `False` otherwise).
189  deprecated : None or `str`, optional
190  A description of why this Field is deprecated, including removal date.
191  If not None, the string is appended to the docstring for this Field.
192 
193  See also
194  --------
195  ChoiceField
196  ConfigChoiceField
197  ConfigDictField
198  ConfigField
199  DictField
200  Field
201  ListField
202  RangeField
203  RegistryField
204 
205  Notes
206  -----
207  You can use the `ConfigurableInstance.apply` method to construct a
208  fully-configured configurable.
209  """
210 
211  def validateTarget(self, target, ConfigClass):
212  """Validate the target and configuration class.
213 
214  Parameters
215  ----------
216  target
217  The configurable being verified.
218  ConfigClass : `lsst.pex.config.Config`-type or `None`
219  The configuration class associated with the ``target``. This can
220  be `None` if ``target`` has a ``ConfigClass`` attribute.
221 
222  Raises
223  ------
224  AttributeError
225  Raised if ``ConfigClass`` is `None` and ``target`` does not have a
226  ``ConfigClass`` attribute.
227  TypeError
228  Raised if ``ConfigClass`` is not a `~lsst.pex.config.Config`
229  subclass.
230  ValueError
231  Raised if:
232 
233  - ``target`` is not callable (callables have a ``__call__``
234  method).
235  - ``target`` is not startically defined (does not have
236  ``__module__`` or ``__name__`` attributes).
237  """
238  if ConfigClass is None:
239  try:
240  ConfigClass = target.ConfigClass
241  except Exception:
242  raise AttributeError("'target' must define attribute 'ConfigClass'")
243  if not issubclass(ConfigClass, Config):
244  raise TypeError("'ConfigClass' is of incorrect type %s."
245  "'ConfigClass' must be a subclass of Config" % _typeStr(ConfigClass))
246  if not hasattr(target, '__call__'):
247  raise ValueError("'target' must be callable")
248  if not hasattr(target, '__module__') or not hasattr(target, '__name__'):
249  raise ValueError("'target' must be statically defined"
250  "(must have '__module__' and '__name__' attributes)")
251  return ConfigClass
252 
253  def __init__(self, doc, target, ConfigClass=None, default=None, check=None, deprecated=None):
254  ConfigClass = self.validateTarget(target, ConfigClass)
255 
256  if default is None:
257  default = ConfigClass
258  if default != ConfigClass and type(default) != ConfigClass:
259  raise TypeError("'default' is of incorrect type %s. Expected %s" %
260  (_typeStr(default), _typeStr(ConfigClass)))
261 
262  source = getStackFrame()
263  self._setup(doc=doc, dtype=ConfigurableInstance, default=default,
264  check=check, optional=False, source=source, deprecated=deprecated)
265  self.target = target
266  self.ConfigClass = ConfigClass
267 
268  def __getOrMake(self, instance, at=None, label="default"):
269  value = instance._storage.get(self.name, None)
270  if value is None:
271  if at is None:
272  at = getCallStack(1)
273  value = ConfigurableInstance(instance, self, at=at, label=label)
274  instance._storage[self.name] = value
275  return value
276 
277  def __get__(self, instance, owner=None, at=None, label="default"):
278  if instance is None or not isinstance(instance, Config):
279  return self
280  else:
281  return self.__getOrMake(instance, at=at, label=label)
282 
283  def __set__(self, instance, value, at=None, label="assignment"):
284  if instance._frozen:
285  raise FieldValidationError(self, instance, "Cannot modify a frozen Config")
286  if at is None:
287  at = getCallStack()
288  oldValue = self.__getOrMake(instance, at=at)
289 
290  if isinstance(value, ConfigurableInstance):
291  oldValue.retarget(value.target, value.ConfigClass, at, label)
292  oldValue.update(__at=at, __label=label, **value._storage)
293  elif type(value) == oldValue._ConfigClass:
294  oldValue.update(__at=at, __label=label, **value._storage)
295  elif value == oldValue.ConfigClass:
296  value = oldValue.ConfigClass()
297  oldValue.update(__at=at, __label=label, **value._storage)
298  else:
299  msg = "Value %s is of incorrect type %s. Expected %s" % \
300  (value, _typeStr(value), _typeStr(oldValue.ConfigClass))
301  raise FieldValidationError(self, instance, msg)
302 
303  def rename(self, instance):
304  fullname = _joinNamePath(instance._name, self.name)
305  value = self.__getOrMake(instance)
306  value._rename(fullname)
307 
308  def _collectImports(self, instance, imports):
309  value = self.__get__(instance)
310  target = value.target
311  imports.add(target.__module__)
312  value.value._collectImports()
313  imports |= value.value._imports
314 
315  def save(self, outfile, instance):
316  fullname = _joinNamePath(instance._name, self.name)
317  value = self.__getOrMake(instance)
318  target = value.target
319 
320  if target != self.target:
321  # not targeting the field-default target.
322  # save target information
323  ConfigClass = value.ConfigClass
324  outfile.write(u"{}.retarget(target={}, ConfigClass={})\n\n".format(fullname,
325  _typeStr(target),
326  _typeStr(ConfigClass)))
327  # save field values
328  value._save(outfile)
329 
330  def freeze(self, instance):
331  value = self.__getOrMake(instance)
332  value.freeze()
333 
334  def toDict(self, instance):
335  value = self.__get__(instance)
336  return value.toDict()
337 
338  def validate(self, instance):
339  value = self.__get__(instance)
340  value.validate()
341 
342  if self.check is not None and not self.check(value):
343  msg = "%s is not a valid value" % str(value)
344  raise FieldValidationError(self, instance, msg)
345 
346  def __deepcopy__(self, memo):
347  """Customize deep-copying, because we always want a reference to the
348  original typemap.
349 
350  WARNING: this must be overridden by subclasses if they change the
351  constructor signature!
352  """
353  return type(self)(doc=self.doc, target=self.target, ConfigClass=self.ConfigClass,
354  default=copy.deepcopy(self.default))
355 
356  def _compare(self, instance1, instance2, shortcut, rtol, atol, output):
357  """Compare two fields for equality.
358 
359  Used by `lsst.pex.ConfigDictField.compare`.
360 
361  Parameters
362  ----------
363  instance1 : `lsst.pex.config.Config`
364  Left-hand side config instance to compare.
365  instance2 : `lsst.pex.config.Config`
366  Right-hand side config instance to compare.
367  shortcut : `bool`
368  If `True`, this function returns as soon as an inequality if found.
369  rtol : `float`
370  Relative tolerance for floating point comparisons.
371  atol : `float`
372  Absolute tolerance for floating point comparisons.
373  output : callable
374  A callable that takes a string, used (possibly repeatedly) to
375  report inequalities. For example: `print`.
376 
377  Returns
378  -------
379  isEqual : bool
380  `True` if the fields are equal, `False` otherwise.
381 
382  Notes
383  -----
384  Floating point comparisons are performed by `numpy.allclose`.
385  """
386  c1 = getattr(instance1, self.name)._value
387  c2 = getattr(instance2, self.name)._value
388  name = getComparisonName(
389  _joinNamePath(instance1._name, self.name),
390  _joinNamePath(instance2._name, self.name)
391  )
392  return compareConfigs(name, c1, c2, shortcut=shortcut, rtol=rtol, atol=atol, output=output)
def __setattr__(self, name, value, at=None, label="assignment")
def compareConfigs(name, c1, c2, shortcut=True, rtol=1E-8, atol=1E-8, output=None)
Definition: comparison.py:105
def getCallStack(skip=0)
Definition: callStack.py:169
def __get__(self, instance, owner=None, at=None, label="default")
Definition: config.py:488
def getStackFrame(relative=0)
Definition: callStack.py:52
def format(config, name=None, writeSourceLine=True, prefix="", verbose=False)
Definition: history.py:168
def retarget(self, target, ConfigClass=None, at=None, label="retarget")
def __init__(self, doc, target, ConfigClass=None, default=None, check=None, deprecated=None)
def __init__(self, config, field, at=None, label="default")
def __getOrMake(self, instance, at=None, label="default")
def __delattr__(self, name, at=None, label="delete")
def __get__(self, instance, owner=None, at=None, label="default")
def _setup(self, doc, dtype, default, check, optional, source, deprecated)
Definition: config.py:278
def __set__(self, instance, value, at=None, label="assignment")
def getComparisonName(name1, name2)
Definition: comparison.py:34