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