LSST Applications  21.0.0-172-gfb10e10a+18fedfabac,22.0.0+297cba6710,22.0.0+80564b0ff1,22.0.0+8d77f4f51a,22.0.0+a28f4c53b1,22.0.0+dcf3732eb2,22.0.1-1-g7d6de66+2a20fdde0d,22.0.1-1-g8e32f31+297cba6710,22.0.1-1-geca5380+7fa3b7d9b6,22.0.1-12-g44dc1dc+2a20fdde0d,22.0.1-15-g6a90155+515f58c32b,22.0.1-16-g9282f48+790f5f2caa,22.0.1-2-g92698f7+dcf3732eb2,22.0.1-2-ga9b0f51+7fa3b7d9b6,22.0.1-2-gd1925c9+bf4f0e694f,22.0.1-24-g1ad7a390+a9625a72a8,22.0.1-25-g5bf6245+3ad8ecd50b,22.0.1-25-gb120d7b+8b5510f75f,22.0.1-27-g97737f7+2a20fdde0d,22.0.1-32-gf62ce7b1+aa4237961e,22.0.1-4-g0b3f228+2a20fdde0d,22.0.1-4-g243d05b+871c1b8305,22.0.1-4-g3a563be+32dcf1063f,22.0.1-4-g44f2e3d+9e4ab0f4fa,22.0.1-42-gca6935d93+ba5e5ca3eb,22.0.1-5-g15c806e+85460ae5f3,22.0.1-5-g58711c4+611d128589,22.0.1-5-g75bb458+99c117b92f,22.0.1-6-g1c63a23+7fa3b7d9b6,22.0.1-6-g50866e6+84ff5a128b,22.0.1-6-g8d3140d+720564cf76,22.0.1-6-gd805d02+cc5644f571,22.0.1-8-ge5750ce+85460ae5f3,master-g6e05de7fdc+babf819c66,master-g99da0e417a+8d77f4f51a,w.2021.48
LSST Data Management Base Package
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 lsst.afw.geom.transformConfig.AffineTransformConfig lsst.afw.geom.transformConfig.IdentityTransformConfig lsst.afw.geom.transformConfig.MultiTransformConfig lsst.afw.geom.transformConfig.OneTransformConfig lsst.afw.geom.transformConfig.RadialTransformConfig lsst.afw.geom.transformConfig.TransformConfig lsst.afw.math._chebyshevBoundedFieldConfig.ChebyshevBoundedFieldConfig lsst.dax.apdb.apdb.ApdbConfig lsst.fgcmcal.sedterms.Sedboundaryterm lsst.fgcmcal.sedterms.SedboundarytermDict lsst.fgcmcal.sedterms.Sedterm lsst.fgcmcal.sedterms.SedtermDict lsst.ip.isr.crosstalk.CrosstalkConfig lsst.ip.isr.fringe.FringeConfig lsst.ip.isr.fringe.FringeStatisticsConfig lsst.ip.isr.masking.MaskingConfig lsst.ip.isr.straylight.StrayLightConfig lsst.ip.isr.vignette.VignetteConfig lsst.meas.algorithms.gaussianPsfFactory.GaussianPsfFactory lsst.meas.algorithms.indexerRegistry.HtmIndexerConfig lsst.meas.algorithms.measureApCorr.MeasureApCorrConfig lsst.meas.algorithms.reserveSourcesTask.ReserveSourcesConfig lsst.meas.algorithms.skyObjects.SkyObjectsConfig lsst.meas.astrom.directMatch.DirectMatchConfigWithoutLoader lsst.meas.astrom.fitSipDistortion.FitSipDistortionConfig lsst.meas.base.applyApCorr.ApplyApCorrConfig lsst.meas.base.baseMeasurement.BaseMeasurementConfig lsst.meas.base.baseMeasurement.SourceSlotConfig lsst.meas.base.catalogCalculation.CatalogCalculationConfig lsst.meas.base.noiseReplacer.NoiseReplacerConfig lsst.meas.base.pluginsBase.BasePluginConfig lsst.meas.base.references.BaseReferencesConfig lsst.meas.modelfit.psf.psfContinued.GeneralShapeletPsfApproxConfig lsst.pipe.drivers.background.BackgroundConfig lsst.pipe.drivers.background.FocalPlaneBackgroundConfig lsst.pipe.drivers.background.MaskObjectsConfig lsst.pipe.drivers.background.SkyMeasurementConfig lsst.pipe.drivers.background.SkyStatsConfig lsst.pipe.drivers.coaddDriver.CoaddDriverConfig lsst.pipe.drivers.constructCalibs.CalibCombineConfig lsst.pipe.drivers.constructCalibs.CalibConfig lsst.pipe.drivers.constructCalibs.CalibStatsConfig lsst.pipe.drivers.multiBandDriver.MultiBandDriverConfig lsst.pipe.drivers.processCcdWithFakesDriver.ProcessCcdWithFakesDriverConfig lsst.pipe.drivers.singleFrameDriver.SingleFrameDriverConfig lsst.pipe.drivers.visualizeVisit.VisualizeVisitConfig lsst.pipe.tasks.colorterms.Colorterm lsst.pipe.tasks.colorterms.ColortermDict lsst.pipe.tasks.colorterms.ColortermLibrary lsst.pipe.tasks.configurableActions._configurableAction.ConfigurableAction lsst.pipe.tasks.fakes.BaseFakeSourcesConfig lsst.pipe.tasks.ingest.IngestConfig lsst.pipe.tasks.ingest.ParseConfig lsst.pipe.tasks.ingest.RegisterConfig lsst.pipe.tasks.ingestCalibs.IngestCalibsConfig lsst.pipe.tasks.mocks.mockCoadd.MockCoaddConfig lsst.pipe.tasks.mocks.mockObject.MockObjectConfig lsst.pipe.tasks.mocks.mockObservation.MockObservationConfig lsst.pipe.tasks.multiBandUtils.CullPeaksConfig lsst.pipe.tasks.propagateVisitFlags.PropagateVisitFlagsConfig lsst.pipe.tasks.registerImage.RegisterConfig lsst.pipe.tasks.scaleVariance.ScaleVarianceConfig lsst.pipe.tasks.setPrimaryFlags.SetPrimaryFlagsConfig

Public Member Functions

def __iter__ (self)
 
def keys (self)
 
def values (self)
 
def items (self)
 
def iteritems (self)
 
def itervalues (self)
 
def iterkeys (self)
 
def __contains__ (self, name)
 Return True if the specified field exists in this config. More...
 
def __new__ (cls, *args, **kw)
 
def __reduce__ (self)
 
def setDefaults (self)
 
def update (self, **kw)
 
def load (self, filename, root="config")
 
def loadFromStream (self, stream, root="config", filename=None)
 
def save (self, filename, root="config")
 
def saveToStream (self, outfile, root="config", skipImports=False)
 
def freeze (self)
 
def toDict (self)
 
def names (self)
 
def validate (self)
 
def formatHistory (self, name, **kwargs)
 
def __setattr__ (self, attr, value, at=None, label="assignment")
 
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)
 
def __init_subclass__ (cls, **kwargs)
 
def __setattr__ (cls, name, value)
 

Properties

 history = property(lambda x: x._history)
 

Detailed Description

Base class for configuration (*config*) objects.

Notes
-----
A ``Config`` object will usually have several `~lsst.pex.config.Field`
instances as class attributes. These are used to define most of the base
class behavior.

``Config`` implements a mapping API that provides many `dict`-like methods,
such as `keys`, `values`, `items`, `iteritems`, `iterkeys`, and
`itervalues`. ``Config`` instances also support the ``in`` operator to
test if a field is in the config. Unlike a `dict`, ``Config`` classes are
not subscriptable. Instead, access individual fields as attributes of the
configuration instance.

Examples
--------
Config classes are subclasses of ``Config`` that have
`~lsst.pex.config.Field` instances (or instances of
`~lsst.pex.config.Field` subclasses) as class attributes:

>>> from lsst.pex.config import Config, Field, ListField
>>> class DemoConfig(Config):
...     intField = Field(doc="An integer field", dtype=int, default=42)
...     listField = ListField(doc="List of favorite beverages.", dtype=str,
...                           default=['coffee', 'green tea', 'water'])
...
>>> config = DemoConfig()

Configs support many `dict`-like APIs:

>>> config.keys()
['intField', 'listField']
>>> 'intField' in config
True

Individual fields can be accessed as attributes of the configuration:

>>> config.intField
42
>>> config.listField.append('earl grey tea')
>>> print(config.listField)
['coffee', 'green tea', 'water', 'earl grey tea']

Definition at line 745 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.

    @param[in] name  field name to test for

Definition at line 886 of file config.py.

886  def __contains__(self, name):
887  """!Return True if the specified field exists in this config
888 
889  @param[in] name field name to test for
890  """
891  return self._storage.__contains__(name)
892 

◆ __delattr__()

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

Definition at line 1369 of file config.py.

1369  def __delattr__(self, attr, at=None, label="deletion"):
1370  if attr in self._fields:
1371  if at is None:
1372  at = getCallStack()
1373  self._fields[attr].__delete__(self, at=at, label=label)
1374  else:
1375  object.__delattr__(self, attr)
1376 
def getCallStack(skip=0)
Definition: callStack.py:175

◆ __eq__()

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

Definition at line 1377 of file config.py.

1377  def __eq__(self, other):
1378  if type(other) == type(self):
1379  for name in self._fields:
1380  thisValue = getattr(self, name)
1381  otherValue = getattr(other, name)
1382  if isinstance(thisValue, float) and math.isnan(thisValue):
1383  if not math.isnan(otherValue):
1384  return False
1385  elif thisValue != otherValue:
1386  return False
1387  return True
1388  return False
1389 
table::Key< int > type
Definition: Detector.cc:163

◆ __init_subclass__()

def lsst.pex.config.config.Config.__init_subclass__ (   cls,
**  kwargs 
)
Run initialization for every subclass.

Specifically registers the subclass with a YAML representer
and YAML constructor (if pyyaml is available)

Reimplemented in lsst.pipe.tasks.dataFrameActions._baseDataFrameActions.DataFrameAction.

Definition at line 1447 of file config.py.

1447  def __init_subclass__(cls, **kwargs):
1448  """Run initialization for every subclass.
1449 
1450  Specifically registers the subclass with a YAML representer
1451  and YAML constructor (if pyyaml is available)
1452  """
1453  super().__init_subclass__(**kwargs)
1454 
1455  if not yaml:
1456  return
1457 
1458  yaml.add_representer(cls, _yaml_config_representer)
1459 

◆ __iter__()

def lsst.pex.config.config.Config.__iter__ (   self)
Iterate over fields.

Definition at line 791 of file config.py.

791  def __iter__(self):
792  """Iterate over fields.
793  """
794  return self._fields.__iter__()
795 

◆ __ne__()

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

Definition at line 1390 of file config.py.

1390  def __ne__(self, other):
1391  return not self.__eq__(other)
1392 

◆ __new__()

def lsst.pex.config.config.Config.__new__ (   cls,
args,
**  kw 
)
Allocate a new `lsst.pex.config.Config` object.

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

This ensures that even if a derived `~lsst.pex.config.Config` class
implements ``__init__``, its author does not need to be concerned about
when or even the base ``Config.__init__`` should be called.

Definition at line 893 of file config.py.

893  def __new__(cls, *args, **kw):
894  """Allocate a new `lsst.pex.config.Config` object.
895 
896  In order to ensure that all Config object are always in a proper state
897  when handed to users or to derived `~lsst.pex.config.Config` classes,
898  some attributes are handled at allocation time rather than at
899  initialization.
900 
901  This ensures that even if a derived `~lsst.pex.config.Config` class
902  implements ``__init__``, its author does not need to be concerned about
903  when or even the base ``Config.__init__`` should be called.
904  """
905  name = kw.pop("__name", None)
906  at = kw.pop("__at", getCallStack())
907  # remove __label and ignore it
908  kw.pop("__label", "default")
909 
910  instance = object.__new__(cls)
911  instance._frozen = False
912  instance._name = name
913  instance._storage = {}
914  instance._history = {}
915  instance._imports = set()
916  # load up defaults
917  for field in instance._fields.values():
918  instance._history[field.name] = []
919  field.__set__(instance, field.default, at=at + [field.source], label="default")
920  # set custom default-overides
921  instance.setDefaults()
922  # set constructor overides
923  instance.update(__at=at, **kw)
924  return instance
925 
daf::base::PropertySet * set
Definition: fits.cc:912

◆ __reduce__()

def lsst.pex.config.config.Config.__reduce__ (   self)
Reduction for pickling (function with arguments to reproduce).

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

Definition at line 926 of file config.py.

926  def __reduce__(self):
927  """Reduction for pickling (function with arguments to reproduce).
928 
929  We need to condense and reconstitute the `~lsst.pex.config.Config`,
930  since it may contain lambdas (as the ``check`` elements) that cannot
931  be pickled.
932  """
933  # The stream must be in characters to match the API but pickle
934  # requires bytes
935  stream = io.StringIO()
936  self.saveToStream(stream)
937  return (unreduceConfig, (self.__class__, stream.getvalue().encode()))
938 
pybind11::bytes encode(Region const &self)
Encode a Region as a pybind11 bytes object.
Definition: utils.h:53

◆ __repr__()

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

Definition at line 1396 of file config.py.

1396  def __repr__(self):
1397  return "%s(%s)" % (
1398  _typeStr(self),
1399  ", ".join("%s=%r" % (k, v) for k, v in self.toDict().items() if v is not None)
1400  )
1401 
std::vector< SchemaItem< Flag > > * items

◆ __setattr__() [1/2]

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

Definition at line 189 of file config.py.

189  def __setattr__(cls, name, value):
190  if isinstance(value, Field):
191  value.name = name
192  cls._fields[name] = value
193  type.__setattr__(cls, name, value)
194 
195 

◆ __setattr__() [2/2]

def lsst.pex.config.config.Config.__setattr__ (   self,
  attr,
  value,
  at = None,
  label = "assignment" 
)
Set an attribute (such as a field's value).

Notes
-----
Unlike normal Python objects, `~lsst.pex.config.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 1337 of file config.py.

1337  def __setattr__(self, attr, value, at=None, label="assignment"):
1338  """Set an attribute (such as a field's value).
1339 
1340  Notes
1341  -----
1342  Unlike normal Python objects, `~lsst.pex.config.Config` objects are
1343  locked such that no additional attributes nor properties may be added
1344  to them dynamically.
1345 
1346  Although this is not the standard Python behavior, it helps to protect
1347  users from accidentally mispelling a field name, or trying to set a
1348  non-existent field.
1349  """
1350  if attr in self._fields:
1351  if self._fields[attr].deprecated is not None:
1352  fullname = _joinNamePath(self._name, self._fields[attr].name)
1353  warnings.warn(f"Config field {fullname} is deprecated: {self._fields[attr].deprecated}",
1354  FutureWarning, stacklevel=2)
1355  if at is None:
1356  at = getCallStack()
1357  # This allows Field descriptors to work.
1358  self._fields[attr].__set__(self, value, at=at, label=label)
1359  elif hasattr(getattr(self.__class__, attr, None), '__set__'):
1360  # This allows properties and other non-Field descriptors to work.
1361  return object.__setattr__(self, attr, value)
1362  elif attr in self.__dict__ or attr in ("_name", "_history", "_storage", "_frozen", "_imports"):
1363  # This allows specific private attributes to work.
1364  self.__dict__[attr] = value
1365  else:
1366  # We throw everything else.
1367  raise AttributeError("%s has no attribute %s" % (_typeStr(self), attr))
1368 

◆ __str__()

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

Definition at line 1393 of file config.py.

1393  def __str__(self):
1394  return str(self.toDict())
1395 

◆ compare()

def lsst.pex.config.config.Config.compare (   self,
  other,
  shortcut = True,
  rtol = 1E-8,
  atol = 1E-8,
  output = None 
)
Compare this configuration to another `~lsst.pex.config.Config` for
equality.

Parameters
----------
other : `lsst.pex.config.Config`
    Other `~lsst.pex.config.Config` object to compare against this
    config.
shortcut : `bool`, optional
    If `True`, return as soon as an inequality is found. Default is
    `True`.
rtol : `float`, optional
    Relative tolerance for floating point comparisons.
atol : `float`, optional
    Absolute tolerance for floating point comparisons.
output : callable, optional
    A callable that takes a string, used (possibly repeatedly) to
    report inequalities.

Returns
-------
isEqual : `bool`
    `True` when the two `lsst.pex.config.Config` instances are equal.
    `False` if there is an inequality.

See also
--------
lsst.pex.config.compareConfigs

Notes
-----
Unselected targets of `~lsst.pex.config.RegistryField` fields and
unselected choices of `~lsst.pex.config.ConfigChoiceField` fields
are not considered by this method.

Floating point comparisons are performed by `numpy.allclose`.

Definition at line 1402 of file config.py.

1402  def compare(self, other, shortcut=True, rtol=1E-8, atol=1E-8, output=None):
1403  """Compare this configuration to another `~lsst.pex.config.Config` for
1404  equality.
1405 
1406  Parameters
1407  ----------
1408  other : `lsst.pex.config.Config`
1409  Other `~lsst.pex.config.Config` object to compare against this
1410  config.
1411  shortcut : `bool`, optional
1412  If `True`, return as soon as an inequality is found. Default is
1413  `True`.
1414  rtol : `float`, optional
1415  Relative tolerance for floating point comparisons.
1416  atol : `float`, optional
1417  Absolute tolerance for floating point comparisons.
1418  output : callable, optional
1419  A callable that takes a string, used (possibly repeatedly) to
1420  report inequalities.
1421 
1422  Returns
1423  -------
1424  isEqual : `bool`
1425  `True` when the two `lsst.pex.config.Config` instances are equal.
1426  `False` if there is an inequality.
1427 
1428  See also
1429  --------
1430  lsst.pex.config.compareConfigs
1431 
1432  Notes
1433  -----
1434  Unselected targets of `~lsst.pex.config.RegistryField` fields and
1435  unselected choices of `~lsst.pex.config.ConfigChoiceField` fields
1436  are not considered by this method.
1437 
1438  Floating point comparisons are performed by `numpy.allclose`.
1439  """
1440  name1 = self._name if self._name is not None else "config"
1441  name2 = other._name if other._name is not None else "config"
1442  name = getComparisonName(name1, name2)
1443  return compareConfigs(name, self, other, shortcut=shortcut,
1444  rtol=rtol, atol=atol, output=output)
1445 
def compareConfigs(name, c1, c2, shortcut=True, rtol=1E-8, atol=1E-8, output=None)
Definition: comparison.py:111
def getComparisonName(name1, name2)
Definition: comparison.py:40

◆ formatHistory()

def lsst.pex.config.config.Config.formatHistory (   self,
  name,
**  kwargs 
)
Format a configuration field's history to a human-readable format.

Parameters
----------
name : `str`
    Name of a `~lsst.pex.config.Field` in this config.
kwargs
    Keyword arguments passed to `lsst.pex.config.history.format`.

Returns
-------
history : `str`
    A string containing the formatted history.

See also
--------
lsst.pex.config.history.format

Definition at line 1311 of file config.py.

1311  def formatHistory(self, name, **kwargs):
1312  """Format a configuration field's history to a human-readable format.
1313 
1314  Parameters
1315  ----------
1316  name : `str`
1317  Name of a `~lsst.pex.config.Field` in this config.
1318  kwargs
1319  Keyword arguments passed to `lsst.pex.config.history.format`.
1320 
1321  Returns
1322  -------
1323  history : `str`
1324  A string containing the formatted history.
1325 
1326  See also
1327  --------
1328  lsst.pex.config.history.format
1329  """
1330  import lsst.pex.config.history as pexHist
1331  return pexHist.format(self, name, **kwargs)
1332 

◆ freeze()

def lsst.pex.config.config.Config.freeze (   self)
Make this config, and all subconfigs, read-only.

Definition at line 1177 of file config.py.

1177  def freeze(self):
1178  """Make this config, and all subconfigs, read-only.
1179  """
1180  self._frozen = True
1181  for field in self._fields.values():
1182  field.freeze(self)
1183 

◆ items()

def lsst.pex.config.config.Config.items (   self)
Get configurations as ``(field name, field value)`` pairs.

Returns
-------
items : `list`
    List of tuples for each configuration. Tuple items are:

    0. Field name.
    1. Field value.

See also
--------
lsst.pex.config.Config.iteritems

Definition at line 824 of file config.py.

824  def items(self):
825  """Get configurations as ``(field name, field value)`` pairs.
826 
827  Returns
828  -------
829  items : `list`
830  List of tuples for each configuration. Tuple items are:
831 
832  0. Field name.
833  1. Field value.
834 
835  See also
836  --------
837  lsst.pex.config.Config.iteritems
838  """
839  return list(self._storage.items())
840 
daf::base::PropertyList * list
Definition: fits.cc:913

◆ iteritems()

def lsst.pex.config.config.Config.iteritems (   self)
Iterate over (field name, field value) pairs.

Yields
------
item : `tuple`
    Tuple items are:

    0. Field name.
    1. Field value.

See also
--------
lsst.pex.config.Config.items

Definition at line 841 of file config.py.

841  def iteritems(self):
842  """Iterate over (field name, field value) pairs.
843 
844  Yields
845  ------
846  item : `tuple`
847  Tuple items are:
848 
849  0. Field name.
850  1. Field value.
851 
852  See also
853  --------
854  lsst.pex.config.Config.items
855  """
856  return iter(self._storage.items())
857 

◆ iterkeys()

def lsst.pex.config.config.Config.iterkeys (   self)
Iterate over field names

Yields
------
key : `str`
    A field's key (attribute name).

See also
--------
lsst.pex.config.Config.values

Definition at line 872 of file config.py.

872  def iterkeys(self):
873  """Iterate over field names
874 
875  Yields
876  ------
877  key : `str`
878  A field's key (attribute name).
879 
880  See also
881  --------
882  lsst.pex.config.Config.values
883  """
884  return iter(self.storage.keys())
885 

◆ itervalues()

def lsst.pex.config.config.Config.itervalues (   self)
Iterate over field values.

Yields
------
value : obj
    A field value.

See also
--------
lsst.pex.config.Config.values

Definition at line 858 of file config.py.

858  def itervalues(self):
859  """Iterate over field values.
860 
861  Yields
862  ------
863  value : obj
864  A field value.
865 
866  See also
867  --------
868  lsst.pex.config.Config.values
869  """
870  return iter(self.storage.values())
871 

◆ keys()

def lsst.pex.config.config.Config.keys (   self)
Get field names.

Returns
-------
names : `list`
    List of `lsst.pex.config.Field` names.

See also
--------
lsst.pex.config.Config.iterkeys

Definition at line 796 of file config.py.

796  def keys(self):
797  """Get field names.
798 
799  Returns
800  -------
801  names : `list`
802  List of `lsst.pex.config.Field` names.
803 
804  See also
805  --------
806  lsst.pex.config.Config.iterkeys
807  """
808  return list(self._storage.keys())
809 

◆ load()

def lsst.pex.config.config.Config.load (   self,
  filename,
  root = "config" 
)
Modify this config in place by executing the Python code in a
configuration file.

Parameters
----------
filename : `str`
    Name of the configuration file. A configuration file is Python
    module.
root : `str`, optional
    Name of the variable in file that refers to the config being
    overridden.

    For example, the value of root is ``"config"`` and the file
    contains::

        config.myField = 5

    Then this config's field ``myField`` is set to ``5``.

    **Deprecated:** For 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.

See also
--------
lsst.pex.config.Config.loadFromStream
lsst.pex.config.Config.save
lsst.pex.config.Config.saveFromStream

Definition at line 1012 of file config.py.

1012  def load(self, filename, root="config"):
1013  """Modify this config in place by executing the Python code in a
1014  configuration file.
1015 
1016  Parameters
1017  ----------
1018  filename : `str`
1019  Name of the configuration file. A configuration file is Python
1020  module.
1021  root : `str`, optional
1022  Name of the variable in file that refers to the config being
1023  overridden.
1024 
1025  For example, the value of root is ``"config"`` and the file
1026  contains::
1027 
1028  config.myField = 5
1029 
1030  Then this config's field ``myField`` is set to ``5``.
1031 
1032  **Deprecated:** For backwards compatibility, older config files
1033  that use ``root="root"`` instead of ``root="config"`` will be
1034  loaded with a warning printed to `sys.stderr`. This feature will be
1035  removed at some point.
1036 
1037  See also
1038  --------
1039  lsst.pex.config.Config.loadFromStream
1040  lsst.pex.config.Config.save
1041  lsst.pex.config.Config.saveFromStream
1042  """
1043  with open(filename, "r") as f:
1044  code = compile(f.read(), filename=filename, mode="exec")
1045  self.loadFromStream(stream=code, root=root, filename=filename)
1046 

◆ 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
----------
stream : file-like object, `str`, or compiled string
    Stream containing configuration override code.
root : `str`, optional
    Name of the variable in file that refers to the config being
    overridden.

    For example, the value of root is ``"config"`` and the file
    contains::

        config.myField = 5

    Then this config's field ``myField`` is set to ``5``.

    **Deprecated:** For 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.
filename : `str`, optional
    Name of the configuration file, or `None` if unknown or contained
    in the stream. Used for error reporting.

See also
--------
lsst.pex.config.Config.load
lsst.pex.config.Config.save
lsst.pex.config.Config.saveFromStream

Definition at line 1047 of file config.py.

1047  def loadFromStream(self, stream, root="config", filename=None):
1048  """Modify this Config in place by executing the Python code in the
1049  provided stream.
1050 
1051  Parameters
1052  ----------
1053  stream : file-like object, `str`, or compiled string
1054  Stream containing configuration override code.
1055  root : `str`, optional
1056  Name of the variable in file that refers to the config being
1057  overridden.
1058 
1059  For example, the value of root is ``"config"`` and the file
1060  contains::
1061 
1062  config.myField = 5
1063 
1064  Then this config's field ``myField`` is set to ``5``.
1065 
1066  **Deprecated:** For backwards compatibility, older config files
1067  that use ``root="root"`` instead of ``root="config"`` will be
1068  loaded with a warning printed to `sys.stderr`. This feature will be
1069  removed at some point.
1070  filename : `str`, optional
1071  Name of the configuration file, or `None` if unknown or contained
1072  in the stream. Used for error reporting.
1073 
1074  See also
1075  --------
1076  lsst.pex.config.Config.load
1077  lsst.pex.config.Config.save
1078  lsst.pex.config.Config.saveFromStream
1079  """
1080  with RecordingImporter() as importer:
1081  globals = {"__file__": filename}
1082  try:
1083  local = {root: self}
1084  exec(stream, globals, local)
1085  except NameError as e:
1086  if root == "config" and "root" in e.args[0]:
1087  if filename is None:
1088  # try to determine the file name; a compiled string
1089  # has attribute "co_filename",
1090  # an open file has attribute "name", else give up
1091  filename = getattr(stream, "co_filename", None)
1092  if filename is None:
1093  filename = getattr(stream, "name", "?")
1094  print(f"Config override file {filename!r}"
1095  " appears to use 'root' instead of 'config'; trying with 'root'", file=sys.stderr)
1096  local = {"root": self}
1097  exec(stream, globals, local)
1098  else:
1099  raise
1100 
1101  self._imports.update(importer.getModules())
1102 

◆ names()

def lsst.pex.config.config.Config.names (   self)
Get all the field names in the config, recursively.

Returns
-------
names : `list` of `str`
    Field names.

Definition at line 1232 of file config.py.

1232  def names(self):
1233  """Get all the field names in the config, recursively.
1234 
1235  Returns
1236  -------
1237  names : `list` of `str`
1238  Field names.
1239  """
1240  #
1241  # Rather than sort out the recursion all over again use the
1242  # pre-existing saveToStream()
1243  #
1244  with io.StringIO() as strFd:
1245  self.saveToStream(strFd, "config")
1246  contents = strFd.getvalue()
1247  strFd.close()
1248  #
1249  # Pull the names out of the dumped config
1250  #
1251  keys = []
1252  for line in contents.split("\n"):
1253  if re.search(r"^((assert|import)\s+|\s*$|#)", line):
1254  continue
1255 
1256  mat = re.search(r"^(?:config\.)?([^=]+)\s*=\s*.*", line)
1257  if mat:
1258  keys.append(mat.group(1))
1259 
1260  return keys
1261 

◆ 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
----------
filename : `str`
    Desination filename of this configuration.
root : `str`, optional
    Name to use for the root config variable. The same value must be
    used when loading (see `lsst.pex.config.Config.load`).

See also
--------
lsst.pex.config.Config.saveToStream
lsst.pex.config.Config.load
lsst.pex.config.Config.loadFromStream

Definition at line 1103 of file config.py.

1103  def save(self, filename, root="config"):
1104  """Save a Python script to the named file, which, when loaded,
1105  reproduces this config.
1106 
1107  Parameters
1108  ----------
1109  filename : `str`
1110  Desination filename of this configuration.
1111  root : `str`, optional
1112  Name to use for the root config variable. The same value must be
1113  used when loading (see `lsst.pex.config.Config.load`).
1114 
1115  See also
1116  --------
1117  lsst.pex.config.Config.saveToStream
1118  lsst.pex.config.Config.load
1119  lsst.pex.config.Config.loadFromStream
1120  """
1121  d = os.path.dirname(filename)
1122  with tempfile.NamedTemporaryFile(mode="w", delete=False, dir=d) as outfile:
1123  self.saveToStream(outfile, root)
1124  # tempfile is hardcoded to create files with mode '0600'
1125  # for an explantion of these antics see:
1126  # https://stackoverflow.com/questions/10291131/how-to-use-os-umask-in-python
1127  umask = os.umask(0o077)
1128  os.umask(umask)
1129  os.chmod(outfile.name, (~umask & 0o666))
1130  # chmod before the move so we get quasi-atomic behavior if the
1131  # source and dest. are on the same filesystem.
1132  # os.rename may not work across filesystems
1133  shutil.move(outfile.name, filename)
1134 

◆ saveToStream()

def lsst.pex.config.config.Config.saveToStream (   self,
  outfile,
  root = "config",
  skipImports = False 
)
Save a configuration file to a stream, which, when loaded,
reproduces this config.

Parameters
----------
outfile : file-like object
    Destination file object write the config into. Accepts strings not
    bytes.
root
    Name to use for the root config variable. The same value must be
    used when loading (see `lsst.pex.config.Config.load`).
skipImports : `bool`, optional
    If `True` then do not include ``import`` statements in output,
    this is to support human-oriented output from ``pipetask`` where
    additional clutter is not useful.

See also
--------
lsst.pex.config.Config.save
lsst.pex.config.Config.load
lsst.pex.config.Config.loadFromStream

Definition at line 1135 of file config.py.

1135  def saveToStream(self, outfile, root="config", skipImports=False):
1136  """Save a configuration file to a stream, which, when loaded,
1137  reproduces this config.
1138 
1139  Parameters
1140  ----------
1141  outfile : file-like object
1142  Destination file object write the config into. Accepts strings not
1143  bytes.
1144  root
1145  Name to use for the root config variable. The same value must be
1146  used when loading (see `lsst.pex.config.Config.load`).
1147  skipImports : `bool`, optional
1148  If `True` then do not include ``import`` statements in output,
1149  this is to support human-oriented output from ``pipetask`` where
1150  additional clutter is not useful.
1151 
1152  See also
1153  --------
1154  lsst.pex.config.Config.save
1155  lsst.pex.config.Config.load
1156  lsst.pex.config.Config.loadFromStream
1157  """
1158  tmp = self._name
1159  self._rename(root)
1160  try:
1161  if not skipImports:
1162  self._collectImports()
1163  # Remove self from the set, as it is handled explicitly below
1164  self._imports.remove(self.__module__)
1165  configType = type(self)
1166  typeString = _typeStr(configType)
1167  outfile.write(f"import {configType.__module__}\n")
1168  outfile.write(f"assert type({root})=={typeString}, 'config is of type %s.%s instead of "
1169  f"{typeString}' % (type({root}).__module__, type({root}).__name__)\n")
1170  for imp in self._imports:
1171  if imp in sys.modules and sys.modules[imp] is not None:
1172  outfile.write(u"import {}\n".format(imp))
1173  self._save(outfile)
1174  finally:
1175  self._rename(tmp)
1176 
def format(config, name=None, writeSourceLine=True, prefix="", verbose=False)
Definition: history.py:174

◆ setDefaults()

def lsst.pex.config.config.Config.setDefaults (   self)
Subclass hook for computing defaults.

Notes
-----
Derived `~lsst.pex.config.Config` classes that must compute defaults
rather than using the `~lsst.pex.config.Field` instances's defaults
should do so here. To correctly use inherited defaults,
implementations of ``setDefaults`` must call their base class's
``setDefaults``.

Reimplemented in lsst.pipe.tasks.scaleVariance.ScaleVarianceConfig, lsst.pipe.tasks.mocks.mockCoadd.MockCoaddConfig, lsst.pipe.tasks.ingestCuratedCalibs.IngestCuratedCalibsConfig, lsst.pipe.tasks.dataFrameActions._actions.NanoJansky, lsst.pipe.drivers.multiBandDriver.MultiBandDriverConfig, lsst.pipe.drivers.constructCalibs.FringeConfig, lsst.pipe.drivers.constructCalibs.DarkConfig, lsst.pipe.drivers.constructCalibs.CalibConfig, lsst.pipe.drivers.coaddDriver.CoaddDriverConfig, lsst.pipe.drivers.background.MaskObjectsConfig, lsst.meas.modelfit.psf.psfContinued.GeneralShapeletPsfApproxForcedConfig, lsst.meas.modelfit.psf.psfContinued.GeneralShapeletPsfApproxSingleFrameConfig, lsst.meas.modelfit.cmodel.cmodelContinued.CModelForcedConfig, lsst.meas.modelfit.cmodel.cmodelContinued.CModelSingleFrameConfig, lsst.meas.base.forcedMeasurement.ForcedMeasurementConfig, and lsst.ip.diffim.dipoleMeasurement.DipoleMeasurementConfig.

Definition at line 939 of file config.py.

939  def setDefaults(self):
940  """Subclass hook for computing defaults.
941 
942  Notes
943  -----
944  Derived `~lsst.pex.config.Config` classes that must compute defaults
945  rather than using the `~lsst.pex.config.Field` instances's defaults
946  should do so here. To correctly use inherited defaults,
947  implementations of ``setDefaults`` must call their base class's
948  ``setDefaults``.
949  """
950  pass
951 

◆ toDict()

def lsst.pex.config.config.Config.toDict (   self)
Make a dictionary of field names and their values.

Returns
-------
dict_ : `dict`
    Dictionary with keys that are `~lsst.pex.config.Field` names.
    Values are `~lsst.pex.config.Field` values.

See also
--------
lsst.pex.config.Field.toDict

Notes
-----
This method uses the `~lsst.pex.config.Field.toDict` method of
individual fields. Subclasses of `~lsst.pex.config.Field` may need to
implement a ``toDict`` method for *this* method to work.

Definition at line 1208 of file config.py.

1208  def toDict(self):
1209  """Make a dictionary of field names and their values.
1210 
1211  Returns
1212  -------
1213  dict_ : `dict`
1214  Dictionary with keys that are `~lsst.pex.config.Field` names.
1215  Values are `~lsst.pex.config.Field` values.
1216 
1217  See also
1218  --------
1219  lsst.pex.config.Field.toDict
1220 
1221  Notes
1222  -----
1223  This method uses the `~lsst.pex.config.Field.toDict` method of
1224  individual fields. Subclasses of `~lsst.pex.config.Field` may need to
1225  implement a ``toDict`` method for *this* method to work.
1226  """
1227  dict_ = {}
1228  for name, field in self._fields.items():
1229  dict_[name] = field.toDict(self)
1230  return dict_
1231 

◆ update()

def lsst.pex.config.config.Config.update (   self,
**  kw 
)
Update values of fields specified by the keyword arguments.

Parameters
----------
kw
    Keywords are configuration field names. Values are configuration
    field values.

Notes
-----
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. Do not modify these keywords to
subvert a `~lsst.pex.config.Config` instance's history.

Examples
--------
This is a config with three fields:

>>> from lsst.pex.config import Config, Field
>>> class DemoConfig(Config):
...     fieldA = Field(doc='Field A', dtype=int, default=42)
...     fieldB = Field(doc='Field B', dtype=bool, default=True)
...     fieldC = Field(doc='Field C', dtype=str, default='Hello world')
...
>>> config = DemoConfig()

These are the default values of each field:

>>> for name, value in config.iteritems():
...     print(f"{name}: {value}")
...
fieldA: 42
fieldB: True
fieldC: 'Hello world'

Using this method to update ``fieldA`` and ``fieldC``:

>>> config.update(fieldA=13, fieldC='Updated!')

Now the values of each field are:

>>> for name, value in config.iteritems():
...     print(f"{name}: {value}")
...
fieldA: 13
fieldB: True
fieldC: 'Updated!'

Definition at line 952 of file config.py.

952  def update(self, **kw):
953  """Update values of fields specified by the keyword arguments.
954 
955  Parameters
956  ----------
957  kw
958  Keywords are configuration field names. Values are configuration
959  field values.
960 
961  Notes
962  -----
963  The ``__at`` and ``__label`` keyword arguments are special internal
964  keywords. They are used to strip out any internal steps from the
965  history tracebacks of the config. Do not modify these keywords to
966  subvert a `~lsst.pex.config.Config` instance's history.
967 
968  Examples
969  --------
970  This is a config with three fields:
971 
972  >>> from lsst.pex.config import Config, Field
973  >>> class DemoConfig(Config):
974  ... fieldA = Field(doc='Field A', dtype=int, default=42)
975  ... fieldB = Field(doc='Field B', dtype=bool, default=True)
976  ... fieldC = Field(doc='Field C', dtype=str, default='Hello world')
977  ...
978  >>> config = DemoConfig()
979 
980  These are the default values of each field:
981 
982  >>> for name, value in config.iteritems():
983  ... print(f"{name}: {value}")
984  ...
985  fieldA: 42
986  fieldB: True
987  fieldC: 'Hello world'
988 
989  Using this method to update ``fieldA`` and ``fieldC``:
990 
991  >>> config.update(fieldA=13, fieldC='Updated!')
992 
993  Now the values of each field are:
994 
995  >>> for name, value in config.iteritems():
996  ... print(f"{name}: {value}")
997  ...
998  fieldA: 13
999  fieldB: True
1000  fieldC: 'Updated!'
1001  """
1002  at = kw.pop("__at", getCallStack())
1003  label = kw.pop("__label", "update")
1004 
1005  for name, value in kw.items():
1006  try:
1007  field = self._fields[name]
1008  field.__set__(self, value, at=at, label=label)
1009  except KeyError:
1010  raise KeyError("No field of name %s exists in config type %s" % (name, _typeStr(self)))
1011 

◆ validate()

def lsst.pex.config.config.Config.validate (   self)
Validate the Config, raising an exception if invalid.

Raises
------
lsst.pex.config.FieldValidationError
    Raised if verification fails.

Notes
-----
The base class implementation performs type checks on all fields by
calling their `~lsst.pex.config.Field.validate` methods.

Complex single-field validation can be defined by deriving new Field
types. For convenience, some derived `lsst.pex.config.Field`-types
(`~lsst.pex.config.ConfigField` and
`~lsst.pex.config.ConfigChoiceField`) are defined in `lsst.pex.config`
that handle recursing into subconfigs.

Inter-field relationships should only be checked in derived
`~lsst.pex.config.Config` classes after calling this method, and base
validation is complete.

Reimplemented in lsst.pipe.drivers.multiBandDriver.MultiBandDriverConfig, lsst.pipe.drivers.coaddDriver.CoaddDriverConfig, lsst.pipe.drivers.background.MaskObjectsConfig, lsst.meas.base.baseMeasurement.BaseMeasurementConfig, lsst.meas.algorithms.measureApCorr.MeasureApCorrConfig, lsst.meas.algorithms.gaussianPsfFactory.GaussianPsfFactory, lsst.fgcmcal.sedterms.Sedterm, lsst.dax.apdb.apdbSql.ApdbSqlConfig, and lsst.afw.geom.transformConfig.RadialTransformConfig.

Definition at line 1285 of file config.py.

1285  def validate(self):
1286  """Validate the Config, raising an exception if invalid.
1287 
1288  Raises
1289  ------
1290  lsst.pex.config.FieldValidationError
1291  Raised if verification fails.
1292 
1293  Notes
1294  -----
1295  The base class implementation performs type checks on all fields by
1296  calling their `~lsst.pex.config.Field.validate` methods.
1297 
1298  Complex single-field validation can be defined by deriving new Field
1299  types. For convenience, some derived `lsst.pex.config.Field`-types
1300  (`~lsst.pex.config.ConfigField` and
1301  `~lsst.pex.config.ConfigChoiceField`) are defined in `lsst.pex.config`
1302  that handle recursing into subconfigs.
1303 
1304  Inter-field relationships should only be checked in derived
1305  `~lsst.pex.config.Config` classes after calling this method, and base
1306  validation is complete.
1307  """
1308  for field in self._fields.values():
1309  field.validate(self)
1310 

◆ values()

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

Returns
-------
values : `list`
    List of field values.

See also
--------
lsst.pex.config.Config.itervalues

Definition at line 810 of file config.py.

810  def values(self):
811  """Get field values.
812 
813  Returns
814  -------
815  values : `list`
816  List of field values.
817 
818  See also
819  --------
820  lsst.pex.config.Config.itervalues
821  """
822  return list(self._storage.values())
823 

Property Documentation

◆ history

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

Definition at line 1333 of file config.py.


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