LSSTApplications  10.0+286,10.0+36,10.0+46,10.0-2-g4f67435,10.1+152,10.1+37,11.0,11.0+1,11.0-1-g47edd16,11.0-1-g60db491,11.0-1-g7418c06,11.0-2-g04d2804,11.0-2-g68503cd,11.0-2-g818369d,11.0-2-gb8b8ce7
LSSTDataManagementBasePackage
Public Member Functions | Properties | Private Member Functions | Private Attributes | Static Private Attributes | List of all members
lsst.pex.config.config.Config Class Reference
Inheritance diagram for lsst.pex.config.config.Config:

Public Member Functions

def __iter__
 Iterate over fields. More...
 
def keys
 Return the list of field names. More...
 
def values
 Return the list of field values. More...
 
def items
 Return the list of (field name, field value) pairs. More...
 
def iteritems
 Iterate over (field name, field value) pairs. More...
 
def itervalues
 Iterate over field values. More...
 
def iterkeys
 Iterate over field names. More...
 
def __contains__
 Return True if the specified field exists in this config. More...
 
def __new__
 Allocate a new Config object. More...
 
def __reduce__
 
def setDefaults
 
def update
 Update values specified by the keyword arguments. More...
 
def load
 Modify this config in place by executing the Python code in the named file. More...
 
def loadFromStream
 Modify this config in place by executing the python code in the provided stream. More...
 
def save
 Save a python script to the named file, which, when loaded, reproduces this Config. More...
 
def saveToStream
 Save a python script to a stream, which, when loaded, reproduces this Config. More...
 
def freeze
 Make this Config and all sub-configs read-only. More...
 
def toDict
 Return a dict of field name: value. More...
 
def validate
 Validate the Config; raise an exception if invalid. More...
 
def formatHistory
 Format the specified config field's history to a more human-readable format. More...
 
def __setattr__
 Regulate which attributes can be set. More...
 
def __delattr__
 
def __eq__
 
def __ne__
 
def __str__
 
def __repr__
 
def compare
 Compare two Configs for equality; return True if equal. More...
 

Properties

 history = property(lambda x: x._history)
 

Private Member Functions

def _save
 Save this Config to an open stream object. More...
 
def _rename
 Rename this Config object in its parent config. More...
 

Private Attributes

 _frozen
 
 _name
 

Static Private Attributes

 __metaclass__ = ConfigMeta
 

Detailed Description

Base class for control objects.

A Config object will usually have several Field instances as class 
attributes; these are used to define most of the base class behavior.  
Simple derived class should be able to be defined simply by setting those 
attributes.

Config also emulates a dict of field name: field value

Definition at line 392 of file config.py.

Member Function Documentation

def lsst.pex.config.config.Config.__contains__ (   self,
  name 
)

Return True if the specified field exists in this config.

Parameters
[in]namefield name to test for

Definition at line 438 of file config.py.

439  def __contains__(self, name):
440  """!Return True if the specified field exists in this config
441 
442  @param[in] name field name to test for
443  """
444  return self._storage.__contains__(name)
def __contains__
Return True if the specified field exists in this config.
Definition: config.py:438
def lsst.pex.config.config.Config.__delattr__ (   self,
  attr,
  at = None,
  label = "deletion" 
)

Definition at line 689 of file config.py.

690  def __delattr__(self, attr, at=None, label="deletion"):
691  if attr in self._fields:
692  if at is None:
693  at=traceback.extract_stack()[:-1]
694  self._fields[attr].__delete__(self, at=at, label=label)
695  else:
696  object.__delattr__(self, attr)
def lsst.pex.config.config.Config.__eq__ (   self,
  other 
)

Definition at line 697 of file config.py.

698  def __eq__(self, other):
699  if type(other) == type(self):
700  for name in self._fields:
701  thisValue = getattr(self, name)
702  otherValue = getattr(other, name)
703  if isinstance(thisValue, float) and math.isnan(thisValue):
704  if not math.isnan(otherValue):
705  return False
706  elif thisValue != otherValue:
707  return False
708  return True
709  return False
def lsst.pex.config.config.Config.__iter__ (   self)

Iterate over fields.

Definition at line 405 of file config.py.

406  def __iter__(self):
407  """!Iterate over fields
408  """
409  return self._fields.__iter__()
def __iter__
Iterate over fields.
Definition: config.py:405
def lsst.pex.config.config.Config.__ne__ (   self,
  other 
)

Definition at line 710 of file config.py.

711  def __ne__(self, other):
712  return not self.__eq__(other)
def lsst.pex.config.config.Config.__new__ (   cls,
  args,
  kw 
)

Allocate a new Config object.

In order to ensure that all Config object are always in a proper state when handed to users or to derived Config classes, some attributes are handled at allocation time rather than at initialization

This ensures that even if a derived Config class implements init, the author does not need to be concerned about when or even if he should call the base Config.__init__

Definition at line 445 of file config.py.

446  def __new__(cls, *args, **kw):
447  """!Allocate a new Config object.
448 
449  In order to ensure that all Config object are always in a proper
450  state when handed to users or to derived Config classes, some
451  attributes are handled at allocation time rather than at initialization
452 
453  This ensures that even if a derived Config class implements __init__,
454  the author does not need to be concerned about when or even if he
455  should call the base Config.__init__
456  """
457  name = kw.pop("__name", None)
458  at = kw.pop("__at", traceback.extract_stack()[:-1])
459  # remove __label and ignore it
460  kw.pop("__label", "default")
461 
462  instance = object.__new__(cls)
463  instance._frozen=False
464  instance._name=name
465  instance._storage = {}
466  instance._history = {}
467  instance._imports = set()
468  # load up defaults
469  for field in instance._fields.itervalues():
470  instance._history[field.name]=[]
471  field.__set__(instance, field.default, at=at+[field.source], label="default")
472  # set custom default-overides
473  instance.setDefaults()
474  # set constructor overides
475  instance.update(__at=at, **kw)
476  return instance
def __new__
Allocate a new Config object.
Definition: config.py:445
def lsst.pex.config.config.Config.__reduce__ (   self)
Reduction for pickling (function with arguments to reproduce).

We need to condense and reconstitute the Config, since it may contain lambdas
(as the 'check' elements) that cannot be pickled.

Definition at line 477 of file config.py.

478  def __reduce__(self):
479  """Reduction for pickling (function with arguments to reproduce).
480 
481  We need to condense and reconstitute the Config, since it may contain lambdas
482  (as the 'check' elements) that cannot be pickled.
483  """
484  stream = io.BytesIO()
485  self.saveToStream(stream)
486  return (unreduceConfig, (self.__class__, stream.getvalue()))
def saveToStream
Save a python script to a stream, which, when loaded, reproduces this Config.
Definition: config.py:574
def lsst.pex.config.config.Config.__repr__ (   self)

Definition at line 716 of file config.py.

717  def __repr__(self):
718  return "%s(%s)" % (
719  _typeStr(self),
720  ", ".join("%s=%r" % (k, v) for k, v in self.toDict().iteritems() if v is not None)
721  )
def iteritems
Iterate over (field name, field value) pairs.
Definition: config.py:423
def toDict
Return a dict of field name: value.
Definition: config.py:608
def lsst.pex.config.config.Config.__setattr__ (   self,
  attr,
  value,
  at = None,
  label = "assignment" 
)

Regulate which attributes can be set.

Unlike normal python objects, Config objects are locked such that no additional attributes nor properties may be added to them dynamically.

Although this is not the standard Python behavior, it helps to protect users from accidentally mispelling a field name, or trying to set a non-existent field.

Definition at line 663 of file config.py.

664  def __setattr__(self, attr, value, at=None, label="assignment"):
665  """!Regulate which attributes can be set
666 
667  Unlike normal python objects, Config objects are locked such
668  that no additional attributes nor properties may be added to them
669  dynamically.
670 
671  Although this is not the standard Python behavior, it helps to
672  protect users from accidentally mispelling a field name, or
673  trying to set a non-existent field.
674  """
675  if attr in self._fields:
676  if at is None:
677  at=traceback.extract_stack()[:-1]
678  # This allows Field descriptors to work.
679  self._fields[attr].__set__(self, value, at=at, label=label)
680  elif hasattr(getattr(self.__class__, attr, None), '__set__'):
681  # This allows properties and other non-Field descriptors to work.
682  return object.__setattr__(self, attr, value)
683  elif attr in self.__dict__ or attr in ("_name", "_history", "_storage", "_frozen", "_imports"):
684  # This allows specific private attributes to work.
685  self.__dict__[attr] = value
686  else:
687  # We throw everything else.
688  raise AttributeError("%s has no attribute %s"%(_typeStr(self), attr))
def __setattr__
Regulate which attributes can be set.
Definition: config.py:663
def lsst.pex.config.config.Config.__str__ (   self)

Definition at line 713 of file config.py.

714  def __str__(self):
715  return str(self.toDict())
def toDict
Return a dict of field name: value.
Definition: config.py:608
def lsst.pex.config.config.Config._rename (   self,
  name 
)
private

Rename this Config object in its parent config.

Parameters
[in]namenew name for this config in its parent config

Correct behavior is dependent on proper implementation of Field.rename. If implementing a new Field type, you may need to implement your own rename method.

Definition at line 619 of file config.py.

620  def _rename(self, name):
621  """!Rename this Config object in its parent config
622 
623  @param[in] name new name for this config in its parent config
624 
625  Correct behavior is dependent on proper implementation of Field.rename. If implementing a new
626  Field type, you may need to implement your own rename method.
627  """
628  self._name = name
629  for field in self._fields.itervalues():
630  field.rename(self)
def _rename
Rename this Config object in its parent config.
Definition: config.py:619
def lsst.pex.config.config.Config._save (   self,
  outfile 
)
private

Save this Config to an open stream object.

Definition at line 599 of file config.py.

600  def _save(self, outfile):
601  """!Save this Config to an open stream object
602  """
603  for imp in self._imports:
604  if imp in sys.modules and sys.modules[imp] is not None:
605  print >> outfile, "import %s" % imp
606  for field in self._fields.itervalues():
607  field.save(outfile, self)
def _save
Save this Config to an open stream object.
Definition: config.py:599
def lsst.pex.config.config.Config.compare (   self,
  other,
  shortcut = True,
  rtol = 1E-8,
  atol = 1E-8,
  output = None 
)

Compare two Configs for equality; return True if equal.

If the Configs contain RegistryFields or ConfigChoiceFields, unselected Configs will not be compared.

Parameters
[in]otherConfig object to compare with self.
[in]shortcutIf True, return as soon as an inequality is found.
[in]rtolRelative tolerance for floating point comparisons.
[in]atolAbsolute tolerance for floating point comparisons.
[in]outputIf not None, a callable that takes a string, used (possibly repeatedly) to report inequalities.

Floating point comparisons are performed by numpy.allclose; refer to that for details.

Definition at line 722 of file config.py.

723  def compare(self, other, shortcut=True, rtol=1E-8, atol=1E-8, output=None):
724  """!Compare two Configs for equality; return True if equal
725 
726  If the Configs contain RegistryFields or ConfigChoiceFields, unselected Configs
727  will not be compared.
728 
729  @param[in] other Config object to compare with self.
730  @param[in] shortcut If True, return as soon as an inequality is found.
731  @param[in] rtol Relative tolerance for floating point comparisons.
732  @param[in] atol Absolute tolerance for floating point comparisons.
733  @param[in] output If not None, a callable that takes a string, used (possibly repeatedly)
734  to report inequalities.
735 
736  Floating point comparisons are performed by numpy.allclose; refer to that for details.
737  """
738  name1 = self._name if self._name is not None else "config"
739  name2 = other._name if other._name is not None else "config"
740  name = getComparisonName(name1, name2)
741  return compareConfigs(name, self, other, shortcut=shortcut,
742  rtol=rtol, atol=atol, output=output)
def compare
Compare two Configs for equality; return True if equal.
Definition: config.py:722
def lsst.pex.config.config.Config.formatHistory (   self,
  name,
  kwargs 
)

Format the specified config field's history to a more human-readable format.

Parameters
[in]namename of field whose history is wanted
[in]kwargskeyword arguments for lsst.pex.config.history.format
Returns
a string containing the formatted history

Definition at line 648 of file config.py.

649  def formatHistory(self, name, **kwargs):
650  """!Format the specified config field's history to a more human-readable format
651 
652  @param[in] name name of field whose history is wanted
653  @param[in] kwargs keyword arguments for lsst.pex.config.history.format
654  @return a string containing the formatted history
655  """
656  import lsst.pex.config.history as pexHist
657  return pexHist.format(self, name, **kwargs)
def formatHistory
Format the specified config field's history to a more human-readable format.
Definition: config.py:648
def lsst.pex.config.config.Config.freeze (   self)

Make this Config and all sub-configs read-only.

Definition at line 592 of file config.py.

593  def freeze(self):
594  """!Make this Config and all sub-configs read-only
595  """
596  self._frozen=True
597  for field in self._fields.itervalues():
598  field.freeze(self)
def freeze
Make this Config and all sub-configs read-only.
Definition: config.py:592
def lsst.pex.config.config.Config.items (   self)

Return the list of (field name, field value) pairs.

Definition at line 418 of file config.py.

419  def items(self):
420  """!Return the list of (field name, field value) pairs
421  """
422  return self._storage.items()
def items
Return the list of (field name, field value) pairs.
Definition: config.py:418
def lsst.pex.config.config.Config.iteritems (   self)

Iterate over (field name, field value) pairs.

Definition at line 423 of file config.py.

424  def iteritems(self):
425  """!Iterate over (field name, field value) pairs
426  """
427  return self._storage.iteritems()
def iteritems
Iterate over (field name, field value) pairs.
Definition: config.py:423
def lsst.pex.config.config.Config.iterkeys (   self)

Iterate over field names.

Definition at line 433 of file config.py.

434  def iterkeys(self):
435  """!Iterate over field names
436  """
437  return self.storage.iterkeys()
def iterkeys
Iterate over field names.
Definition: config.py:433
def lsst.pex.config.config.Config.itervalues (   self)

Iterate over field values.

Definition at line 428 of file config.py.

429  def itervalues(self):
430  """!Iterate over field values
431  """
432  return self.storage.itervalues()
def itervalues
Iterate over field values.
Definition: config.py:428
def lsst.pex.config.config.Config.keys (   self)

Return the list of field names.

Definition at line 410 of file config.py.

411  def keys(self):
412  """!Return the list of field names
413  """
return self._storage.keys()
def keys
Return the list of field names.
Definition: config.py:410
def lsst.pex.config.config.Config.load (   self,
  filename,
  root = "config" 
)

Modify this config in place by executing the Python code in the named file.

Parameters
[in]filenamename of file containing config override code
[in]rootname of variable in file that refers to the config being overridden

For example: if the value of root is "config" and the file contains this text: "config.myField = 5" then this config's field "myField" is set to 5.

Deprecated:
For purposes of backwards compatibility, older config files that use root="root" instead of root="config" will be loaded with a warning printed to sys.stderr. This feature will be removed at some point.

Definition at line 514 of file config.py.

515  def load(self, filename, root="config"):
516  """!Modify this config in place by executing the Python code in the named file.
517 
518  @param[in] filename name of file containing config override code
519  @param[in] root name of variable in file that refers to the config being overridden
520 
521  For example: if the value of root is "config" and the file contains this text:
522  "config.myField = 5" then this config's field "myField" is set to 5.
523 
524  @deprecated For purposes of backwards compatibility, older config files that use
525  root="root" instead of root="config" will be loaded with a warning printed to sys.stderr.
526  This feature will be removed at some point.
527  """
528  with open(filename) as f:
529  code = compile(f.read(), filename=filename, mode="exec")
530  self.loadFromStream(stream=code, root=root)
def loadFromStream
Modify this config in place by executing the python code in the provided stream.
Definition: config.py:531
def load
Modify this config in place by executing the Python code in the named file.
Definition: config.py:514
def lsst.pex.config.config.Config.loadFromStream (   self,
  stream,
  root = "config",
  filename = None 
)

Modify this config in place by executing the python code in the provided stream.

Parameters
[in]streamopen file object, string or compiled string containing config override code
[in]rootname of variable in stream that refers to the config being overridden
[in]filenamename of config override file, or None if unknown or contained in the stream; used for error reporting

For example: if the value of root is "config" and the stream contains this text: "config.myField = 5" then this config's field "myField" is set to 5.

Deprecated:
For purposes of backwards compatibility, older config files that use root="root" instead of root="config" will be loaded with a warning printed to sys.stderr. This feature will be removed at some point.

Definition at line 531 of file config.py.

532  def loadFromStream(self, stream, root="config", filename=None):
533  """!Modify this config in place by executing the python code in the provided stream.
534 
535  @param[in] stream open file object, string or compiled string containing config override code
536  @param[in] root name of variable in stream that refers to the config being overridden
537  @param[in] filename name of config override file, or None if unknown or contained
538  in the stream; used for error reporting
539 
540  For example: if the value of root is "config" and the stream contains this text:
541  "config.myField = 5" then this config's field "myField" is set to 5.
542 
543  @deprecated For purposes of backwards compatibility, older config files that use
544  root="root" instead of root="config" will be loaded with a warning printed to sys.stderr.
545  This feature will be removed at some point.
546  """
547  with RecordingImporter() as importer:
548  try:
549  local = {root: self}
550  exec stream in {}, local
551  except NameError as e:
552  if root == "config" and "root" in e.args[0]:
553  if filename is None:
554  # try to determine the file name; a compiled string has attribute "co_filename",
555  # an open file has attribute "name", else give up
556  filename = getattr(stream, "co_filename", None)
557  if filename is None:
558  filename = getattr(stream, "name", "?")
559  sys.stderr.write("Config override file %r" % (filename,) + \
560  " appears to use 'root' instead of 'config'; trying with 'root'")
561  local = {"root": self}
562  exec stream in {}, local
563 
564  self._imports.update(importer.getModules())
def loadFromStream
Modify this config in place by executing the python code in the provided stream.
Definition: config.py:531
def lsst.pex.config.config.Config.save (   self,
  filename,
  root = "config" 
)

Save a python script to the named file, which, when loaded, reproduces this Config.

Parameters
[in]filenamename of file to which to write the config
[in]rootname to use for the root config variable; the same value must be used when loading

Definition at line 565 of file config.py.

566  def save(self, filename, root="config"):
567  """!Save a python script to the named file, which, when loaded, reproduces this Config
568 
569  @param[in] filename name of file to which to write the config
570  @param[in] root name to use for the root config variable; the same value must be used when loading
571  """
572  with open(filename, 'w') as outfile:
573  self.saveToStream(outfile, root)
def saveToStream
Save a python script to a stream, which, when loaded, reproduces this Config.
Definition: config.py:574
def save
Save a python script to the named file, which, when loaded, reproduces this Config.
Definition: config.py:565
def lsst.pex.config.config.Config.saveToStream (   self,
  outfile,
  root = "config" 
)

Save a python script to a stream, which, when loaded, reproduces this Config.

Parameters
outfile[inout] open file object to which to write the config
root[in] name to use for the root config variable; the same value must be used when loading

Definition at line 574 of file config.py.

575  def saveToStream(self, outfile, root="config"):
576  """!Save a python script to a stream, which, when loaded, reproduces this Config
577 
578  @param outfile [inout] open file object to which to write the config
579  @param root [in] name to use for the root config variable; the same value must be used when loading
580  """
581  tmp = self._name
582  self._rename(root)
583  try:
584  configType = type(self)
585  typeString = _typeStr(configType)
586  print >> outfile, "import %s" % (configType.__module__)
587  print >> outfile, "assert type(%s)==%s, 'config is of type %%s.%%s" % (root, typeString), \
588  "instead of %s' %% (type(%s).__module__, type(%s).__name__)" % (typeString, root, root)
589  self._save(outfile)
590  finally:
591  self._rename(tmp)
def saveToStream
Save a python script to a stream, which, when loaded, reproduces this Config.
Definition: config.py:574
def _rename
Rename this Config object in its parent config.
Definition: config.py:619
def _save
Save this Config to an open stream object.
Definition: config.py:599
def lsst.pex.config.config.Config.setDefaults (   self)
Derived config classes that must compute defaults rather than using the 
Field defaults should do so here. 
To correctly use inherited defaults, implementations of setDefaults() 
must call their base class' setDefaults()

Definition at line 487 of file config.py.

488  def setDefaults(self):
489  """
490  Derived config classes that must compute defaults rather than using the
491  Field defaults should do so here.
492  To correctly use inherited defaults, implementations of setDefaults()
493  must call their base class' setDefaults()
494  """
495  pass
def lsst.pex.config.config.Config.toDict (   self)

Return a dict of field name: value.

Correct behavior is dependent on proper implementation of Field.toDict. If implementing a new Field type, you may need to implement your own toDict method.

Definition at line 608 of file config.py.

609  def toDict(self):
610  """!Return a dict of field name: value
611 
612  Correct behavior is dependent on proper implementation of Field.toDict. If implementing a new
613  Field type, you may need to implement your own toDict method.
614  """
615  dict_ = {}
616  for name, field in self._fields.iteritems():
617  dict_[name] = field.toDict(self)
618  return dict_
def toDict
Return a dict of field name: value.
Definition: config.py:608
def lsst.pex.config.config.Config.update (   self,
  kw 
)

Update values specified by the keyword arguments.

Warning
The '__at' and '__label' keyword arguments are special internal keywords. They are used to strip out any internal steps from the history tracebacks of the config. Modifying these keywords allows users to lie about a Config's history. Please do not do so!

Definition at line 496 of file config.py.

497  def update(self, **kw):
498  """!Update values specified by the keyword arguments
499 
500  @warning The '__at' and '__label' keyword arguments are special internal
501  keywords. They are used to strip out any internal steps from the
502  history tracebacks of the config. Modifying these keywords allows users
503  to lie about a Config's history. Please do not do so!
504  """
505  at = kw.pop("__at", traceback.extract_stack()[:-1])
506  label = kw.pop("__label", "update")
507 
508  for name, value in kw.iteritems():
509  try:
510  field = self._fields[name]
511  field.__set__(self, value, at=at, label=label)
512  except KeyError:
513  raise KeyError("No field of name %s exists in config type %s"%(name, _typeStr(self)))
def update
Update values specified by the keyword arguments.
Definition: config.py:496
def lsst.pex.config.config.Config.validate (   self)

Validate the Config; raise an exception if invalid.

The base class implementation performs type checks on all fields by calling Field.validate().

Complex single-field validation can be defined by deriving new Field types. As syntactic sugar, some derived Field types are defined in this module which handle recursing into sub-configs (ConfigField, ConfigChoiceField)

Inter-field relationships should only be checked in derived Config classes after calling this method, and base validation is complete

Definition at line 631 of file config.py.

632  def validate(self):
633  """!Validate the Config; raise an exception if invalid
634 
635  The base class implementation performs type checks on all fields by
636  calling Field.validate().
637 
638  Complex single-field validation can be defined by deriving new Field
639  types. As syntactic sugar, some derived Field types are defined in
640  this module which handle recursing into sub-configs
641  (ConfigField, ConfigChoiceField)
642 
643  Inter-field relationships should only be checked in derived Config
644  classes after calling this method, and base validation is complete
645  """
646  for field in self._fields.itervalues():
647  field.validate(self)
def validate
Validate the Config; raise an exception if invalid.
Definition: config.py:631
def lsst.pex.config.config.Config.values (   self)

Return the list of field values.

Definition at line 414 of file config.py.

415  def values(self):
416  """!Return the list of field values
417  """
return self._storage.values()
def values
Return the list of field values.
Definition: config.py:414

Member Data Documentation

lsst.pex.config.config.Config.__metaclass__ = ConfigMeta
staticprivate

Definition at line 403 of file config.py.

lsst.pex.config.config.Config._frozen
private

Definition at line 595 of file config.py.

lsst.pex.config.config.Config._name
private

Definition at line 627 of file config.py.

Property Documentation

lsst.pex.config.config.Config.history = property(lambda x: x._history)
static

Definition at line 661 of file config.py.


The documentation for this class was generated from the following file: