Inheritance diagram for lsst.pex.config.config.Config:
Public Member Functions | |
| __iter__ (self) | |
| keys (self) | |
| values (self) | |
| items (self) | |
| __contains__ (self, name) | |
| __new__ (cls, *args, **kw) | |
| __reduce__ (self) | |
| setDefaults (self) | |
| update (self, **kw) | |
| load (self, filename, root="config") | |
| loadFromStream (self, stream, root="config", filename=None, extraLocals=None) | |
| loadFromString (self, code, root="config", filename=None, extraLocals=None) | |
| save (self, filename, root="config") | |
| saveToString (self, skipImports=False) | |
| saveToStream (self, outfile, root="config", skipImports=False) | |
| freeze (self) | |
| toDict (self) | |
| names (self) | |
| validate (self) | |
| formatHistory (self, name, **kwargs) | |
| __setattr__ (self, attr, value, at=None, label="assignment") | |
| __delattr__ (self, attr, at=None, label="deletion") | |
| __eq__ (self, other) | |
| __ne__ (self, other) | |
| __str__ (self) | |
| __repr__ (self) | |
| compare (self, other, shortcut=True, rtol=1e-8, atol=1e-8, output=None) | |
| __init_subclass__ (cls, **kwargs) | |
Protected Member Functions | |
| _save (self, outfile) | |
| _collectImports (self) | |
| _rename (self, name) | |
| _fromPython (cls, config_py) | |
Protected Attributes | |
| _imports | |
| _frozen | |
| _name | |
Static Protected Attributes | |
| dict | _storage [str, Any] |
| dict | _fields [str, Field] |
| dict | _history [str, list[Any]] |
| set | _imports [Any] |
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`, and `items`. ``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']
Member Function Documentation
◆ __contains__()
| lsst.pex.config.config.Config.__contains__ | ( | self, | |
| name ) |
Return `True` if the specified field exists in this config.
Parameters
----------
name : `str`
Field name to test for.
Returns
-------
in : `bool`
`True` if the specified field exists in the config.
Reimplemented in lsst.pex.config.configChoiceField.ConfigInstanceDict.
Definition at line 1002 of file config.py.
1002 def __contains__(self, name):
1003 """Return `True` if the specified field exists in this config.
1004
1005 Parameters
1006 ----------
1007 name : `str`
1008 Field name to test for.
1009
1010 Returns
1011 -------
1012 in : `bool`
1013 `True` if the specified field exists in the config.
1014 """
1015 return self._storage.__contains__(name)
1016
◆ __delattr__()
| lsst.pex.config.config.Config.__delattr__ | ( | self, | |
| attr, | |||
| at = None, | |||
| label = "deletion" ) |
◆ __eq__()
| lsst.pex.config.config.Config.__eq__ | ( | self, | |
| other ) |
Definition at line 1587 of file config.py.
1587 def __eq__(self, other):
1588 if type(other) is type(self):
1589 for name in self._fields:
1590 thisValue = getattr(self, name)
1591 otherValue = getattr(other, name)
1592 if isinstance(thisValue, float) and math.isnan(thisValue):
1593 if not math.isnan(otherValue):
1594 return False
1595 elif thisValue != otherValue:
1596 return False
1597 return True
1598 return False
1599
◆ __init_subclass__()
| lsst.pex.config.config.Config.__init_subclass__ | ( | cls, | |
| ** | kwargs ) |
Run initialization for every subclass. Specifically registers the subclass with a YAML representer and YAML constructor (if pyyaml is available)
Reimplemented in lsst.pipe.tasks.dataFrameActions._baseDataFrameActions.DataFrameAction.
Definition at line 1656 of file config.py.
1656 def __init_subclass__(cls, **kwargs):
1657 """Run initialization for every subclass.
1658
1659 Specifically registers the subclass with a YAML representer
1660 and YAML constructor (if pyyaml is available)
1661 """
1662 super().__init_subclass__(**kwargs)
1663
1664 if not yaml:
1665 return
1666
1667 yaml.add_representer(cls, _yaml_config_representer)
1668
◆ __iter__()
| lsst.pex.config.config.Config.__iter__ | ( | self | ) |
Iterate over fields.
Reimplemented in lsst.pex.config.configChoiceField.ConfigInstanceDict.
Definition at line 965 of file config.py.
965 def __iter__(self):
966 """Iterate over fields."""
967 return self._fields.__iter__()
968
◆ __ne__()
| lsst.pex.config.config.Config.__ne__ | ( | self, | |
| other ) |
◆ __new__()
| 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.
Reimplemented in lsst.meas.base.baseMeasurement.BaseMeasurementConfig.
Definition at line 1017 of file config.py.
1017 def __new__(cls, *args, **kw):
1018 """Allocate a new `lsst.pex.config.Config` object.
1019
1020 In order to ensure that all Config object are always in a proper state
1021 when handed to users or to derived `~lsst.pex.config.Config` classes,
1022 some attributes are handled at allocation time rather than at
1023 initialization.
1024
1025 This ensures that even if a derived `~lsst.pex.config.Config` class
1026 implements ``__init__``, its author does not need to be concerned about
1027 when or even the base ``Config.__init__`` should be called.
1028 """
1029 name = kw.pop("__name", None)
1030 at = kw.pop("__at", getCallStack())
1031 # remove __label and ignore it
1032 kw.pop("__label", "default")
1033
1034 instance = object.__new__(cls)
1035 instance._frozen = False
1036 instance._name = name
1037 instance._storage = {}
1038 instance._history = {}
1039 instance._imports = set()
1040 # load up defaults
1041 for field in instance._fields.values():
1042 instance._history[field.name] = []
1043 field.__set__(instance, field.default, at=at + [field.source], label="default")
1044 # set custom default-overrides
1045 instance.setDefaults()
1046 # set constructor overrides
1047 instance.update(__at=at, **kw)
1048 return instance
1049
◆ __reduce__()
| 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.
Reimplemented in lsst.pex.config.configChoiceField.ConfigInstanceDict.
Definition at line 1050 of file config.py.
1050 def __reduce__(self):
1051 """Reduction for pickling (function with arguments to reproduce).
1052
1053 We need to condense and reconstitute the `~lsst.pex.config.Config`,
1054 since it may contain lambdas (as the ``check`` elements) that cannot
1055 be pickled.
1056 """
1057 # The stream must be in characters to match the API but pickle
1058 # requires bytes
1059 stream = io.StringIO()
1060 self.saveToStream(stream)
1061 return (unreduceConfig, (self.__class__, stream.getvalue().encode()))
1062
◆ __repr__()
| lsst.pex.config.config.Config.__repr__ | ( | self | ) |
◆ __setattr__()
| 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.
Reimplemented from lsst.pex.config.config.ConfigMeta.
Reimplemented in lsst.pex.config.registry.RegistryInstanceDict, lsst.pex.config.configChoiceField.ConfigInstanceDict, and lsst.pex.config.configurableActions._configurableAction.ConfigurableAction.
Definition at line 1544 of file config.py.
1544 def __setattr__(self, attr, value, at=None, label="assignment"):
1545 """Set an attribute (such as a field's value).
1546
1547 Notes
1548 -----
1549 Unlike normal Python objects, `~lsst.pex.config.Config` objects are
1550 locked such that no additional attributes nor properties may be added
1551 to them dynamically.
1552
1553 Although this is not the standard Python behavior, it helps to protect
1554 users from accidentally mispelling a field name, or trying to set a
1555 non-existent field.
1556 """
1557 if attr in self._fields:
1558 if self._fields[attr].deprecated is not None:
1559 fullname = _joinNamePath(self._name, self._fields[attr].name)
1560 warnings.warn(
1561 f"Config field {fullname} is deprecated: {self._fields[attr].deprecated}",
1562 FutureWarning,
1563 stacklevel=2,
1564 )
1565 if at is None:
1566 at = getCallStack()
1567 # This allows Field descriptors to work.
1568 self._fields[attr].__set__(self, value, at=at, label=label)
1569 elif hasattr(getattr(self.__class__, attr, None), "__set__"):
1570 # This allows properties and other non-Field descriptors to work.
1571 return object.__setattr__(self, attr, value)
1572 elif attr in self.__dict__ or attr in ("_name", "_history", "_storage", "_frozen", "_imports"):
1573 # This allows specific private attributes to work.
1574 self.__dict__[attr] = value
1575 else:
1576 # We throw everything else.
1577 raise AttributeError(f"{_typeStr(self)} has no attribute {attr}")
1578
◆ __str__()
| lsst.pex.config.config.Config.__str__ | ( | self | ) |
◆ _collectImports()
|
protected |
Add module containing self to the list of things to import and then loops over all the fields in the config calling a corresponding collect method. The field method will call _collectImports on any configs it may own and return the set of things to import. This returned set will be merged with the set of imports for this config class.
Reimplemented in lsst.pex.config.configChoiceField.ConfigChoiceField.
Definition at line 1400 of file config.py.
1400 def _collectImports(self):
1401 """Add module containing self to the list of things to import and
1402 then loops over all the fields in the config calling a corresponding
1403 collect method.
1404
1405 The field method will call _collectImports on any
1406 configs it may own and return the set of things to import. This
1407 returned set will be merged with the set of imports for this config
1408 class.
1409 """
1410 self._imports.add(self.__module__)
1412 field._collectImports(self, self._imports)
1413
◆ _fromPython()
|
protected |
Instantiate a `Config`-subclass from serialized Python form.
Parameters
----------
config_py : `str`
A serialized form of the Config as created by
`Config.saveToStream`.
Returns
-------
config : `Config`
Reconstructed `Config` instant.
Definition at line 1670 of file config.py.
1670 def _fromPython(cls, config_py):
1671 """Instantiate a `Config`-subclass from serialized Python form.
1672
1673 Parameters
1674 ----------
1675 config_py : `str`
1676 A serialized form of the Config as created by
1677 `Config.saveToStream`.
1678
1679 Returns
1680 -------
1681 config : `Config`
1682 Reconstructed `Config` instant.
1683 """
1684 cls = _classFromPython(config_py)
1685 return unreduceConfig(cls, config_py)
1686
1687
◆ _rename()
|
protected |
Rename this config object in its parent `~lsst.pex.config.Config`.
Parameters
----------
name : `str`
New name for this config in its parent `~lsst.pex.config.Config`.
Notes
-----
This method uses the `~lsst.pex.config.Field.rename` method of
individual `lsst.pex.config.Field` instances.
`lsst.pex.config.Field` subclasses may need to implement a ``rename``
method for *this* method to work.
See Also
--------
lsst.pex.config.Field.rename
Reimplemented in lsst.pex.config.configChoiceField.ConfigInstanceDict.
Definition at line 1468 of file config.py.
1468 def _rename(self, name):
1469 """Rename this config object in its parent `~lsst.pex.config.Config`.
1470
1471 Parameters
1472 ----------
1473 name : `str`
1474 New name for this config in its parent `~lsst.pex.config.Config`.
1475
1476 Notes
1477 -----
1478 This method uses the `~lsst.pex.config.Field.rename` method of
1479 individual `lsst.pex.config.Field` instances.
1480 `lsst.pex.config.Field` subclasses may need to implement a ``rename``
1481 method for *this* method to work.
1482
1483 See Also
1484 --------
1485 lsst.pex.config.Field.rename
1486 """
1487 self._name = name
1488 for field in self._fields.values():
1489 field.rename(self)
1490
◆ _save()
|
protected |
Save this config to an open stream object.
Parameters
----------
outfile : file-like object
Destination file object write the config into. Accepts strings not
bytes.
Definition at line 1388 of file config.py.
1388 def _save(self, outfile):
1389 """Save this config to an open stream object.
1390
1391 Parameters
1392 ----------
1393 outfile : file-like object
1394 Destination file object write the config into. Accepts strings not
1395 bytes.
1396 """
1397 for field in self._fields.values():
1398 field.save(outfile, self)
1399
◆ compare()
| 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 1612 of file config.py.
1612 def compare(self, other, shortcut=True, rtol=1e-8, atol=1e-8, output=None):
1613 """Compare this configuration to another `~lsst.pex.config.Config` for
1614 equality.
1615
1616 Parameters
1617 ----------
1618 other : `lsst.pex.config.Config`
1619 Other `~lsst.pex.config.Config` object to compare against this
1620 config.
1621 shortcut : `bool`, optional
1622 If `True`, return as soon as an inequality is found. Default is
1623 `True`.
1624 rtol : `float`, optional
1625 Relative tolerance for floating point comparisons.
1626 atol : `float`, optional
1627 Absolute tolerance for floating point comparisons.
1628 output : callable, optional
1629 A callable that takes a string, used (possibly repeatedly) to
1630 report inequalities.
1631
1632 Returns
1633 -------
1634 isEqual : `bool`
1635 `True` when the two `lsst.pex.config.Config` instances are equal.
1636 `False` if there is an inequality.
1637
1638 See Also
1639 --------
1640 lsst.pex.config.compareConfigs
1641
1642 Notes
1643 -----
1644 Unselected targets of `~lsst.pex.config.RegistryField` fields and
1645 unselected choices of `~lsst.pex.config.ConfigChoiceField` fields
1646 are not considered by this method.
1647
1648 Floating point comparisons are performed by `numpy.allclose`.
1649 """
1650 name1 = self._name if self._name is not None else "config"
1651 name2 = other._name if other._name is not None else "config"
1652 name = getComparisonName(name1, name2)
1653 return compareConfigs(name, self, other, shortcut=shortcut, rtol=rtol, atol=atol, output=output)
1654
◆ formatHistory()
| 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 1517 of file config.py.
1517 def formatHistory(self, name, **kwargs):
1518 """Format a configuration field's history to a human-readable format.
1519
1520 Parameters
1521 ----------
1522 name : `str`
1523 Name of a `~lsst.pex.config.Field` in this config.
1524 **kwargs
1525 Keyword arguments passed to `lsst.pex.config.history.format`.
1526
1527 Returns
1528 -------
1529 history : `str`
1530 A string containing the formatted history.
1531
1532 See Also
1533 --------
1534 lsst.pex.config.history.format
1535 """
1537
1538 return pexHist.format(self, name, **kwargs)
1539
Definition history.py:1
◆ freeze()
| lsst.pex.config.config.Config.freeze | ( | self | ) |
Make this config, and all subconfigs, read-only.
Reimplemented in lsst.pex.config.configChoiceField.ConfigInstanceDict, and lsst.pex.config.configChoiceField.ConfigChoiceField.
Definition at line 1382 of file config.py.
1382 def freeze(self):
1383 """Make this config, and all subconfigs, read-only."""
1384 self._frozen = True
1385 for field in self._fields.values():
1386 field.freeze(self)
1387
◆ items()
| lsst.pex.config.config.Config.items | ( | self | ) |
Get configurations as ``(field name, field value)`` pairs.
Returns
-------
items : `~collections.abc.ItemsView`
Iterator of tuples for each configuration. Tuple items are:
0. Field name.
1. Field value.
Definition at line 989 of file config.py.
990 """Get configurations as ``(field name, field value)`` pairs.
991
992 Returns
993 -------
994 items : `~collections.abc.ItemsView`
995 Iterator of tuples for each configuration. Tuple items are:
996
997 0. Field name.
998 1. Field value.
999 """
1001
◆ keys()
| lsst.pex.config.config.Config.keys | ( | self | ) |
Get field names.
Returns
-------
names : `~collections.abc.KeysView`
List of `lsst.pex.config.Field` names.
Definition at line 969 of file config.py.
969 def keys(self):
970 """Get field names.
971
972 Returns
973 -------
974 names : `~collections.abc.KeysView`
975 List of `lsst.pex.config.Field` names.
976 """
977 return self._storage.keys()
978
◆ load()
| 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``.
See Also
--------
lsst.pex.config.Config.loadFromStream
lsst.pex.config.Config.loadFromString
lsst.pex.config.Config.save
lsst.pex.config.Config.saveToStream
lsst.pex.config.Config.saveToString
Definition at line 1136 of file config.py.
1136 def load(self, filename, root="config"):
1137 """Modify this config in place by executing the Python code in a
1138 configuration file.
1139
1140 Parameters
1141 ----------
1142 filename : `str`
1143 Name of the configuration file. A configuration file is Python
1144 module.
1145 root : `str`, optional
1146 Name of the variable in file that refers to the config being
1147 overridden.
1148
1149 For example, the value of root is ``"config"`` and the file
1150 contains::
1151
1152 config.myField = 5
1153
1154 Then this config's field ``myField`` is set to ``5``.
1155
1156 See Also
1157 --------
1158 lsst.pex.config.Config.loadFromStream
1159 lsst.pex.config.Config.loadFromString
1160 lsst.pex.config.Config.save
1161 lsst.pex.config.Config.saveToStream
1162 lsst.pex.config.Config.saveToString
1163 """
1164 with open(filename) as f:
1165 code = compile(f.read(), filename=filename, mode="exec")
1166 self.loadFromString(code, root=root, filename=filename)
1167
◆ loadFromStream()
| lsst.pex.config.config.Config.loadFromStream | ( | self, | |
| stream, | |||
| root = "config", | |||
| filename = None, | |||
| extraLocals = None ) |
Modify this Config in place by executing the Python code in the
provided stream.
Parameters
----------
stream : file-like object, `str`, `bytes`, or `~types.CodeType`
Stream containing configuration override code. If this is a
code object, it should be compiled with ``mode="exec"``.
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``.
filename : `str`, optional
Name of the configuration file, or `None` if unknown or contained
in the stream. Used for error reporting.
extraLocals : `dict` of `str` to `object`, optional
Any extra variables to include in local scope when loading.
Notes
-----
For backwards compatibility reasons, this method accepts strings, bytes
and code objects as well as file-like objects. New code should use
`loadFromString` instead for most of these types.
See Also
--------
lsst.pex.config.Config.load
lsst.pex.config.Config.loadFromString
lsst.pex.config.Config.save
lsst.pex.config.Config.saveToStream
lsst.pex.config.Config.saveToString
Definition at line 1168 of file config.py.
1168 def loadFromStream(self, stream, root="config", filename=None, extraLocals=None):
1169 """Modify this Config in place by executing the Python code in the
1170 provided stream.
1171
1172 Parameters
1173 ----------
1174 stream : file-like object, `str`, `bytes`, or `~types.CodeType`
1175 Stream containing configuration override code. If this is a
1176 code object, it should be compiled with ``mode="exec"``.
1177 root : `str`, optional
1178 Name of the variable in file that refers to the config being
1179 overridden.
1180
1181 For example, the value of root is ``"config"`` and the file
1182 contains::
1183
1184 config.myField = 5
1185
1186 Then this config's field ``myField`` is set to ``5``.
1187 filename : `str`, optional
1188 Name of the configuration file, or `None` if unknown or contained
1189 in the stream. Used for error reporting.
1190 extraLocals : `dict` of `str` to `object`, optional
1191 Any extra variables to include in local scope when loading.
1192
1193 Notes
1194 -----
1195 For backwards compatibility reasons, this method accepts strings, bytes
1196 and code objects as well as file-like objects. New code should use
1197 `loadFromString` instead for most of these types.
1198
1199 See Also
1200 --------
1201 lsst.pex.config.Config.load
1202 lsst.pex.config.Config.loadFromString
1203 lsst.pex.config.Config.save
1204 lsst.pex.config.Config.saveToStream
1205 lsst.pex.config.Config.saveToString
1206 """
1207 if hasattr(stream, "read"):
1208 if filename is None:
1209 filename = getattr(stream, "name", "?")
1210 code = compile(stream.read(), filename=filename, mode="exec")
1211 else:
1212 code = stream
1213 self.loadFromString(code, root=root, filename=filename, extraLocals=extraLocals)
1214
◆ loadFromString()
| lsst.pex.config.config.Config.loadFromString | ( | self, | |
| code, | |||
| root = "config", | |||
| filename = None, | |||
| extraLocals = None ) |
Modify this Config in place by executing the Python code in the
provided string.
Parameters
----------
code : `str`, `bytes`, or `~types.CodeType`
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``.
filename : `str`, optional
Name of the configuration file, or `None` if unknown or contained
in the stream. Used for error reporting.
extraLocals : `dict` of `str` to `object`, optional
Any extra variables to include in local scope when loading.
Raises
------
ValueError
Raised if a key in extraLocals is the same value as the value of
the root argument.
See Also
--------
lsst.pex.config.Config.load
lsst.pex.config.Config.loadFromStream
lsst.pex.config.Config.save
lsst.pex.config.Config.saveToStream
lsst.pex.config.Config.saveToString
Definition at line 1215 of file config.py.
1215 def loadFromString(self, code, root="config", filename=None, extraLocals=None):
1216 """Modify this Config in place by executing the Python code in the
1217 provided string.
1218
1219 Parameters
1220 ----------
1221 code : `str`, `bytes`, or `~types.CodeType`
1222 Stream containing configuration override code.
1223 root : `str`, optional
1224 Name of the variable in file that refers to the config being
1225 overridden.
1226
1227 For example, the value of root is ``"config"`` and the file
1228 contains::
1229
1230 config.myField = 5
1231
1232 Then this config's field ``myField`` is set to ``5``.
1233 filename : `str`, optional
1234 Name of the configuration file, or `None` if unknown or contained
1235 in the stream. Used for error reporting.
1236 extraLocals : `dict` of `str` to `object`, optional
1237 Any extra variables to include in local scope when loading.
1238
1239 Raises
1240 ------
1241 ValueError
1242 Raised if a key in extraLocals is the same value as the value of
1243 the root argument.
1244
1245 See Also
1246 --------
1247 lsst.pex.config.Config.load
1248 lsst.pex.config.Config.loadFromStream
1249 lsst.pex.config.Config.save
1250 lsst.pex.config.Config.saveToStream
1251 lsst.pex.config.Config.saveToString
1252 """
1253 if filename is None:
1254 # try to determine the file name; a compiled string
1255 # has attribute "co_filename",
1256 filename = getattr(code, "co_filename", "?")
1257 with RecordingImporter() as importer:
1258 globals = {"__file__": filename}
1259 local = {root: self}
1260 if extraLocals is not None:
1261 # verify the value of root was not passed as extra local args
1262 if root in extraLocals:
1263 raise ValueError(
1264 f"{root} is reserved and cannot be used as a variable name in extraLocals"
1265 )
1266 local.update(extraLocals)
1267 exec(code, globals, local)
1268
1269 self._imports.update(importer.getModules())
1270
◆ names()
| 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 1438 of file config.py.
1438 def names(self):
1439 """Get all the field names in the config, recursively.
1440
1441 Returns
1442 -------
1443 names : `list` of `str`
1444 Field names.
1445 """
1446 #
1447 # Rather than sort out the recursion all over again use the
1448 # pre-existing saveToStream()
1449 #
1450 with io.StringIO() as strFd:
1451 self.saveToStream(strFd, "config")
1452 contents = strFd.getvalue()
1453 strFd.close()
1454 #
1455 # Pull the names out of the dumped config
1456 #
1457 keys = []
1458 for line in contents.split("\n"):
1459 if re.search(r"^((assert|import)\s+|\s*$|#)", line):
1460 continue
1461
1462 mat = re.search(r"^(?:config\.)?([^=]+)\s*=\s*.*", line)
1463 if mat:
1464 keys.append(mat.group(1))
1465
1466 return keys
1467
◆ save()
| 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.saveToString
lsst.pex.config.Config.load
lsst.pex.config.Config.loadFromStream
lsst.pex.config.Config.loadFromString
Reimplemented in lsst.pex.config.configChoiceField.ConfigChoiceField.
Definition at line 1271 of file config.py.
1271 def save(self, filename, root="config"):
1272 """Save a Python script to the named file, which, when loaded,
1273 reproduces this config.
1274
1275 Parameters
1276 ----------
1277 filename : `str`
1278 Desination filename of this configuration.
1279 root : `str`, optional
1280 Name to use for the root config variable. The same value must be
1281 used when loading (see `lsst.pex.config.Config.load`).
1282
1283 See Also
1284 --------
1285 lsst.pex.config.Config.saveToStream
1286 lsst.pex.config.Config.saveToString
1287 lsst.pex.config.Config.load
1288 lsst.pex.config.Config.loadFromStream
1289 lsst.pex.config.Config.loadFromString
1290 """
1291 d = os.path.dirname(filename)
1292 with tempfile.NamedTemporaryFile(mode="w", delete=False, dir=d) as outfile:
1293 self.saveToStream(outfile, root)
1294 # tempfile is hardcoded to create files with mode '0600'
1295 # for an explantion of these antics see:
1296 # https://stackoverflow.com/questions/10291131/how-to-use-os-umask-in-python
1297 umask = os.umask(0o077)
1298 os.umask(umask)
1299 os.chmod(outfile.name, (~umask & 0o666))
1300 # chmod before the move so we get quasi-atomic behavior if the
1301 # source and dest. are on the same filesystem.
1302 # os.rename may not work across filesystems
1303 shutil.move(outfile.name, filename)
1304
◆ saveToStream()
| lsst.pex.config.config.Config.saveToStream | ( | self, | |
| outfile, | |||
| root = "config", | |||
| skipImports = False ) |
Save a configuration file to a stream, which, when loaded,
reproduces this config.
Parameters
----------
outfile : file-like object
Destination file object write the config into. Accepts strings not
bytes.
root : `str`, optional
Name to use for the root config variable. The same value must be
used when loading (see `lsst.pex.config.Config.load`).
skipImports : `bool`, optional
If `True` then do not include ``import`` statements in output,
this is to support human-oriented output from ``pipetask`` where
additional clutter is not useful.
See Also
--------
lsst.pex.config.Config.save
lsst.pex.config.Config.saveToString
lsst.pex.config.Config.load
lsst.pex.config.Config.loadFromStream
lsst.pex.config.Config.loadFromString
Definition at line 1333 of file config.py.
1333 def saveToStream(self, outfile, root="config", skipImports=False):
1334 """Save a configuration file to a stream, which, when loaded,
1335 reproduces this config.
1336
1337 Parameters
1338 ----------
1339 outfile : file-like object
1340 Destination file object write the config into. Accepts strings not
1341 bytes.
1342 root : `str`, optional
1343 Name to use for the root config variable. The same value must be
1344 used when loading (see `lsst.pex.config.Config.load`).
1345 skipImports : `bool`, optional
1346 If `True` then do not include ``import`` statements in output,
1347 this is to support human-oriented output from ``pipetask`` where
1348 additional clutter is not useful.
1349
1350 See Also
1351 --------
1352 lsst.pex.config.Config.save
1353 lsst.pex.config.Config.saveToString
1354 lsst.pex.config.Config.load
1355 lsst.pex.config.Config.loadFromStream
1356 lsst.pex.config.Config.loadFromString
1357 """
1358 tmp = self._name
1359 self._rename(root)
1360 try:
1361 if not skipImports:
1362 self._collectImports()
1363 # Remove self from the set, as it is handled explicitly below
1364 self._imports.remove(self.__module__)
1365 configType = type(self)
1366 typeString = _typeStr(configType)
1367 outfile.write(f"import {configType.__module__}\n")
1368 # We are required to write this on a single line because
1369 # of later regex matching, rather than adopting black style
1370 # formatting.
1371 outfile.write(
1372 f'assert type({root}) is {typeString}, f"config is of type '
1373 f'{{type({root}).__module__}}.{{type({root}).__name__}} instead of {typeString}"\n\n'
1374 )
1375 for imp in sorted(self._imports):
1376 if imp in sys.modules and sys.modules[imp] is not None:
1377 outfile.write(f"import {imp}\n")
1378 self._save(outfile)
1379 finally:
1380 self._rename(tmp)
1381
◆ saveToString()
| lsst.pex.config.config.Config.saveToString | ( | self, | |
| skipImports = False ) |
Return the Python script form of this configuration as an executable
string.
Parameters
----------
skipImports : `bool`, optional
If `True` then do not include ``import`` statements in output,
this is to support human-oriented output from ``pipetask`` where
additional clutter is not useful.
Returns
-------
code : `str`
A code string readable by `loadFromString`.
See Also
--------
lsst.pex.config.Config.save
lsst.pex.config.Config.saveToStream
lsst.pex.config.Config.load
lsst.pex.config.Config.loadFromStream
lsst.pex.config.Config.loadFromString
Definition at line 1305 of file config.py.
1305 def saveToString(self, skipImports=False):
1306 """Return the Python script form of this configuration as an executable
1307 string.
1308
1309 Parameters
1310 ----------
1311 skipImports : `bool`, optional
1312 If `True` then do not include ``import`` statements in output,
1313 this is to support human-oriented output from ``pipetask`` where
1314 additional clutter is not useful.
1315
1316 Returns
1317 -------
1318 code : `str`
1319 A code string readable by `loadFromString`.
1320
1321 See Also
1322 --------
1323 lsst.pex.config.Config.save
1324 lsst.pex.config.Config.saveToStream
1325 lsst.pex.config.Config.load
1326 lsst.pex.config.Config.loadFromStream
1327 lsst.pex.config.Config.loadFromString
1328 """
1329 buffer = io.StringIO()
1330 self.saveToStream(buffer, skipImports=skipImports)
1331 return buffer.getvalue()
1332
◆ setDefaults()
| lsst.pex.config.config.Config.setDefaults | ( | self | ) |
Subclass hook for computing defaults. Notes ----- Derived `~lsst.pex.config.Config` classes that must compute defaults rather than using the `~lsst.pex.config.Field` instances's defaults should do so here. To correctly use inherited defaults, implementations of ``setDefaults`` must call their base class's ``setDefaults``.
Reimplemented in lsst.ip.diffim.dipoleMeasurement.DipoleMeasurementConfig, lsst.ip.diffim.subtractImages.AlardLuptonSubtractBaseConfig, lsst.ip.isr.ampOffset.AmpOffsetConfig, lsst.meas.algorithms.computeExPsf.ComputeExPsfConfig, lsst.meas.algorithms.measureApCorr.MeasureApCorrConfig, lsst.meas.algorithms.noise_covariance.ComputeNoiseCorrelationConfig, lsst.meas.algorithms.normalizedCalibrationFlux.NormalizedCalibrationFluxConfig, lsst.meas.algorithms.scaleVariance.ScaleVarianceConfig, lsst.meas.base.forcedMeasurement.ForcedMeasurementConfig, lsst.meas.modelfit.cmodel.cmodelContinued.CModelSingleFrameConfig, lsst.meas.modelfit.cmodel.cmodelContinued.CModelForcedConfig, lsst.meas.modelfit.psf.psfContinued.GeneralShapeletPsfApproxSingleFrameConfig, lsst.meas.modelfit.psf.psfContinued.GeneralShapeletPsfApproxForcedConfig, lsst.pipe.tasks.background.MaskObjectsConfig, and lsst.pipe.tasks.dataFrameActions._actions.NanoJansky.
Definition at line 1063 of file config.py.
1063 def setDefaults(self):
1064 """Subclass hook for computing defaults.
1065
1066 Notes
1067 -----
1068 Derived `~lsst.pex.config.Config` classes that must compute defaults
1069 rather than using the `~lsst.pex.config.Field` instances's defaults
1070 should do so here. To correctly use inherited defaults,
1071 implementations of ``setDefaults`` must call their base class's
1072 ``setDefaults``.
1073 """
1074 pass
1075
◆ toDict()
| 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.
Reimplemented in lsst.pex.config.configChoiceField.ConfigChoiceField.
Definition at line 1414 of file config.py.
1414 def toDict(self):
1415 """Make a dictionary of field names and their values.
1416
1417 Returns
1418 -------
1419 dict_ : `dict`
1420 Dictionary with keys that are `~lsst.pex.config.Field` names.
1421 Values are `~lsst.pex.config.Field` values.
1422
1423 See Also
1424 --------
1425 lsst.pex.config.Field.toDict
1426
1427 Notes
1428 -----
1429 This method uses the `~lsst.pex.config.Field.toDict` method of
1430 individual fields. Subclasses of `~lsst.pex.config.Field` may need to
1431 implement a ``toDict`` method for *this* method to work.
1432 """
1433 dict_ = {}
1435 dict_[name] = field.toDict(self)
1436 return dict_
1437
◆ update()
| 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 1076 of file config.py.
1076 def update(self, **kw):
1077 """Update values of fields specified by the keyword arguments.
1078
1079 Parameters
1080 ----------
1081 **kw
1082 Keywords are configuration field names. Values are configuration
1083 field values.
1084
1085 Notes
1086 -----
1087 The ``__at`` and ``__label`` keyword arguments are special internal
1088 keywords. They are used to strip out any internal steps from the
1089 history tracebacks of the config. Do not modify these keywords to
1090 subvert a `~lsst.pex.config.Config` instance's history.
1091
1092 Examples
1093 --------
1094 This is a config with three fields:
1095
1096 >>> from lsst.pex.config import Config, Field
1097 >>> class DemoConfig(Config):
1098 ... fieldA = Field(doc='Field A', dtype=int, default=42)
1099 ... fieldB = Field(doc='Field B', dtype=bool, default=True)
1100 ... fieldC = Field(doc='Field C', dtype=str, default='Hello world')
1101 ...
1102 >>> config = DemoConfig()
1103
1104 These are the default values of each field:
1105
1106 >>> for name, value in config.iteritems():
1107 ... print(f"{name}: {value}")
1108 ...
1109 fieldA: 42
1110 fieldB: True
1111 fieldC: 'Hello world'
1112
1113 Using this method to update ``fieldA`` and ``fieldC``:
1114
1115 >>> config.update(fieldA=13, fieldC='Updated!')
1116
1117 Now the values of each field are:
1118
1119 >>> for name, value in config.iteritems():
1120 ... print(f"{name}: {value}")
1121 ...
1122 fieldA: 13
1123 fieldB: True
1124 fieldC: 'Updated!'
1125 """
1126 at = kw.pop("__at", getCallStack())
1127 label = kw.pop("__label", "update")
1128
1129 for name, value in kw.items():
1130 try:
1131 field = self._fields[name]
1132 field.__set__(self, value, at=at, label=label)
1133 except KeyError:
1134 raise KeyError(f"No field of name {name} exists in config type {_typeStr(self)}")
1135
◆ validate()
| lsst.pex.config.config.Config.validate | ( | self | ) |
Validate the Config, raising an exception if invalid.
Raises
------
lsst.pex.config.FieldValidationError
Raised if verification fails.
Notes
-----
The base class implementation performs type checks on all fields by
calling their `~lsst.pex.config.Field.validate` methods.
Complex single-field validation can be defined by deriving new Field
types. For convenience, some derived `lsst.pex.config.Field`-types
(`~lsst.pex.config.ConfigField` and
`~lsst.pex.config.ConfigChoiceField`) are defined in
``lsst.pex.config`` that handle recursing into subconfigs.
Inter-field relationships should only be checked in derived
`~lsst.pex.config.Config` classes after calling this method, and base
validation is complete.
Reimplemented in lsst.afw.geom.transformConfig.RadialTransformConfig, lsst.dax.apdb.sql.apdbSql.ApdbSqlConfig, lsst.fgcmcal.sedterms.Sedterm, lsst.meas.algorithms.gaussianPsfFactory.GaussianPsfFactory, lsst.meas.algorithms.measureApCorr.MeasureApCorrConfig, lsst.meas.algorithms.treecorrUtils.TreecorrConfig, lsst.meas.base.baseMeasurement.BaseMeasurementConfig, lsst.meas.base.compensatedGaussian._compensatedTophat.SingleFrameCompensatedTophatFluxConfig, lsst.pex.config.configurableActions.tests.ActionTest1, lsst.pex.config.configurableActions.tests.ActionTest2, lsst.pex.config.configurableActions.tests.ActionTest3, lsst.pex.config.configurableActions.tests.TestDivideAction, lsst.pipe.tasks.background.MaskObjectsConfig, and lsst.pex.config.configChoiceField.ConfigChoiceField.
Definition at line 1491 of file config.py.
1491 def validate(self):
1492 """Validate the Config, raising an exception if invalid.
1493
1494 Raises
1495 ------
1496 lsst.pex.config.FieldValidationError
1497 Raised if verification fails.
1498
1499 Notes
1500 -----
1501 The base class implementation performs type checks on all fields by
1502 calling their `~lsst.pex.config.Field.validate` methods.
1503
1504 Complex single-field validation can be defined by deriving new Field
1505 types. For convenience, some derived `lsst.pex.config.Field`-types
1506 (`~lsst.pex.config.ConfigField` and
1507 `~lsst.pex.config.ConfigChoiceField`) are defined in
1508 ``lsst.pex.config`` that handle recursing into subconfigs.
1509
1510 Inter-field relationships should only be checked in derived
1511 `~lsst.pex.config.Config` classes after calling this method, and base
1512 validation is complete.
1513 """
1514 for field in self._fields.values():
1515 field.validate(self)
1516
◆ values()
| lsst.pex.config.config.Config.values | ( | self | ) |
Get field values.
Returns
-------
values : `~collections.abc.ValuesView`
Iterator of field values.
Definition at line 979 of file config.py.
979 def values(self):
980 """Get field values.
981
982 Returns
983 -------
984 values : `~collections.abc.ValuesView`
985 Iterator of field values.
986 """
987 return self._storage.values()
988
Member Data Documentation
◆ _fields
|
staticprotected |
◆ _frozen
◆ _history
|
staticprotected |
◆ _imports [1/2]
|
staticprotected |
◆ _imports [2/2]
◆ _name
◆ _storage
|
staticprotected |
Property Documentation
◆ history
|
static |
The documentation for this class was generated from the following file:
- /j/snowflake/release/lsstsw/stack/lsst-scipipe-9.0.0/Linux64/pex_config/g2cdde0e794+c2c89b37c4/python/lsst/pex/config/config.py
