LSSTApplications  17.0,17.0+1,17.0+10,17.0+13,17.0+6,17.0+9,17.0-1-g377950a+5,17.0.1,17.0.1-1-g0d345a5+1,17.0.1-1-g444bd44+1,17.0.1-1-g46e6382+1,17.0.1-1-g4d4fbc4,17.0.1-1-g703d48b+1,17.0.1-1-g9deacb5+1,17.0.1-1-gaef33af,17.0.1-1-gea52513+1,17.0.1-1-gf4e0155+1,17.0.1-1-gfc65f5f+1,17.0.1-1-gfc6fb1f,17.0.1-2-g0ce9737+1,17.0.1-2-g2a2f1b99+1,17.0.1-2-gd73ec07+1,17.0.1-2-gd9aa6e4+1,17.0.1-3-g18e75bb+1,17.0.1-3-gb71a564+1,17.0.1-3-gc20ba7d+1,17.0.1-4-g41c8d5dc0+1,17.0.1-5-gb7d1e01,17.0.1-5-gf0ac6446+1,17.0.1-7-g69836a1
LSSTDataManagementBasePackage
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.ip.isr.crosstalk.CrosstalkConfig lsst.ip.isr.fringe.FringeConfig lsst.ip.isr.fringe.FringeStatisticsConfig lsst.ip.isr.masking.MaskingConfig lsst.ip.isr.measureCrosstalk.MeasureCrosstalkConfig lsst.ip.isr.straylight.StrayLightConfig lsst.ip.isr.vignette.VignetteConfig lsst.meas.algorithms.debugger.MeasurementDebuggerConfig 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.obs.base.gen3.ingest.RawIngestConfig lsst.pipe.drivers.background.BackgroundConfig lsst.pipe.drivers.background.FocalPlaneBackgroundConfig 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.singleFrameDriver.SingleFrameDriverConfig lsst.pipe.drivers.skyCorrection.SkyCorrectionConfig lsst.pipe.drivers.visualizeVisit.VisualizeVisitConfig lsst.pipe.tasks.colorterms.Colorterm lsst.pipe.tasks.colorterms.ColortermDict lsst.pipe.tasks.colorterms.ColortermLibrary 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.multiBand.DeblendCoaddSourcesConfig 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")
 
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 __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 653 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 794 of file config.py.

794  def __contains__(self, name):
795  """!Return True if the specified field exists in this config
796 
797  @param[in] name field name to test for
798  """
799  return self._storage.__contains__(name)
800 

◆ __delattr__()

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

Definition at line 1266 of file config.py.

1266  def __delattr__(self, attr, at=None, label="deletion"):
1267  if attr in self._fields:
1268  if at is None:
1269  at = getCallStack()
1270  self._fields[attr].__delete__(self, at=at, label=label)
1271  else:
1272  object.__delattr__(self, attr)
1273 
def getCallStack(skip=0)
Definition: callStack.py:169

◆ __eq__()

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

Definition at line 1274 of file config.py.

1274  def __eq__(self, other):
1275  if type(other) == type(self):
1276  for name in self._fields:
1277  thisValue = getattr(self, name)
1278  otherValue = getattr(other, name)
1279  if isinstance(thisValue, float) and math.isnan(thisValue):
1280  if not math.isnan(otherValue):
1281  return False
1282  elif thisValue != otherValue:
1283  return False
1284  return True
1285  return False
1286 
table::Key< int > type
Definition: Detector.cc:164

◆ __iter__()

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

Definition at line 699 of file config.py.

699  def __iter__(self):
700  """Iterate over fields.
701  """
702  return self._fields.__iter__()
703 

◆ __ne__()

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

Definition at line 1287 of file config.py.

1287  def __ne__(self, other):
1288  return not self.__eq__(other)
1289 

◆ __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 801 of file config.py.

801  def __new__(cls, *args, **kw):
802  """Allocate a new `lsst.pex.config.Config` object.
803 
804  In order to ensure that all Config object are always in a proper state
805  when handed to users or to derived `~lsst.pex.config.Config` classes,
806  some attributes are handled at allocation time rather than at
807  initialization.
808 
809  This ensures that even if a derived `~lsst.pex.config.Config` class
810  implements ``__init__``, its author does not need to be concerned about
811  when or even the base ``Config.__init__`` should be called.
812  """
813  name = kw.pop("__name", None)
814  at = kw.pop("__at", getCallStack())
815  # remove __label and ignore it
816  kw.pop("__label", "default")
817 
818  instance = object.__new__(cls)
819  instance._frozen = False
820  instance._name = name
821  instance._storage = {}
822  instance._history = {}
823  instance._imports = set()
824  # load up defaults
825  for field in instance._fields.values():
826  instance._history[field.name] = []
827  field.__set__(instance, field.default, at=at + [field.source], label="default")
828  # set custom default-overides
829  instance.setDefaults()
830  # set constructor overides
831  instance.update(__at=at, **kw)
832  return instance
833 
daf::base::PropertySet * set
Definition: fits.cc:832
def getCallStack(skip=0)
Definition: callStack.py:169

◆ __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 834 of file config.py.

834  def __reduce__(self):
835  """Reduction for pickling (function with arguments to reproduce).
836 
837  We need to condense and reconstitute the `~lsst.pex.config.Config`,
838  since it may contain lambdas (as the ``check`` elements) that cannot
839  be pickled.
840  """
841  # The stream must be in characters to match the API but pickle requires bytes
842  stream = io.StringIO()
843  self.saveToStream(stream)
844  return (unreduceConfig, (self.__class__, stream.getvalue().encode()))
845 

◆ __repr__()

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

Definition at line 1293 of file config.py.

1293  def __repr__(self):
1294  return "%s(%s)" % (
1295  _typeStr(self),
1296  ", ".join("%s=%r" % (k, v) for k, v in self.toDict().items() if v is not None)
1297  )
1298 
std::vector< SchemaItem< Flag > > * items

◆ __setattr__() [1/2]

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

Definition at line 130 of file config.py.

130  def __setattr__(cls, name, value):
131  if isinstance(value, Field):
132  value.name = name
133  cls._fields[name] = value
134  type.__setattr__(cls, name, value)
135 
136 

◆ __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 1238 of file config.py.

1238  def __setattr__(self, attr, value, at=None, label="assignment"):
1239  """Set an attribute (such as a field's value).
1240 
1241  Notes
1242  -----
1243  Unlike normal Python objects, `~lsst.pex.config.Config` objects are
1244  locked such that no additional attributes nor properties may be added
1245  to them dynamically.
1246 
1247  Although this is not the standard Python behavior, it helps to protect
1248  users from accidentally mispelling a field name, or trying to set a
1249  non-existent field.
1250  """
1251  if attr in self._fields:
1252  if at is None:
1253  at = getCallStack()
1254  # This allows Field descriptors to work.
1255  self._fields[attr].__set__(self, value, at=at, label=label)
1256  elif hasattr(getattr(self.__class__, attr, None), '__set__'):
1257  # This allows properties and other non-Field descriptors to work.
1258  return object.__setattr__(self, attr, value)
1259  elif attr in self.__dict__ or attr in ("_name", "_history", "_storage", "_frozen", "_imports"):
1260  # This allows specific private attributes to work.
1261  self.__dict__[attr] = value
1262  else:
1263  # We throw everything else.
1264  raise AttributeError("%s has no attribute %s" % (_typeStr(self), attr))
1265 
def getCallStack(skip=0)
Definition: callStack.py:169

◆ __str__()

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

Definition at line 1290 of file config.py.

1290  def __str__(self):
1291  return str(self.toDict())
1292 

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

1299  def compare(self, other, shortcut=True, rtol=1E-8, atol=1E-8, output=None):
1300  """Compare this configuration to another `~lsst.pex.config.Config` for
1301  equality.
1302 
1303  Parameters
1304  ----------
1305  other : `lsst.pex.config.Config`
1306  Other `~lsst.pex.config.Config` object to compare against this
1307  config.
1308  shortcut : `bool`, optional
1309  If `True`, return as soon as an inequality is found. Default is
1310  `True`.
1311  rtol : `float`, optional
1312  Relative tolerance for floating point comparisons.
1313  atol : `float`, optional
1314  Absolute tolerance for floating point comparisons.
1315  output : callable, optional
1316  A callable that takes a string, used (possibly repeatedly) to
1317  report inequalities.
1318 
1319  Returns
1320  -------
1321  isEqual : `bool`
1322  `True` when the two `lsst.pex.config.Config` instances are equal.
1323  `False` if there is an inequality.
1324 
1325  See also
1326  --------
1327  lsst.pex.config.compareConfigs
1328 
1329  Notes
1330  -----
1331  Unselected targets of `~lsst.pex.config.RegistryField` fields and
1332  unselected choices of `~lsst.pex.config.ConfigChoiceField` fields
1333  are not considered by this method.
1334 
1335  Floating point comparisons are performed by `numpy.allclose`.
1336  """
1337  name1 = self._name if self._name is not None else "config"
1338  name2 = other._name if other._name is not None else "config"
1339  name = getComparisonName(name1, name2)
1340  return compareConfigs(name, self, other, shortcut=shortcut,
1341  rtol=rtol, atol=atol, output=output)
1342 
1343 
def compareConfigs(name, c1, c2, shortcut=True, rtol=1E-8, atol=1E-8, output=None)
Definition: comparison.py:105
def getComparisonName(name1, name2)
Definition: comparison.py:34

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

1212  def formatHistory(self, name, **kwargs):
1213  """Format a configuration field's history to a human-readable format.
1214 
1215  Parameters
1216  ----------
1217  name : `str`
1218  Name of a `~lsst.pex.config.Field` in this config.
1219  kwargs
1220  Keyword arguments passed to `lsst.pex.config.history.format`.
1221 
1222  Returns
1223  -------
1224  history : `str`
1225  A string containing the formatted history.
1226 
1227  See also
1228  --------
1229  lsst.pex.config.history.format
1230  """
1231  import lsst.pex.config.history as pexHist
1232  return pexHist.format(self, name, **kwargs)
1233 

◆ freeze()

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

Definition at line 1079 of file config.py.

1079  def freeze(self):
1080  """Make this config, and all subconfigs, read-only.
1081  """
1082  self._frozen = True
1083  for field in self._fields.values():
1084  field.freeze(self)
1085 

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

732  def items(self):
733  """Get configurations as ``(field name, field value)`` pairs.
734 
735  Returns
736  -------
737  items : `list`
738  List of tuples for each configuration. Tuple items are:
739 
740  0. Field name.
741  1. Field value.
742 
743  See also
744  --------
745  lsst.pex.config.Config.iteritems
746  """
747  return list(self._storage.items())
748 
std::vector< SchemaItem< Flag > > * items
daf::base::PropertyList * list
Definition: fits.cc:833

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

749  def iteritems(self):
750  """Iterate over (field name, field value) pairs.
751 
752  Yields
753  ------
754  item : `tuple`
755  Tuple items are:
756 
757  0. Field name.
758  1. Field value.
759 
760  See also
761  --------
762  lsst.pex.config.Config.items
763  """
764  return iter(self._storage.items())
765 
std::vector< SchemaItem< Flag > > * items

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

780  def iterkeys(self):
781  """Iterate over field names
782 
783  Yields
784  ------
785  key : `str`
786  A field's key (attribute name).
787 
788  See also
789  --------
790  lsst.pex.config.Config.values
791  """
792  return iter(self.storage.keys())
793 

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

766  def itervalues(self):
767  """Iterate over field values.
768 
769  Yields
770  ------
771  value : obj
772  A field value.
773 
774  See also
775  --------
776  lsst.pex.config.Config.values
777  """
778  return iter(self.storage.values())
779 

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

704  def keys(self):
705  """Get field names.
706 
707  Returns
708  -------
709  names : `list`
710  List of `lsst.pex.config.Field` names.
711 
712  See also
713  --------
714  lsst.pex.config.Config.iterkeys
715  """
716  return list(self._storage.keys())
717 
daf::base::PropertyList * list
Definition: fits.cc:833

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

919  def load(self, filename, root="config"):
920  """Modify this config in place by executing the Python code in a
921  configuration file.
922 
923  Parameters
924  ----------
925  filename : `str`
926  Name of the configuration file. A configuration file is Python
927  module.
928  root : `str`, optional
929  Name of the variable in file that refers to the config being
930  overridden.
931 
932  For example, the value of root is ``"config"`` and the file
933  contains::
934 
935  config.myField = 5
936 
937  Then this config's field ``myField`` is set to ``5``.
938 
939  **Deprecated:** For backwards compatibility, older config files
940  that use ``root="root"`` instead of ``root="config"`` will be
941  loaded with a warning printed to `sys.stderr`. This feature will be
942  removed at some point.
943 
944  See also
945  --------
946  lsst.pex.config.Config.loadFromStream
947  lsst.pex.config.Config.save
948  lsst.pex.config.Config.saveFromStream
949  """
950  with open(filename, "r") as f:
951  code = compile(f.read(), filename=filename, mode="exec")
952  self.loadFromStream(stream=code, root=root)
953 

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

954  def loadFromStream(self, stream, root="config", filename=None):
955  """Modify this Config in place by executing the Python code in the
956  provided stream.
957 
958  Parameters
959  ----------
960  stream : file-like object, `str`, or compiled string
961  Stream containing configuration override code.
962  root : `str`, optional
963  Name of the variable in file that refers to the config being
964  overridden.
965 
966  For example, the value of root is ``"config"`` and the file
967  contains::
968 
969  config.myField = 5
970 
971  Then this config's field ``myField`` is set to ``5``.
972 
973  **Deprecated:** For backwards compatibility, older config files
974  that use ``root="root"`` instead of ``root="config"`` will be
975  loaded with a warning printed to `sys.stderr`. This feature will be
976  removed at some point.
977  filename : `str`, optional
978  Name of the configuration file, or `None` if unknown or contained
979  in the stream. Used for error reporting.
980 
981  See also
982  --------
983  lsst.pex.config.Config.load
984  lsst.pex.config.Config.save
985  lsst.pex.config.Config.saveFromStream
986  """
987  with RecordingImporter() as importer:
988  try:
989  local = {root: self}
990  exec(stream, {}, local)
991  except NameError as e:
992  if root == "config" and "root" in e.args[0]:
993  if filename is None:
994  # try to determine the file name; a compiled string has attribute "co_filename",
995  # an open file has attribute "name", else give up
996  filename = getattr(stream, "co_filename", None)
997  if filename is None:
998  filename = getattr(stream, "name", "?")
999  print(f"Config override file {filename!r}"
1000  " appears to use 'root' instead of 'config'; trying with 'root'", file=sys.stderr)
1001  local = {"root": self}
1002  exec(stream, {}, local)
1003  else:
1004  raise
1005 
1006  self._imports.update(importer.getModules())
1007 

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

1133  def names(self):
1134  """Get all the field names in the config, recursively.
1135 
1136  Returns
1137  -------
1138  names : `list` of `str`
1139  Field names.
1140  """
1141  #
1142  # Rather than sort out the recursion all over again use the
1143  # pre-existing saveToStream()
1144  #
1145  with io.StringIO() as strFd:
1146  self.saveToStream(strFd, "config")
1147  contents = strFd.getvalue()
1148  strFd.close()
1149  #
1150  # Pull the names out of the dumped config
1151  #
1152  keys = []
1153  for line in contents.split("\n"):
1154  if re.search(r"^((assert|import)\s+|\s*$|#)", line):
1155  continue
1156 
1157  mat = re.search(r"^(?:config\.)?([^=]+)\s*=\s*.*", line)
1158  if mat:
1159  keys.append(mat.group(1))
1160 
1161  return keys
1162 

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

1008  def save(self, filename, root="config"):
1009  """Save a Python script to the named file, which, when loaded,
1010  reproduces this config.
1011 
1012  Parameters
1013  ----------
1014  filename : `str`
1015  Desination filename of this configuration.
1016  root : `str`, optional
1017  Name to use for the root config variable. The same value must be
1018  used when loading (see `lsst.pex.config.Config.load`).
1019 
1020  See also
1021  --------
1022  lsst.pex.config.Config.saveToStream
1023  lsst.pex.config.Config.load
1024  lsst.pex.config.Config.loadFromStream
1025  """
1026  d = os.path.dirname(filename)
1027  with tempfile.NamedTemporaryFile(mode="w", delete=False, dir=d) as outfile:
1028  self.saveToStream(outfile, root)
1029  # tempfile is hardcoded to create files with mode '0600'
1030  # for an explantion of these antics see:
1031  # https://stackoverflow.com/questions/10291131/how-to-use-os-umask-in-python
1032  umask = os.umask(0o077)
1033  os.umask(umask)
1034  os.chmod(outfile.name, (~umask & 0o666))
1035  # chmod before the move so we get quasi-atomic behavior if the
1036  # source and dest. are on the same filesystem.
1037  # os.rename may not work across filesystems
1038  shutil.move(outfile.name, filename)
1039 

◆ saveToStream()

def lsst.pex.config.config.Config.saveToStream (   self,
  outfile,
  root = "config" 
)
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`).

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

Definition at line 1040 of file config.py.

1040  def saveToStream(self, outfile, root="config"):
1041  """Save a configuration file to a stream, which, when loaded,
1042  reproduces this config.
1043 
1044  Parameters
1045  ----------
1046  outfile : file-like object
1047  Destination file object write the config into. Accepts strings not
1048  bytes.
1049  root
1050  Name to use for the root config variable. The same value must be
1051  used when loading (see `lsst.pex.config.Config.load`).
1052 
1053  See also
1054  --------
1055  lsst.pex.config.Config.save
1056  lsst.pex.config.Config.load
1057  lsst.pex.config.Config.loadFromStream
1058  """
1059  tmp = self._name
1060  self._rename(root)
1061  try:
1062  self._collectImports()
1063  # Remove self from the set, as it is handled explicitly below
1064  self._imports.remove(self.__module__)
1065  configType = type(self)
1066  typeString = _typeStr(configType)
1067  outfile.write(u"import {}\n".format(configType.__module__))
1068  outfile.write(u"assert type({})=={}, 'config is of type %s.%s ".format(root, typeString))
1069  outfile.write(u"instead of {}' % (type({}).__module__, type({}).__name__)\n".format(typeString,
1070  root,
1071  root))
1072  for imp in self._imports:
1073  if imp in sys.modules and sys.modules[imp] is not None:
1074  outfile.write(u"import {}\n".format(imp))
1075  self._save(outfile)
1076  finally:
1077  self._rename(tmp)
1078 
table::Key< int > type
Definition: Detector.cc:164
def format(config, name=None, writeSourceLine=True, prefix="", verbose=False)
Definition: history.py:168

◆ 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``.

Definition at line 846 of file config.py.

846  def setDefaults(self):
847  """Subclass hook for computing defaults.
848 
849  Notes
850  -----
851  Derived `~lsst.pex.config.Config` classes that must compute defaults
852  rather than using the `~lsst.pex.config.Field` instances's defaults
853  should do so here. To correctly use inherited defaults,
854  implementations of ``setDefaults`` must call their base class's
855  ``setDefaults``.
856  """
857  pass
858 

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

1109  def toDict(self):
1110  """Make a dictionary of field names and their values.
1111 
1112  Returns
1113  -------
1114  dict_ : `dict`
1115  Dictionary with keys that are `~lsst.pex.config.Field` names.
1116  Values are `~lsst.pex.config.Field` values.
1117 
1118  See also
1119  --------
1120  lsst.pex.config.Field.toDict
1121 
1122  Notes
1123  -----
1124  This method uses the `~lsst.pex.config.Field.toDict` method of
1125  individual fields. Subclasses of `~lsst.pex.config.Field` may need to
1126  implement a ``toDict`` method for *this* method to work.
1127  """
1128  dict_ = {}
1129  for name, field in self._fields.items():
1130  dict_[name] = field.toDict(self)
1131  return dict_
1132 
std::vector< SchemaItem< Flag > > * items

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

859  def update(self, **kw):
860  """Update values of fields specified by the keyword arguments.
861 
862  Parameters
863  ----------
864  kw
865  Keywords are configuration field names. Values are configuration
866  field values.
867 
868  Notes
869  -----
870  The ``__at`` and ``__label`` keyword arguments are special internal
871  keywords. They are used to strip out any internal steps from the
872  history tracebacks of the config. Do not modify these keywords to
873  subvert a `~lsst.pex.config.Config` instance's history.
874 
875  Examples
876  --------
877  This is a config with three fields:
878 
879  >>> from lsst.pex.config import Config, Field
880  >>> class DemoConfig(Config):
881  ... fieldA = Field(doc='Field A', dtype=int, default=42)
882  ... fieldB = Field(doc='Field B', dtype=bool, default=True)
883  ... fieldC = Field(doc='Field C', dtype=str, default='Hello world')
884  ...
885  >>> config = DemoConfig()
886 
887  These are the default values of each field:
888 
889  >>> for name, value in config.iteritems():
890  ... print(f"{name}: {value}")
891  ...
892  fieldA: 42
893  fieldB: True
894  fieldC: 'Hello world'
895 
896  Using this method to update ``fieldA`` and ``fieldC``:
897 
898  >>> config.update(fieldA=13, fieldC='Updated!')
899 
900  Now the values of each field are:
901 
902  >>> for name, value in config.iteritems():
903  ... print(f"{name}: {value}")
904  ...
905  fieldA: 13
906  fieldB: True
907  fieldC: 'Updated!'
908  """
909  at = kw.pop("__at", getCallStack())
910  label = kw.pop("__label", "update")
911 
912  for name, value in kw.items():
913  try:
914  field = self._fields[name]
915  field.__set__(self, value, at=at, label=label)
916  except KeyError:
917  raise KeyError("No field of name %s exists in config type %s" % (name, _typeStr(self)))
918 
def getCallStack(skip=0)
Definition: callStack.py:169

◆ 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.

Definition at line 1186 of file config.py.

1186  def validate(self):
1187  """Validate the Config, raising an exception if invalid.
1188 
1189  Raises
1190  ------
1191  lsst.pex.config.FieldValidationError
1192  Raised if verification fails.
1193 
1194  Notes
1195  -----
1196  The base class implementation performs type checks on all fields by
1197  calling their `~lsst.pex.config.Field.validate` methods.
1198 
1199  Complex single-field validation can be defined by deriving new Field
1200  types. For convenience, some derived `lsst.pex.config.Field`-types
1201  (`~lsst.pex.config.ConfigField` and
1202  `~lsst.pex.config.ConfigChoiceField`) are defined in `lsst.pex.config`
1203  that handle recursing into subconfigs.
1204 
1205  Inter-field relationships should only be checked in derived
1206  `~lsst.pex.config.Config` classes after calling this method, and base
1207  validation is complete.
1208  """
1209  for field in self._fields.values():
1210  field.validate(self)
1211 

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

718  def values(self):
719  """Get field values.
720 
721  Returns
722  -------
723  values : `list`
724  List of field values.
725 
726  See also
727  --------
728  lsst.pex.config.Config.itervalues
729  """
730  return list(self._storage.values())
731 
daf::base::PropertyList * list
Definition: fits.cc:833

Property Documentation

◆ history

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

Definition at line 1234 of file config.py.


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