LSSTApplications  17.0+11,17.0+35,17.0+59,17.0+60,17.0+62,17.0+7,17.0-1-g377950a+35,17.0.1-1-g114240f+2,17.0.1-1-g4d4fbc4+30,17.0.1-1-g55520dc+53,17.0.1-1-g5f4ed7e+57,17.0.1-1-g6dd7d69+21,17.0.1-1-g8de6c91+11,17.0.1-1-gb9095d2+7,17.0.1-1-ge9fec5e+5,17.0.1-1-gf4e0155+61,17.0.1-1-gfc65f5f+55,17.0.1-1-gfc6fb1f+20,17.0.1-10-g87f9f3f+7,17.0.1-12-g112a4bc+1,17.0.1-17-gab9750a3+3,17.0.1-17-gdae4c4a+14,17.0.1-19-g3a24bb2,17.0.1-2-g26618f5+34,17.0.1-2-g54f2ebc+9,17.0.1-2-gf403422+1,17.0.1-21-g52a398f+3,17.0.1-25-gd5522830,17.0.1-3-g7e86b59+44,17.0.1-3-gb5ca14a,17.0.1-3-gd08d533+45,17.0.1-31-gb0791f330,17.0.1-4-g59d126d+8,17.0.1-5-g3877d06,17.0.1-7-g35889ee+5,17.0.1-7-gc7c8782+20,17.0.1-7-gcb7da53+3,17.0.1-9-gc4bbfb2+8,v18.0.0.rc1
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.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.bootstrapRepo.BootstrapRepoConfig lsst.obs.base.gen3.bootstrapRepo.BootstrapRepoGenericIngestConfig lsst.obs.base.gen3.bootstrapRepo.BootstrapRepoRefCatConfig lsst.obs.base.gen3.bootstrapRepo.BootstrapRepoSkyMapConfig lsst.obs.base.gen3.ingest.RawIngestConfig 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.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 662 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 803 of file config.py.

803  def __contains__(self, name):
804  """!Return True if the specified field exists in this config
805 
806  @param[in] name field name to test for
807  """
808  return self._storage.__contains__(name)
809 

◆ __delattr__()

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

Definition at line 1275 of file config.py.

1275  def __delattr__(self, attr, at=None, label="deletion"):
1276  if attr in self._fields:
1277  if at is None:
1278  at = getCallStack()
1279  self._fields[attr].__delete__(self, at=at, label=label)
1280  else:
1281  object.__delattr__(self, attr)
1282 
def getCallStack(skip=0)
Definition: callStack.py:169

◆ __eq__()

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

Definition at line 1283 of file config.py.

1283  def __eq__(self, other):
1284  if type(other) == type(self):
1285  for name in self._fields:
1286  thisValue = getattr(self, name)
1287  otherValue = getattr(other, name)
1288  if isinstance(thisValue, float) and math.isnan(thisValue):
1289  if not math.isnan(otherValue):
1290  return False
1291  elif thisValue != otherValue:
1292  return False
1293  return True
1294  return False
1295 
table::Key< int > type
Definition: Detector.cc:167

◆ __iter__()

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

Definition at line 708 of file config.py.

708  def __iter__(self):
709  """Iterate over fields.
710  """
711  return self._fields.__iter__()
712 

◆ __ne__()

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

Definition at line 1296 of file config.py.

1296  def __ne__(self, other):
1297  return not self.__eq__(other)
1298 

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

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

843  def __reduce__(self):
844  """Reduction for pickling (function with arguments to reproduce).
845 
846  We need to condense and reconstitute the `~lsst.pex.config.Config`,
847  since it may contain lambdas (as the ``check`` elements) that cannot
848  be pickled.
849  """
850  # The stream must be in characters to match the API but pickle requires bytes
851  stream = io.StringIO()
852  self.saveToStream(stream)
853  return (unreduceConfig, (self.__class__, stream.getvalue().encode()))
854 

◆ __repr__()

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

Definition at line 1302 of file config.py.

1302  def __repr__(self):
1303  return "%s(%s)" % (
1304  _typeStr(self),
1305  ", ".join("%s=%r" % (k, v) for k, v in self.toDict().items() if v is not None)
1306  )
1307 
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 1247 of file config.py.

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

◆ __str__()

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

Definition at line 1299 of file config.py.

1299  def __str__(self):
1300  return str(self.toDict())
1301 

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

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

1221  def formatHistory(self, name, **kwargs):
1222  """Format a configuration field's history to a human-readable format.
1223 
1224  Parameters
1225  ----------
1226  name : `str`
1227  Name of a `~lsst.pex.config.Field` in this config.
1228  kwargs
1229  Keyword arguments passed to `lsst.pex.config.history.format`.
1230 
1231  Returns
1232  -------
1233  history : `str`
1234  A string containing the formatted history.
1235 
1236  See also
1237  --------
1238  lsst.pex.config.history.format
1239  """
1240  import lsst.pex.config.history as pexHist
1241  return pexHist.format(self, name, **kwargs)
1242 

◆ freeze()

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

Definition at line 1088 of file config.py.

1088  def freeze(self):
1089  """Make this config, and all subconfigs, read-only.
1090  """
1091  self._frozen = True
1092  for field in self._fields.values():
1093  field.freeze(self)
1094 

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

741  def items(self):
742  """Get configurations as ``(field name, field value)`` pairs.
743 
744  Returns
745  -------
746  items : `list`
747  List of tuples for each configuration. Tuple items are:
748 
749  0. Field name.
750  1. Field value.
751 
752  See also
753  --------
754  lsst.pex.config.Config.iteritems
755  """
756  return list(self._storage.items())
757 
std::vector< SchemaItem< Flag > > * items
daf::base::PropertyList * list
Definition: fits.cc:885

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

758  def iteritems(self):
759  """Iterate over (field name, field value) pairs.
760 
761  Yields
762  ------
763  item : `tuple`
764  Tuple items are:
765 
766  0. Field name.
767  1. Field value.
768 
769  See also
770  --------
771  lsst.pex.config.Config.items
772  """
773  return iter(self._storage.items())
774 
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 789 of file config.py.

789  def iterkeys(self):
790  """Iterate over field names
791 
792  Yields
793  ------
794  key : `str`
795  A field's key (attribute name).
796 
797  See also
798  --------
799  lsst.pex.config.Config.values
800  """
801  return iter(self.storage.keys())
802 

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

775  def itervalues(self):
776  """Iterate over field values.
777 
778  Yields
779  ------
780  value : obj
781  A field value.
782 
783  See also
784  --------
785  lsst.pex.config.Config.values
786  """
787  return iter(self.storage.values())
788 

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

713  def keys(self):
714  """Get field names.
715 
716  Returns
717  -------
718  names : `list`
719  List of `lsst.pex.config.Field` names.
720 
721  See also
722  --------
723  lsst.pex.config.Config.iterkeys
724  """
725  return list(self._storage.keys())
726 
daf::base::PropertyList * list
Definition: fits.cc:885

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

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

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

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

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

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

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

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

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

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

855  def setDefaults(self):
856  """Subclass hook for computing defaults.
857 
858  Notes
859  -----
860  Derived `~lsst.pex.config.Config` classes that must compute defaults
861  rather than using the `~lsst.pex.config.Field` instances's defaults
862  should do so here. To correctly use inherited defaults,
863  implementations of ``setDefaults`` must call their base class's
864  ``setDefaults``.
865  """
866  pass
867 

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

1118  def toDict(self):
1119  """Make a dictionary of field names and their values.
1120 
1121  Returns
1122  -------
1123  dict_ : `dict`
1124  Dictionary with keys that are `~lsst.pex.config.Field` names.
1125  Values are `~lsst.pex.config.Field` values.
1126 
1127  See also
1128  --------
1129  lsst.pex.config.Field.toDict
1130 
1131  Notes
1132  -----
1133  This method uses the `~lsst.pex.config.Field.toDict` method of
1134  individual fields. Subclasses of `~lsst.pex.config.Field` may need to
1135  implement a ``toDict`` method for *this* method to work.
1136  """
1137  dict_ = {}
1138  for name, field in self._fields.items():
1139  dict_[name] = field.toDict(self)
1140  return dict_
1141 
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 868 of file config.py.

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

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

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

727  def values(self):
728  """Get field values.
729 
730  Returns
731  -------
732  values : `list`
733  List of field values.
734 
735  See also
736  --------
737  lsst.pex.config.Config.itervalues
738  """
739  return list(self._storage.values())
740 
daf::base::PropertyList * list
Definition: fits.cc:885

Property Documentation

◆ history

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

Definition at line 1243 of file config.py.


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