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