lsst.pex.config  16.0-8-g4734f7a+1
Public Member Functions | Properties | List of all members
lsst.pex.config.config.Config Class Reference
Inheritance diagram for lsst.pex.config.config.Config:
lsst.pex.config.config.ConfigMeta

Public Member Functions

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

Properties

 history = property(lambda x: x._history)
 

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 408 of file config.py.

Member Function Documentation

◆ __contains__()

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 454 of file config.py.

◆ __delattr__()

def lsst.pex.config.config.Config.__delattr__ (   self,
  attr,
  at = None,
  label = "deletion" 
)

Definition at line 746 of file config.py.

◆ __eq__()

def lsst.pex.config.config.Config.__eq__ (   self,
  other 
)

Definition at line 754 of file config.py.

◆ __iter__()

def lsst.pex.config.config.Config.__iter__ (   self)

Iterate over fields.

Definition at line 419 of file config.py.

◆ __ne__()

def lsst.pex.config.config.Config.__ne__ (   self,
  other 
)

Definition at line 767 of file config.py.

◆ __new__()

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 461 of file config.py.

◆ __reduce__()

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 493 of file config.py.

◆ __repr__()

def lsst.pex.config.config.Config.__repr__ (   self)

Definition at line 773 of file config.py.

◆ __setattr__() [1/2]

def lsst.pex.config.config.ConfigMeta.__setattr__ (   cls,
  name,
  value 
)
inherited

Definition at line 110 of file config.py.

◆ __setattr__() [2/2]

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 720 of file config.py.

◆ __str__()

def lsst.pex.config.config.Config.__str__ (   self)

Definition at line 770 of file config.py.

◆ compare()

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 779 of file config.py.

◆ formatHistory()

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 705 of file config.py.

◆ freeze()

def lsst.pex.config.config.Config.freeze (   self)

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

Definition at line 624 of file config.py.

◆ items()

def lsst.pex.config.config.Config.items (   self)

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

Definition at line 434 of file config.py.

◆ iteritems()

def lsst.pex.config.config.Config.iteritems (   self)

Iterate over (field name, field value) pairs.

Definition at line 439 of file config.py.

◆ iterkeys()

def lsst.pex.config.config.Config.iterkeys (   self)

Iterate over field names.

Definition at line 449 of file config.py.

◆ itervalues()

def lsst.pex.config.config.Config.itervalues (   self)

Iterate over field values.

Definition at line 444 of file config.py.

◆ keys()

def lsst.pex.config.config.Config.keys (   self)

Return the list of field names.

Definition at line 424 of file config.py.

◆ load()

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 531 of file config.py.

◆ loadFromStream()

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 548 of file config.py.

◆ names()

def lsst.pex.config.config.Config.names (   self)

Return all the keys in a config recursively.

Definition at line 651 of file config.py.

◆ save()

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 584 of file config.py.

◆ saveToStream()

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. Accepts strings not bytes.
root[in] name to use for the root config variable; the same value must be used when loading

Definition at line 604 of file config.py.

◆ setDefaults()

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 504 of file config.py.

◆ toDict()

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 640 of file config.py.

◆ update()

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 513 of file config.py.

◆ validate()

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 688 of file config.py.

◆ values()

def lsst.pex.config.config.Config.values (   self)

Return the list of field values.

Definition at line 429 of file config.py.

Property Documentation

◆ history

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

Definition at line 718 of file config.py.


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