27from __future__
import annotations
33 "FieldValidationError",
34 "UnexpectedProxyUsageError",
49from typing
import Any, ForwardRef, Generic, TypeVar, cast, overload
52 from types
import GenericAlias
55 GenericAlias = type(Mapping[int, int])
64from .callStack
import getCallStack, getStackFrame
65from .comparison
import compareConfigs, compareScalars, getComparisonName
68 YamlLoaders: tuple[Any, ...] = (yaml.Loader, yaml.FullLoader, yaml.SafeLoader, yaml.UnsafeLoader)
72 from yaml
import CLoader
74 YamlLoaders += (CLoader,)
83 """A Subclass of python's GenericAlias used in defining and instantiating
86 This class differs from `types.GenericAlias` in that it calls a method
87 named _parseTypingArgs defined on Fields. This method gives Field and its
88 subclasses an opportunity to transform type parameters into class key word
89 arguments. Code authors do not need to implement any returns of this object
90 directly, and instead only need implement _parseTypingArgs, if a Field
91 subclass differs from the base class implementation.
93 This class is intended to be an implementation detail, returned from a
94 Field's `__class_getitem__` method.
97 def __call__(self, *args: Any, **kwds: Any) -> Any:
98 origin_kwargs = self._parseTypingArgs(self.__args__, kwds)
99 return super().
__call__(*args, **{**kwds, **origin_kwargs})
102FieldTypeVar = TypeVar(
"FieldTypeVar")
106 """Exception raised when a proxy class is used in a context that suggests
107 it should have already been converted to the thing it proxies.
112 """Generate nested configuration names."""
113 if not prefix
and not name:
114 raise ValueError(
"Invalid name: cannot be None")
117 elif prefix
and name:
118 name = prefix +
"." + name
120 if index
is not None:
121 return f
"{name}[{index!r}]"
127 """Cast a value to a type, if appropriate.
134 Data type, such as `float`, `int`, or `str`.
139 If appropriate, the returned value is ``x`` cast to the given type
140 ``dtype``. If the cast cannot be performed the original value of
143 if dtype == float
and isinstance(x, int):
149 """Generate a fully-qualified type name.
154 Fully-qualified type name.
158 This function is used primarily for writing config files to be executed
159 later upon with the 'load' function.
161 if hasattr(x,
"__module__")
and hasattr(x,
"__name__"):
165 if xtype.__module__ ==
"builtins":
166 return xtype.__name__
168 return f
"{xtype.__module__}.{xtype.__name__}"
174 """Represent a Config object in a form suitable for YAML.
176 Stores the serialized stream as a scalar block string.
178 stream = io.StringIO()
179 data.saveToStream(stream)
180 config_py = stream.getvalue()
184 config_py = config_py.rstrip() +
"\n"
188 config_py = re.sub(
r"\s+$",
"\n", config_py, flags=re.MULTILINE)
191 return dumper.represent_scalar(
"lsst.pex.config.Config", config_py, style=
"|")
194 """Construct a config from YAML."""
195 config_py = loader.construct_scalar(node)
196 return Config._fromPython(config_py)
200 for loader
in YamlLoaders:
201 yaml.add_constructor(
"lsst.pex.config.Config", _yaml_config_constructor, Loader=loader)
205 """A metaclass for `lsst.pex.config.Config`.
210 Name to use for class.
211 bases : `~collections.abc.Iterable`
214 Additional parameters.
218 ``ConfigMeta`` adds a dictionary containing all `~lsst.pex.config.Field`
219 class attributes as a class attribute called ``_fields``, and adds
220 the name of each field as an instance variable of the field itself (so you
221 don't have to pass the name of the field to the field constructor).
225 type.__init__(cls, name, bases, dict_)
229 def getFields(classtype):
231 bases = list(classtype.__bases__)
234 fields.update(getFields(b))
236 for k, v
in classtype.__dict__.items():
237 if isinstance(v, Field):
241 fields = getFields(cls)
242 for k, v
in fields.items():
243 setattr(cls, k, copy.deepcopy(v))
246 if isinstance(value, Field):
249 type.__setattr__(cls, name, value)
253 """Raised when a ``~lsst.pex.config.Field`` is not valid in a
254 particular ``~lsst.pex.config.Config``.
258 field : `lsst.pex.config.Field`
259 The field that was not valid.
260 config : `lsst.pex.config.Config`
261 The config containing the invalid field.
263 Text describing why the field was not valid.
268 """Type of the `~lsst.pex.config.Field` that incurred the error.
272 """Name of the `~lsst.pex.config.Field` instance that incurred the
277 lsst.pex.config.Field.name
280 self.
fullname = _joinNamePath(config._name, field.name)
281 """Fully-qualified name of the `~lsst.pex.config.Field` instance
285 self.
history = config.history.setdefault(field.name, [])
286 """Full history of all changes to the `~lsst.pex.config.Field`
291 """File and line number of the `~lsst.pex.config.Field` definition.
296 "%s '%s' failed validation: %s\n"
297 "For more information see the Field definition at:\n%s"
298 " and the Config definition at:\n%s"
311 """A field in a `~lsst.pex.config.Config` that supports `int`, `float`,
312 `complex`, `bool`, and `str` data types.
317 A description of the field for users.
318 dtype : type, optional
319 The field's data type. ``Field`` only supports basic data types:
320 `int`, `float`, `complex`, `bool`, and `str`. See
321 `Field.supportedTypes`. Optional if supplied as a typing argument to
323 default : object, optional
324 The field's default value.
325 check : callable, optional
326 A callable that is called with the field's value. This callable should
327 return `False` if the value is invalid. More complex inter-field
328 validation can be written as part of the
329 `lsst.pex.config.Config.validate` method.
330 optional : `bool`, optional
331 This sets whether the field is considered optional, and therefore
332 doesn't need to be set by the user. When `False`,
333 `lsst.pex.config.Config.validate` fails if the field's value is `None`.
334 deprecated : None or `str`, optional
335 A description of why this Field is deprecated, including removal date.
336 If not None, the string is appended to the docstring for this Field.
341 Raised when the ``dtype`` parameter is not one of the supported types
342 (see `Field.supportedTypes`).
358 ``Field`` instances (including those of any subclass of ``Field``) are used
359 as class attributes of `~lsst.pex.config.Config` subclasses (see the
360 example, below). ``Field`` attributes work like the `property` attributes
361 of classes that implement custom setters and getters. `Field` attributes
362 belong to the class, but operate on the instance. Formally speaking,
363 `Field` attributes are `descriptors
364 <https://docs.python.org/3/howto/descriptor.html>`_.
366 When you access a `Field` attribute on a `Config` instance, you don't
367 get the `Field` instance itself. Instead, you get the value of that field,
368 which might be a simple type (`int`, `float`, `str`, `bool`) or a custom
369 container type (like a `lsst.pex.config.List`) depending on the field's
370 type. See the example, below.
372 Fields can be annotated with a type similar to other python classes (python
373 specification `here <https://peps.python.org/pep-0484/#generics>`_ ).
374 See the name field in the Config example below for an example of this.
375 Unlike most other uses in python, this has an effect at type checking *and*
376 runtime. If the type is specified with a class annotation, it will be used
377 as the value of the ``dtype`` in the ``Field`` and there is no need to
378 specify it as an argument during instantiation.
380 There are Some notes on dtype through type annotation syntax. Type
381 annotation syntax supports supplying the argument as a string of a type
382 name. i.e. "float", but this cannot be used to resolve circular references.
383 Type annotation syntax can be used on an identifier in addition to Class
384 assignment i.e. ``variable: Field[str] = Config.someField`` vs
385 ``someField = Field[str](doc="some doc"). However, this syntax is only
386 useful for annotating the type of the identifier (i.e. variable in previous
387 example) and does nothing for assigning the dtype of the ``Field``.
391 Instances of ``Field`` should be used as class attributes of
392 `lsst.pex.config.Config` subclasses:
394 >>> from lsst.pex.config import Config, Field
395 >>> class Example(Config):
396 ... myInt = Field("An integer field.", int, default=0)
397 ... name = Field[str](doc="A string Field")
399 >>> print(config.myInt)
402 >>> print(config.myInt)
407 """Identifier (variable name) used to refer to a Field within a Config
411 supportedTypes = {str, bool, float, int, complex}
412 """Supported data types for field values (`set` of types).
417 params: tuple[type, ...] | tuple[str, ...], kwds: Mapping[str, Any]
418 ) -> Mapping[str, Any]:
419 """Parse type annotations into keyword constructor arguments.
421 This is a special private method that interprets type arguments (i.e.
422 Field[str]) into keyword arguments to be passed on to the constructor.
424 Subclasses of Field can implement this method to customize how they
425 handle turning type parameters into keyword arguments (see DictField
430 params : `tuple` of `type` or `tuple` of str
431 Parameters passed to the type annotation. These will either be
432 types or strings. Strings are to interpreted as forward references
433 and will be treated as such.
434 kwds : `MutableMapping` with keys of `str` and values of `Any`
435 These are the user supplied keywords that are to be passed to the
440 kwds : `MutableMapping` with keys of `str` and values of `Any`
441 The mapping of keywords that will be passed onto the constructor
442 of the Field. Should be filled in with any information gleaned
443 from the input parameters.
448 Raised if params is of incorrect length.
449 Raised if a forward reference could not be resolved
450 Raised if there is a conflict between params and values in kwds
453 raise ValueError(
"Only single type parameters are supported")
454 unpackedParams = params[0]
455 if isinstance(unpackedParams, str):
456 _typ = ForwardRef(unpackedParams)
462 result = _typ._evaluate(globals(), locals(),
set())
465 result = _typ._evaluate(globals(), locals())
467 raise ValueError(
"Could not deduce type from input")
468 unpackedParams = cast(type, result)
469 if "dtype" in kwds
and kwds[
"dtype"] != unpackedParams:
470 raise ValueError(
"Conflicting definition for dtype")
471 elif "dtype" not in kwds:
472 kwds = {**kwds, **{
"dtype": unpackedParams}}
478 def __init__(self, doc, dtype=None, default=None, check=None, optional=False, deprecated=None):
481 "dtype must either be supplied as an argument or as a type argument to the class"
484 raise ValueError(
"Unsupported Field dtype %s" % _typeStr(dtype))
486 source = getStackFrame()
494 deprecated=deprecated,
497 def _setup(self, doc, dtype, default, check, optional, source, deprecated):
498 """Set attributes, usually during initialization."""
500 """Data type for the field.
504 raise ValueError(
"Docstring is empty.")
507 if deprecated
is not None:
508 doc = f
"{doc} Deprecated: {deprecated}"
510 """A description of the field (`str`).
514 """If not None, a description of why this field is deprecated (`str`).
517 self.
__doc__ = f
"{doc} (`{dtype.__name__}`"
518 if optional
or default
is not None:
519 self.
__doc__ += f
", default ``{default!r}``"
523 """Default value for this field.
527 """A user-defined function that validates the value of the field.
531 """Flag that determines if the field is required to be set (`bool`).
533 When `False`, `lsst.pex.config.Config.validate` will fail if the
534 field's value is `None`.
538 """The stack frame where this field is defined (`list` of
539 `~lsst.pex.config.callStack.StackFrame`).
543 r"""Rename the field in a `~lsst.pex.config.Config` (for internal use
548 instance : `lsst.pex.config.Config`
549 The config instance that contains this field.
553 This method is invoked by the `lsst.pex.config.Config` object that
554 contains this field and should not be called directly.
556 Renaming is only relevant for `~lsst.pex.config.Field` instances that
557 hold subconfigs. `~lsst.pex.config.Field`\s that hold subconfigs should
558 rename each subconfig with the full field name as generated by
559 `lsst.pex.config.config._joinNamePath`.
564 """Validate the field (for internal use only).
568 instance : `lsst.pex.config.Config`
569 The config instance that contains this field.
573 lsst.pex.config.FieldValidationError
574 Raised if verification fails.
578 This method provides basic validation:
580 - Ensures that the value is not `None` if the field is not optional.
581 - Ensures type correctness.
582 - Ensures that the user-provided ``check`` function is valid.
584 Most `~lsst.pex.config.Field` subclasses should call
585 `lsst.pex.config.Field.validate` if they re-implement
586 `~lsst.pex.config.Field.validate`.
588 value = self.__get__(instance)
589 if not self.optional
and value
is None:
590 raise FieldValidationError(self, instance,
"Required value cannot be None")
593 """Make this field read-only (for internal use only).
597 instance : `lsst.pex.config.Config`
598 The config instance that contains this field.
602 Freezing is only relevant for fields that hold subconfigs. Fields which
603 hold subconfigs should freeze each subconfig.
605 **Subclasses should implement this method.**
615 The value being validated.
620 Raised if the value's type is incompatible with the field's
623 Raised if the value is rejected by the ``check`` method.
628 if not isinstance(value, self.dtype):
629 msg =
"Value {} is of incorrect type {}. Expected type {}".format(
632 _typeStr(self.dtype),
635 if self.check
is not None and not self.check(value):
636 msg =
"Value %s is not a valid value" % str(value)
637 raise ValueError(msg)
640 """Call the _collectImports method on all config
641 objects the field may own, and union them with the supplied imports
646 instance : instance or subclass of `lsst.pex.config.Config`
647 A config object that has this field defined on it
649 Set of python modules that need imported after persistence
653 def save(self, outfile, instance):
654 """Save this field to a file (for internal use only).
658 outfile : file-like object
659 A writeable field handle.
660 instance : `~lsst.pex.config.Config`
661 The `~lsst.pex.config.Config` instance that contains this field.
665 This method is invoked by the `~lsst.pex.config.Config` object that
666 contains this field and should not be called directly.
668 The output consists of the documentation string
669 (`lsst.pex.config.Field.doc`) formatted as a Python comment. The second
670 line is formatted as an assignment: ``{fullname}={value}``.
672 This output can be executed with Python.
674 value = self.__get__(instance)
675 fullname = _joinNamePath(instance._name, self.name)
677 if self.deprecated
and value == self.default:
682 doc =
"# " + str(self.doc).replace(
"\n",
"\n# ")
683 if isinstance(value, float)
and not math.isfinite(value):
685 outfile.write(f
"{doc}\n{fullname}=float('{value!r}')\n\n")
687 outfile.write(f
"{doc}\n{fullname}={value!r}\n\n")
690 """Convert the field value so that it can be set as the value of an
691 item in a `dict` (for internal use only).
695 instance : `~lsst.pex.config.Config`
696 The `~lsst.pex.config.Config` that contains this field.
701 The field's value. See *Notes*.
705 This method invoked by the owning `~lsst.pex.config.Config` object and
706 should not be called directly.
708 Simple values are passed through. Complex data structures must be
709 manipulated. For example, a `~lsst.pex.config.Field` holding a
710 subconfig should, instead of the subconfig object, return a `dict`
711 where the keys are the field names in the subconfig, and the values are
712 the field values in the subconfig.
718 self, instance: None, owner: Any =
None, at: Any =
None, label: str =
"default"
719 ) -> Field[FieldTypeVar]:
724 self, instance: Config, owner: Any =
None, at: Any =
None, label: str =
"default"
728 def __get__(self, instance, owner=None, at=None, label="default"):
729 """Define how attribute access should occur on the Config instance
730 This is invoked by the owning config object and should not be called
733 When the field attribute is accessed on a Config class object, it
734 returns the field object itself in order to allow inspection of
737 When the field attribute is access on a config instance, the actual
738 value described by the field (and held by the Config instance) is
746 return instance._storage[self.
namename]
747 except AttributeError:
748 if not isinstance(instance, Config):
751 raise AttributeError(
752 f
"Config {instance} is missing _storage attribute, likely incorrectly initialized"
756 self, instance: Config, value: FieldTypeVar |
None, at: Any =
None, label: str =
"assignment"
758 """Set an attribute on the config instance.
762 instance : `lsst.pex.config.Config`
763 The config instance that contains this field.
765 Value to set on this field.
766 at : `list` of `~lsst.pex.config.callStack.StackFrame` or `None`,\
768 The call stack (created by
769 `lsst.pex.config.callStack.getCallStack`).
770 label : `str`, optional
771 Event label for the history.
775 This method is invoked by the owning `lsst.pex.config.Config` object
776 and should not be called directly.
778 Derived `~lsst.pex.config.Field` classes may need to override the
779 behavior. When overriding ``__set__``, `~lsst.pex.config.Field` authors
780 should follow the following rules:
782 - Do not allow modification of frozen configs.
783 - Validate the new value **before** modifying the field. Except if the
784 new value is `None`. `None` is special and no attempt should be made
785 to validate it until `lsst.pex.config.Config.validate` is called.
786 - Do not modify the `~lsst.pex.config.Config` instance to contain
788 - If the field is modified, update the history of the
789 `lsst.pex.config.field.Field` to reflect the changes.
791 In order to decrease the need to implement this method in derived
792 `~lsst.pex.config.Field` types, value validation is performed in the
793 `lsst.pex.config.Field._validateValue`. If only the validation step
794 differs in the derived `~lsst.pex.config.Field`, it is simpler to
795 implement `lsst.pex.config.Field._validateValue` than to reimplement
796 ``__set__``. More complicated behavior, however, may require
802 history = instance._history.setdefault(self.
namename, [])
803 if value
is not None:
804 value = _autocast(value, self.
dtype)
807 except BaseException
as e:
810 instance._storage[self.
namename] = value
813 history.append((value, at, label))
816 """Delete an attribute from a `lsst.pex.config.Config` instance.
820 instance : `lsst.pex.config.Config`
821 The config instance that contains this field.
822 at : `list` of `lsst.pex.config.callStack.StackFrame`
823 The call stack (created by
824 `lsst.pex.config.callStack.getCallStack`).
825 label : `str`, optional
826 Event label for the history.
830 This is invoked by the owning `~lsst.pex.config.Config` object and
831 should not be called directly.
835 self.
__set__(instance,
None, at=at, label=label)
837 def _compare(self, instance1, instance2, shortcut, rtol, atol, output):
838 """Compare a field (named `Field.name`) in two
839 `~lsst.pex.config.Config` instances for equality.
843 instance1 : `lsst.pex.config.Config`
844 Left-hand side `Config` instance to compare.
845 instance2 : `lsst.pex.config.Config`
846 Right-hand side `Config` instance to compare.
847 shortcut : `bool`, optional
849 rtol : `float`, optional
850 Relative tolerance for floating point comparisons.
851 atol : `float`, optional
852 Absolute tolerance for floating point comparisons.
853 output : callable, optional
854 A callable that takes a string, used (possibly repeatedly) to
859 This method must be overridden by more complex `Field` subclasses.
863 lsst.pex.config.compareScalars
865 v1 = getattr(instance1, self.
namename)
866 v2 = getattr(instance2, self.
namename)
867 name = getComparisonName(
868 _joinNamePath(instance1._name, self.
namename), _joinNamePath(instance2._name, self.
namename)
870 return compareScalars(name, v1, v2, dtype=self.
dtype, rtol=rtol, atol=atol, output=output)
874 """Importer (for `sys.meta_path`) that records which modules are being
877 *This class does not do any importing itself.*
881 Use this class as a context manager to ensure it is properly uninstalled
884 >>> with RecordingImporter() as importer:
886 ... import numpy as np
887 ... print("Imported: " + importer.getModules())
895 sys.meta_path = [self] + sys.meta_path
903 """Uninstall the importer."""
909 Called as part of the ``import`` chain of events.
915 path : `list` [`str`]
917 target : `~typing.Any`, optional
925 """Get the set of modules that were imported.
929 modules : `set` of `str`
930 Set of imported module names.
937 """Base class for configuration (*config*) objects.
941 A ``Config`` object will usually have several `~lsst.pex.config.Field`
942 instances as class attributes. These are used to define most of the base
945 ``Config`` implements a mapping API that provides many `dict`-like methods,
946 such as `keys`, `values`, and `items`. ``Config`` instances also support
947 the ``in`` operator to test if a field is in the config. Unlike a `dict`,
948 ``Config`` classes are not subscriptable. Instead, access individual
949 fields as attributes of the configuration instance.
953 Config classes are subclasses of ``Config`` that have
954 `~lsst.pex.config.Field` instances (or instances of
955 `~lsst.pex.config.Field` subclasses) as class attributes:
957 >>> from lsst.pex.config import Config, Field, ListField
958 >>> class DemoConfig(Config):
959 ... intField = Field(doc="An integer field", dtype=int, default=42)
960 ... listField = ListField(doc="List of favorite beverages.", dtype=str,
961 ... default=['coffee', 'green tea', 'water'])
963 >>> config = DemoConfig()
965 Configs support many `dict`-like APIs:
968 ['intField', 'listField']
969 >>> 'intField' in config
972 Individual fields can be accessed as attributes of the configuration:
976 >>> config.listField.append('earl grey tea')
977 >>> print(config.listField)
978 ['coffee', 'green tea', 'water', 'earl grey tea']
981 _storage: dict[str, Any]
982 _fields: dict[str, Field]
983 _history: dict[str, list[Any]]
987 """Iterate over fields."""
995 names : `~collections.abc.KeysView`
996 List of `lsst.pex.config.Field` names.
1001 """Get field values.
1005 values : `~collections.abc.ValuesView`
1006 Iterator of field values.
1011 """Get configurations as ``(field name, field value)`` pairs.
1015 items : `~collections.abc.ItemsView`
1016 Iterator of tuples for each configuration. Tuple items are:
1024 """Return `True` if the specified field exists in this config.
1029 Field name to test for.
1034 `True` if the specified field exists in the config.
1039 """Allocate a new `lsst.pex.config.Config` object.
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
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.
1050 name = kw.pop(
"__name",
None)
1051 at = kw.pop(
"__at", getCallStack())
1053 kw.pop(
"__label",
"default")
1055 instance = object.__new__(cls)
1056 instance._frozen =
False
1057 instance._name = name
1058 instance._storage = {}
1059 instance._history = {}
1060 instance._imports =
set()
1062 for field
in instance._fields.values():
1063 instance._history[field.name] = []
1064 field.__set__(instance, field.default, at=at + [field.source], label=
"default")
1066 instance.setDefaults()
1068 instance.update(__at=at, **kw)
1072 """Reduction for pickling (function with arguments to reproduce).
1074 We need to condense and reconstitute the `~lsst.pex.config.Config`,
1075 since it may contain lambdas (as the ``check`` elements) that cannot
1080 stream = io.StringIO()
1082 return (unreduceConfig, (self.
__class__, stream.getvalue().encode()))
1085 """Subclass hook for computing defaults.
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
1098 """Update values of fields specified by the keyword arguments.
1103 Keywords are configuration field names. Values are configuration
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.
1115 This is a config with three fields:
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')
1123 >>> config = DemoConfig()
1125 These are the default values of each field:
1127 >>> for name, value in config.iteritems():
1128 ... print(f"{name}: {value}")
1132 fieldC: 'Hello world'
1134 Using this method to update ``fieldA`` and ``fieldC``:
1136 >>> config.update(fieldA=13, fieldC='Updated!')
1138 Now the values of each field are:
1140 >>> for name, value in config.iteritems():
1141 ... print(f"{name}: {value}")
1147 at = kw.pop(
"__at", getCallStack())
1148 label = kw.pop(
"__label",
"update")
1150 for name, value
in kw.items():
1152 field = self._fields[name]
1153 field.__set__(self, value, at=at, label=label)
1155 raise KeyError(f
"No field of name {name} exists in config type {_typeStr(self)}")
1157 def load(self, filename, root="config"):
1158 """Modify this config in place by executing the Python code in a
1164 Name of the configuration file. A configuration file is Python
1166 root : `str`, optional
1167 Name of the variable in file that refers to the config being
1170 For example, the value of root is ``"config"`` and the file
1175 Then this config's field ``myField`` is set to ``5``.
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
1185 with open(filename)
as f:
1186 code = compile(f.read(), filename=filename, mode=
"exec")
1190 """Modify this Config in place by executing the Python code in the
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
1202 For example, the value of root is ``"config"`` and the file
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.
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.
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
1228 if hasattr(stream,
"read"):
1229 if filename
is None:
1230 filename = getattr(stream,
"name",
"?")
1231 code = compile(stream.read(), filename=filename, mode=
"exec")
1234 self.
loadFromString(code, root=root, filename=filename, extraLocals=extraLocals)
1237 """Modify this Config in place by executing the Python code in the
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
1248 For example, the value of root is ``"config"`` and the file
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.
1263 Raised if a key in extraLocals is the same value as the value of
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
1274 if filename
is None:
1277 filename = getattr(code,
"co_filename",
"?")
1279 globals = {
"__file__": filename}
1280 local = {root: self}
1281 if extraLocals
is not None:
1283 if root
in extraLocals:
1285 f
"{root} is reserved and cannot be used as a variable name in extraLocals"
1287 local.update(extraLocals)
1288 exec(code, globals, local)
1292 def save(self, filename, root="config"):
1293 """Save a Python script to the named file, which, when loaded,
1294 reproduces this config.
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`).
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
1312 d = os.path.dirname(filename)
1313 with tempfile.NamedTemporaryFile(mode=
"w", delete=
False, dir=d)
as outfile:
1318 umask = os.umask(0o077)
1320 os.chmod(outfile.name, (~umask & 0o666))
1324 shutil.move(outfile.name, filename)
1327 """Return the Python script form of this configuration as an executable
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.
1340 A code string readable by `loadFromString`.
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
1350 buffer = io.StringIO()
1352 return buffer.getvalue()
1355 """Save a configuration file to a stream, which, when loaded,
1356 reproduces this config.
1360 outfile : file-like object
1361 Destination file object write the config into. Accepts strings not
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.
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
1386 configType = type(self)
1387 typeString = _typeStr(configType)
1388 outfile.write(f
"import {configType.__module__}\n")
1390 f
"assert type({root})=={typeString}, 'config is of type %s.%s instead of "
1391 f
"{typeString}' % (type({root}).__module__, type({root}).__name__)\n"
1394 if imp
in sys.modules
and sys.modules[imp]
is not None:
1395 outfile.write(f
"import {imp}\n")
1401 """Make this config, and all subconfigs, read-only."""
1407 """Save this config to an open stream object.
1411 outfile : file-like object
1412 Destination file object write the config into. Accepts strings not
1416 field.save(outfile, 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
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
1433 """Make a dictionary of field names and their values.
1438 Dictionary with keys that are `~lsst.pex.config.Field` names.
1439 Values are `~lsst.pex.config.Field` values.
1443 lsst.pex.config.Field.toDict
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.
1453 dict_[name] = field.toDict(self)
1457 """Get all the field names in the config, recursively.
1461 names : `list` of `str`
1468 with io.StringIO()
as strFd:
1470 contents = strFd.getvalue()
1476 for line
in contents.split(
"\n"):
1477 if re.search(
r"^((assert|import)\s+|\s*$|#)", line):
1480 mat = re.search(
r"^(?:config\.)?([^=]+)\s*=\s*.*", line)
1482 keys.append(mat.group(1))
1487 """Rename this config object in its parent `~lsst.pex.config.Config`.
1492 New name for this config in its parent `~lsst.pex.config.Config`.
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.
1503 lsst.pex.config.Field.rename
1510 """Validate the Config, raising an exception if invalid.
1514 lsst.pex.config.FieldValidationError
1515 Raised if verification fails.
1519 The base class implementation performs type checks on all fields by
1520 calling their `~lsst.pex.config.Field.validate` methods.
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.
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.
1533 field.validate(self)
1536 """Format a configuration field's history to a human-readable format.
1541 Name of a `~lsst.pex.config.Field` in this config.
1543 Keyword arguments passed to `lsst.pex.config.history.format`.
1548 A string containing the formatted history.
1552 lsst.pex.config.history.format
1556 return pexHist.format(self, name, **kwargs)
1558 history = property(
lambda x: x._history)
1559 """Read-only history.
1563 """Set an attribute (such as a field's value).
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.
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
1579 f
"Config field {fullname} is deprecated: {self._fields[attr].deprecated}",
1586 self.
_fields_fields[attr].__set__(self, value, at=at, label=label)
1587 elif hasattr(getattr(self.
__class__, attr,
None),
"__set__"):
1589 return object.__setattr__(self, attr, value)
1590 elif attr
in self.__dict__
or attr
in (
"_name",
"_history",
"_storage",
"_frozen",
"_imports"):
1592 self.__dict__[attr] = value
1595 raise AttributeError(f
"{_typeStr(self)} has no attribute {attr}")
1603 object.__delattr__(self, attr)
1606 if type(other)
is type(self):
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):
1613 elif thisValue != otherValue:
1619 return not self.
__eq__(other)
1622 return str(self.
toDict())
1625 return "{}({})".format(
1627 ", ".join(f
"{k}={v!r}" for k, v
in self.
toDict().
items()
if v
is not None),
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
1636 other : `lsst.pex.config.Config`
1637 Other `~lsst.pex.config.Config` object to compare against this
1639 shortcut : `bool`, optional
1640 If `True`, return as soon as an inequality is found. Default is
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.
1653 `True` when the two `lsst.pex.config.Config` instances are equal.
1654 `False` if there is an inequality.
1658 lsst.pex.config.compareConfigs
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.
1666 Floating point comparisons are performed by `numpy.allclose`.
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)
1675 """Run initialization for every subclass.
1677 Specifically registers the subclass with a YAML representer
1678 and YAML constructor (if pyyaml is available)
1685 yaml.add_representer(cls, _yaml_config_representer)
1689 """Instantiate a `Config`-subclass from serialized Python form.
1694 A serialized form of the Config as created by
1695 `Config.saveToStream`.
1700 Reconstructed `Config` instant.
1707 """Return the Config subclass required by this Config serialization.
1712 A serialized form of the Config as created by
1713 `Config.saveToStream`.
1718 The `Config` subclass associated with this config.
1727 matches = re.search(
r"^import ([\w.]+)\nassert .*==(.*?),", config_py)
1730 first_line, second_line, _ = config_py.split(
"\n", 2)
1732 f
"First two lines did not match expected form. Got:\n - {first_line}\n - {second_line}"
1735 module_name = matches.group(1)
1736 module = importlib.import_module(module_name)
1739 full_name = matches.group(2)
1742 if not full_name.startswith(module_name):
1743 raise ValueError(f
"Module name ({module_name}) inconsistent with full name ({full_name})")
1748 remainder = full_name[len(module_name) + 1 :]
1749 components = remainder.split(
".")
1751 for component
in components:
1752 pytype = getattr(pytype, component)
1757 """Create a `~lsst.pex.config.Config` from a stream.
1761 cls_ : `lsst.pex.config.Config`-type
1762 A `lsst.pex.config.Config` type (not an instance) that is instantiated
1763 with configurations in the ``stream``.
1764 stream : file-like object, `str`, or `~types.CodeType`
1765 Stream containing configuration override code.
1769 config : `lsst.pex.config.Config`
1774 lsst.pex.config.Config.loadFromStream
1777 config.loadFromStream(stream)
std::vector< SchemaItem< Flag > > * items
Any __call__(self, *Any args, **Any kwds)
saveToStream(self, outfile, root="config", skipImports=False)
__setattr__(self, attr, value, at=None, label="assignment")
loadFromStream(self, stream, root="config", filename=None, extraLocals=None)
__new__(cls, *args, **kw)
save(self, filename, root="config")
_fromPython(cls, config_py)
loadFromString(self, code, root="config", filename=None, extraLocals=None)
__delattr__(self, attr, at=None, label="deletion")
saveToString(self, skipImports=False)
formatHistory(self, name, **kwargs)
__init_subclass__(cls, **kwargs)
load(self, filename, root="config")
compare(self, other, shortcut=True, rtol=1e-8, atol=1e-8, output=None)
Mapping[str, Any] _parseTypingArgs(tuple[type,...]|tuple[str,...] params, Mapping[str, Any] kwds)
save(self, outfile, instance)
_collectImports(self, instance, imports)
__get__(self, instance, owner=None, at=None, label="default")
FieldTypeVar __get__(self, Config instance, Any owner=None, Any at=None, str label="default")
__delete__(self, instance, at=None, label="deletion")
Field[FieldTypeVar] __get__(self, None instance, Any owner=None, Any at=None, str label="default")
_compare(self, instance1, instance2, shortcut, rtol, atol, output)
_validateValue(self, value)
None __set__(self, Config instance, FieldTypeVar|None value, Any at=None, str label="assignment")
__class_getitem__(cls, tuple[type,...]|type|ForwardRef params)
__init__(self, doc, dtype=None, default=None, check=None, optional=False, deprecated=None)
_setup(self, doc, dtype, default, check, optional, source, deprecated)
__init__(self, field, config, msg)
find_spec(self, fullname, path, target=None)
daf::base::PropertySet * set
_yaml_config_representer(dumper, data)
_classFromPython(config_py)
_joinNamePath(prefix=None, name=None, index=None)
unreduceConfig(cls_, stream)