lsst.pex.config  14.0-1-gbcd7061+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 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__ (self, 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 420 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 466 of file config.py.

◆ __delattr__()

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

Definition at line 733 of file config.py.

◆ __eq__()

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

Definition at line 741 of file config.py.

◆ __iter__()

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

Iterate over fields.

Definition at line 431 of file config.py.

◆ __ne__()

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

Definition at line 754 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 473 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 505 of file config.py.

◆ __repr__()

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

Definition at line 760 of file config.py.

◆ __setattr__() [1/2]

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

Definition at line 121 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 707 of file config.py.

◆ __str__()

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

Definition at line 757 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 766 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 692 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 636 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 446 of file config.py.

◆ iteritems()

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

Iterate over (field name, field value) pairs.

Definition at line 451 of file config.py.

◆ iterkeys()

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

Iterate over field names.

Definition at line 461 of file config.py.

◆ itervalues()

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

Iterate over field values.

Definition at line 456 of file config.py.

◆ keys()

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

Return the list of field names.

Definition at line 436 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 543 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 560 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 596 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 616 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 516 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 652 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 525 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 675 of file config.py.

◆ values()

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

Return the list of field values.

Definition at line 441 of file config.py.

Property Documentation

◆ history

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

Definition at line 705 of file config.py.


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