LSSTApplications  16.0-10-g9d3e444,16.0-11-g09ed895+3,16.0-11-g12e47bd+4,16.0-11-g9bb73b2+10,16.0-12-g5c924a4+10,16.0-15-g7af1f30,16.0-15-gdd5ca33+2,16.0-16-gf0259e2+1,16.0-17-g31abd91+11,16.0-17-g5cf0468+3,16.0-18-g51a54b3+3,16.0-18-ga4d4bcb+5,16.0-18-gcf94535+2,16.0-19-g9d290d5+2,16.0-2-g0febb12+22,16.0-2-g9d5294e+73,16.0-2-ga8830df+7,16.0-21-g3d035912+2,16.0-26-g8e79609,16.0-28-gfc9ea6c+9,16.0-29-ge8801f9+4,16.0-3-ge00e371+38,16.0-4-g18f3627+17,16.0-4-g5f3a788+21,16.0-4-ga3eb747+11,16.0-4-gabf74b7+33,16.0-4-gb13d127+7,16.0-5-g27fb78a+11,16.0-5-g6a53317+38,16.0-5-gb3f8a4b+91,16.0-51-gbbe9c988+3,16.0-6-g9321be7+5,16.0-6-gcbc7b31+47,16.0-6-gf49912c+33,16.0-7-gd2eeba5+56,16.0-75-gbf7a9a820,16.0-8-g21fd5fe+34,16.0-8-g3a9f023+24,16.0-9-gf3bc169+2,16.0-9-gf5c1f43+12,master-gd73dc1d098+5,w.2019.02
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.forcedPhotImage.ForcedPhotImageConfig 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.mergeMeasurements.MergeMeasurementsConfig 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.multiBand.DetectCoaddSourcesConfig lsst.pipe.tasks.multiBand.MeasureMergedCoaddSourcesConfig 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 639 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 780 of file config.py.

780  def __contains__(self, name):
781  """!Return True if the specified field exists in this config
782 
783  @param[in] name field name to test for
784  """
785  return self._storage.__contains__(name)
786 

◆ __delattr__()

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

Definition at line 1238 of file config.py.

1238  def __delattr__(self, attr, at=None, label="deletion"):
1239  if attr in self._fields:
1240  if at is None:
1241  at = getCallStack()
1242  self._fields[attr].__delete__(self, at=at, label=label)
1243  else:
1244  object.__delattr__(self, attr)
1245 
def getCallStack(skip=0)
Definition: callStack.py:169

◆ __eq__()

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

Definition at line 1246 of file config.py.

1246  def __eq__(self, other):
1247  if type(other) == type(self):
1248  for name in self._fields:
1249  thisValue = getattr(self, name)
1250  otherValue = getattr(other, name)
1251  if isinstance(thisValue, float) and math.isnan(thisValue):
1252  if not math.isnan(otherValue):
1253  return False
1254  elif thisValue != otherValue:
1255  return False
1256  return True
1257  return False
1258 
table::Key< int > type
Definition: Detector.cc:164

◆ __iter__()

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

Definition at line 685 of file config.py.

685  def __iter__(self):
686  """Iterate over fields.
687  """
688  return self._fields.__iter__()
689 

◆ __ne__()

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

Definition at line 1259 of file config.py.

1259  def __ne__(self, other):
1260  return not self.__eq__(other)
1261 

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

787  def __new__(cls, *args, **kw):
788  """Allocate a new `lsst.pex.config.Config` object.
789 
790  In order to ensure that all Config object are always in a proper state
791  when handed to users or to derived `~lsst.pex.config.Config` classes,
792  some attributes are handled at allocation time rather than at
793  initialization.
794 
795  This ensures that even if a derived `~lsst.pex.config.Config` class
796  implements ``__init__``, its author does not need to be concerned about
797  when or even the base ``Config.__init__`` should be called.
798  """
799  name = kw.pop("__name", None)
800  at = kw.pop("__at", getCallStack())
801  # remove __label and ignore it
802  kw.pop("__label", "default")
803 
804  instance = object.__new__(cls)
805  instance._frozen = False
806  instance._name = name
807  instance._storage = {}
808  instance._history = {}
809  instance._imports = set()
810  # load up defaults
811  for field in instance._fields.values():
812  instance._history[field.name] = []
813  field.__set__(instance, field.default, at=at + [field.source], label="default")
814  # set custom default-overides
815  instance.setDefaults()
816  # set constructor overides
817  instance.update(__at=at, **kw)
818  return instance
819 
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 820 of file config.py.

820  def __reduce__(self):
821  """Reduction for pickling (function with arguments to reproduce).
822 
823  We need to condense and reconstitute the `~lsst.pex.config.Config`,
824  since it may contain lambdas (as the ``check`` elements) that cannot
825  be pickled.
826  """
827  # The stream must be in characters to match the API but pickle requires bytes
828  stream = io.StringIO()
829  self.saveToStream(stream)
830  return (unreduceConfig, (self.__class__, stream.getvalue().encode()))
831 

◆ __repr__()

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

Definition at line 1265 of file config.py.

1265  def __repr__(self):
1266  return "%s(%s)" % (
1267  _typeStr(self),
1268  ", ".join("%s=%r" % (k, v) for k, v in self.toDict().items() if v is not None)
1269  )
1270 
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 1210 of file config.py.

1210  def __setattr__(self, attr, value, at=None, label="assignment"):
1211  """Set an attribute (such as a field's value).
1212 
1213  Notes
1214  -----
1215  Unlike normal Python objects, `~lsst.pex.config.Config` objects are
1216  locked such that no additional attributes nor properties may be added
1217  to them dynamically.
1218 
1219  Although this is not the standard Python behavior, it helps to protect
1220  users from accidentally mispelling a field name, or trying to set a
1221  non-existent field.
1222  """
1223  if attr in self._fields:
1224  if at is None:
1225  at = getCallStack()
1226  # This allows Field descriptors to work.
1227  self._fields[attr].__set__(self, value, at=at, label=label)
1228  elif hasattr(getattr(self.__class__, attr, None), '__set__'):
1229  # This allows properties and other non-Field descriptors to work.
1230  return object.__setattr__(self, attr, value)
1231  elif attr in self.__dict__ or attr in ("_name", "_history", "_storage", "_frozen", "_imports"):
1232  # This allows specific private attributes to work.
1233  self.__dict__[attr] = value
1234  else:
1235  # We throw everything else.
1236  raise AttributeError("%s has no attribute %s" % (_typeStr(self), attr))
1237 
def getCallStack(skip=0)
Definition: callStack.py:169

◆ __str__()

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

Definition at line 1262 of file config.py.

1262  def __str__(self):
1263  return str(self.toDict())
1264 

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

1271  def compare(self, other, shortcut=True, rtol=1E-8, atol=1E-8, output=None):
1272  """Compare this configuration to another `~lsst.pex.config.Config` for
1273  equality.
1274 
1275  Parameters
1276  ----------
1277  other : `lsst.pex.config.Config`
1278  Other `~lsst.pex.config.Config` object to compare against this
1279  config.
1280  shortcut : `bool`, optional
1281  If `True`, return as soon as an inequality is found. Default is
1282  `True`.
1283  rtol : `float`, optional
1284  Relative tolerance for floating point comparisons.
1285  atol : `float`, optional
1286  Absolute tolerance for floating point comparisons.
1287  output : callable, optional
1288  A callable that takes a string, used (possibly repeatedly) to
1289  report inequalities.
1290 
1291  Returns
1292  -------
1293  isEqual : `bool`
1294  `True` when the two `lsst.pex.config.Config` instances are equal.
1295  `False` if there is an inequality.
1296 
1297  See also
1298  --------
1299  lsst.pex.config.compareConfigs
1300 
1301  Notes
1302  -----
1303  Unselected targets of `~lsst.pex.config.RegistryField` fields and
1304  unselected choices of `~lsst.pex.config.ConfigChoiceField` fields
1305  are not considered by this method.
1306 
1307  Floating point comparisons are performed by `numpy.allclose`.
1308  """
1309  name1 = self._name if self._name is not None else "config"
1310  name2 = other._name if other._name is not None else "config"
1311  name = getComparisonName(name1, name2)
1312  return compareConfigs(name, self, other, shortcut=shortcut,
1313  rtol=rtol, atol=atol, output=output)
1314 
1315 
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 1184 of file config.py.

1184  def formatHistory(self, name, **kwargs):
1185  """Format a configuration field's history to a human-readable format.
1186 
1187  Parameters
1188  ----------
1189  name : `str`
1190  Name of a `~lsst.pex.config.Field` in this config.
1191  kwargs
1192  Keyword arguments passed to `lsst.pex.config.history.format`.
1193 
1194  Returns
1195  -------
1196  history : `str`
1197  A string containing the formatted history.
1198 
1199  See also
1200  --------
1201  lsst.pex.config.history.format
1202  """
1203  import lsst.pex.config.history as pexHist
1204  return pexHist.format(self, name, **kwargs)
1205 

◆ freeze()

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

Definition at line 1059 of file config.py.

1059  def freeze(self):
1060  """Make this config, and all subconfigs, read-only.
1061  """
1062  self._frozen = True
1063  for field in self._fields.values():
1064  field.freeze(self)
1065 

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

718  def items(self):
719  """Get configurations as ``(field name, field value)`` pairs.
720 
721  Returns
722  -------
723  items : `list`
724  List of tuples for each configuration. Tuple items are:
725 
726  0. Field name.
727  1. Field value.
728 
729  See also
730  --------
731  lsst.pex.config.Config.iteritems
732  """
733  return list(self._storage.items())
734 
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 735 of file config.py.

735  def iteritems(self):
736  """Iterate over (field name, field value) pairs.
737 
738  Yields
739  ------
740  item : `tuple`
741  Tuple items are:
742 
743  0. Field name.
744  1. Field value.
745 
746  See also
747  --------
748  lsst.pex.config.Config.items
749  """
750  return iter(self._storage.items())
751 
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 766 of file config.py.

766  def iterkeys(self):
767  """Iterate over field names
768 
769  Yields
770  ------
771  key : `str`
772  A field's key (attribute name).
773 
774  See also
775  --------
776  lsst.pex.config.Config.values
777  """
778  return iter(self.storage.keys())
779 

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

752  def itervalues(self):
753  """Iterate over field values.
754 
755  Yields
756  ------
757  value : obj
758  A field value.
759 
760  See also
761  --------
762  lsst.pex.config.Config.values
763  """
764  return iter(self.storage.values())
765 

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

690  def keys(self):
691  """Get field names.
692 
693  Returns
694  -------
695  names : `list`
696  List of `lsst.pex.config.Field` names.
697 
698  See also
699  --------
700  lsst.pex.config.Config.iterkeys
701  """
702  return list(self._storage.keys())
703 
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 905 of file config.py.

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

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

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

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

1105  def names(self):
1106  """Get all the field names in the config, recursively.
1107 
1108  Returns
1109  -------
1110  names : `list` of `str`
1111  Field names.
1112  """
1113  #
1114  # Rather than sort out the recursion all over again use the
1115  # pre-existing saveToStream()
1116  #
1117  with io.StringIO() as strFd:
1118  self.saveToStream(strFd, "config")
1119  contents = strFd.getvalue()
1120  strFd.close()
1121  #
1122  # Pull the names out of the dumped config
1123  #
1124  keys = []
1125  for line in contents.split("\n"):
1126  if re.search(r"^((assert|import)\s+|\s*$|#)", line):
1127  continue
1128 
1129  mat = re.search(r"^(?:config\.)?([^=]+)\s*=\s*.*", line)
1130  if mat:
1131  keys.append(mat.group(1))
1132 
1133  return keys
1134 

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

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

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

1026  def saveToStream(self, outfile, root="config"):
1027  """Save a configuration file to a stream, which, when loaded,
1028  reproduces this config.
1029 
1030  Parameters
1031  ----------
1032  outfile : file-like object
1033  Destination file object write the config into. Accepts strings not
1034  bytes.
1035  root
1036  Name to use for the root config variable. The same value must be
1037  used when loading (see `lsst.pex.config.Config.load`).
1038 
1039  See also
1040  --------
1041  lsst.pex.config.Config.save
1042  lsst.pex.config.Config.load
1043  lsst.pex.config.Config.loadFromStream
1044  """
1045  tmp = self._name
1046  self._rename(root)
1047  try:
1048  configType = type(self)
1049  typeString = _typeStr(configType)
1050  outfile.write(u"import {}\n".format(configType.__module__))
1051  outfile.write(u"assert type({})=={}, 'config is of type %s.%s ".format(root, typeString))
1052  outfile.write(u"instead of {}' % (type({}).__module__, type({}).__name__)\n".format(typeString,
1053  root,
1054  root))
1055  self._save(outfile)
1056  finally:
1057  self._rename(tmp)
1058 
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 832 of file config.py.

832  def setDefaults(self):
833  """Subclass hook for computing defaults.
834 
835  Notes
836  -----
837  Derived `~lsst.pex.config.Config` classes that must compute defaults
838  rather than using the `~lsst.pex.config.Field` instances's defaults
839  should do so here. To correctly use inherited defaults,
840  implementations of ``setDefaults`` must call their base class's
841  ``setDefaults``.
842  """
843  pass
844 

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

1081  def toDict(self):
1082  """Make a dictionary of field names and their values.
1083 
1084  Returns
1085  -------
1086  dict_ : `dict`
1087  Dictionary with keys that are `~lsst.pex.config.Field` names.
1088  Values are `~lsst.pex.config.Field` values.
1089 
1090  See also
1091  --------
1092  lsst.pex.config.Field.toDict
1093 
1094  Notes
1095  -----
1096  This method uses the `~lsst.pex.config.Field.toDict` method of
1097  individual fields. Subclasses of `~lsst.pex.config.Field` may need to
1098  implement a ``toDict`` method for *this* method to work.
1099  """
1100  dict_ = {}
1101  for name, field in self._fields.items():
1102  dict_[name] = field.toDict(self)
1103  return dict_
1104 
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 845 of file config.py.

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

1158  def validate(self):
1159  """Validate the Config, raising an exception if invalid.
1160 
1161  Raises
1162  ------
1163  lsst.pex.config.FieldValidationError
1164  Raised if verification fails.
1165 
1166  Notes
1167  -----
1168  The base class implementation performs type checks on all fields by
1169  calling their `~lsst.pex.config.Field.validate` methods.
1170 
1171  Complex single-field validation can be defined by deriving new Field
1172  types. For convenience, some derived `lsst.pex.config.Field`-types
1173  (`~lsst.pex.config.ConfigField` and
1174  `~lsst.pex.config.ConfigChoiceField`) are defined in `lsst.pex.config`
1175  that handle recursing into subconfigs.
1176 
1177  Inter-field relationships should only be checked in derived
1178  `~lsst.pex.config.Config` classes after calling this method, and base
1179  validation is complete.
1180  """
1181  for field in self._fields.values():
1182  field.validate(self)
1183 

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

704  def values(self):
705  """Get field values.
706 
707  Returns
708  -------
709  values : `list`
710  List of field values.
711 
712  See also
713  --------
714  lsst.pex.config.Config.itervalues
715  """
716  return list(self._storage.values())
717 
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 1206 of file config.py.


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