LSST Applications g1653933729+a8ce1bb630,g171997e3ee+76e92115be,g1a997c3884+a8ce1bb630,g28da252d5a+4013ff5194,g2bbee38e9b+d6d0f9f6ae,g2bc492864f+d6d0f9f6ae,g2cdde0e794+ccb74358b7,g3156d2b45e+07302053f8,g347aa1857d+d6d0f9f6ae,g35bb328faa+a8ce1bb630,g3a166c0a6a+d6d0f9f6ae,g3e281a1b8c+130fae20e3,g4005a62e65+17cd334064,g414038480c+c9f68e2a12,g41af890bb2+3e1f62f438,g4e1a3235cc+9db7d56ad0,g7b55021d1b+7b623691d5,g80478fca09+334cc8d2bd,g82479be7b0+b568f6b267,g858d7b2824+37b39d8760,g9125e01d80+a8ce1bb630,ga5288a1d22+11cb34fefe,gae0086650b+a8ce1bb630,gb4ec7eb0ab+37b39d8760,gb58c049af0+d64f4d3760,gc081298178+284e133171,gc28159a63d+d6d0f9f6ae,gcf0d15dbbd+00fe2e0b07,gd6b7c0dfd1+8b62435e69,gda3e153d99+37b39d8760,gda6a2b7d83+00fe2e0b07,gdaeeff99f8+1711a396fd,gdd5a9049c5+23f3b3239a,ge2409df99d+5d9f551a54,ge33fd446bb+37b39d8760,ge79ae78c31+d6d0f9f6ae,gf0baf85859+2dea8344a2,gf5289d68f6+3777f3df5e,w.2024.41
LSST Data Management Base Package
|
Public Member Functions | |
__class_getitem__ (cls, tuple[type,...]|type|ForwardRef params) | |
__init__ (self, doc, dtype=None, default=None, check=None, optional=False, deprecated=None) | |
rename (self, instance) | |
validate (self, instance) | |
freeze (self, instance) | |
save (self, outfile, instance) | |
toDict (self, instance) | |
Field[FieldTypeVar] | __get__ (self, None instance, Any owner=None, Any at=None, str label="default") |
FieldTypeVar | __get__ (self, Config instance, Any owner=None, Any at=None, str label="default") |
__get__ (self, instance, owner=None, at=None, label="default") | |
None | __set__ (self, Config instance, FieldTypeVar|None value, Any at=None, str label="assignment") |
__delete__ (self, instance, at=None, label="deletion") | |
Public Attributes | |
dtype | |
doc | |
deprecated | |
default | |
check | |
optional | |
source | |
name | |
Static Public Attributes | |
str | name |
dict | supportedTypes = {str, bool, float, int, complex} |
Protected Member Functions | |
_setup (self, doc, dtype, default, check, optional, source, deprecated) | |
_validateValue (self, value) | |
_collectImports (self, instance, imports) | |
_compare (self, instance1, instance2, shortcut, rtol, atol, output) | |
Static Protected Member Functions | |
Mapping[str, Any] | _parseTypingArgs (tuple[type,...]|tuple[str,...] params, Mapping[str, Any] kwds) |
A field in a `~lsst.pex.config.Config` that supports `int`, `float`, `complex`, `bool`, and `str` data types. Parameters ---------- doc : `str` A description of the field for users. dtype : type, optional The field's data type. ``Field`` only supports basic data types: `int`, `float`, `complex`, `bool`, and `str`. See `Field.supportedTypes`. Optional if supplied as a typing argument to the class. default : object, optional The field's default value. check : callable, optional A callable that is called with the field's value. This callable should return `False` if the value is invalid. More complex inter-field validation can be written as part of the `lsst.pex.config.Config.validate` method. optional : `bool`, optional This sets whether the field is considered optional, and therefore doesn't need to be set by the user. When `False`, `lsst.pex.config.Config.validate` fails if the field's value is `None`. deprecated : None or `str`, optional A description of why this Field is deprecated, including removal date. If not None, the string is appended to the docstring for this Field. Raises ------ ValueError Raised when the ``dtype`` parameter is not one of the supported types (see `Field.supportedTypes`). See Also -------- ChoiceField ConfigChoiceField ConfigDictField ConfigField ConfigurableField DictField ListField RangeField RegistryField Notes ----- ``Field`` instances (including those of any subclass of ``Field``) are used as class attributes of `~lsst.pex.config.Config` subclasses (see the example, below). ``Field`` attributes work like the `property` attributes of classes that implement custom setters and getters. `Field` attributes belong to the class, but operate on the instance. Formally speaking, `Field` attributes are `descriptors <https://docs.python.org/3/howto/descriptor.html>`_. When you access a `Field` attribute on a `Config` instance, you don't get the `Field` instance itself. Instead, you get the value of that field, which might be a simple type (`int`, `float`, `str`, `bool`) or a custom container type (like a `lsst.pex.config.List`) depending on the field's type. See the example, below. Fields can be annotated with a type similar to other python classes (python specification `here <https://peps.python.org/pep-0484/#generics>`_ ). See the name field in the Config example below for an example of this. Unlike most other uses in python, this has an effect at type checking *and* runtime. If the type is specified with a class annotation, it will be used as the value of the ``dtype`` in the ``Field`` and there is no need to specify it as an argument during instantiation. There are Some notes on dtype through type annotation syntax. Type annotation syntax supports supplying the argument as a string of a type name. i.e. "float", but this cannot be used to resolve circular references. Type annotation syntax can be used on an identifier in addition to Class assignment i.e. ``variable: Field[str] = Config.someField`` vs ``someField = Field[str](doc="some doc"). However, this syntax is only useful for annotating the type of the identifier (i.e. variable in previous example) and does nothing for assigning the dtype of the ``Field``. Examples -------- Instances of ``Field`` should be used as class attributes of `lsst.pex.config.Config` subclasses: >>> from lsst.pex.config import Config, Field >>> class Example(Config): ... myInt = Field("An integer field.", int, default=0) ... name = Field[str](doc="A string Field") ... >>> print(config.myInt) 0 >>> config.myInt = 5 >>> print(config.myInt) 5
lsst.pex.config.config.Field.__init__ | ( | self, | |
doc, | |||
dtype = None, | |||
default = None, | |||
check = None, | |||
optional = False, | |||
deprecated = None ) |
Reimplemented in lsst.pex.config.rangeField.RangeField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.choiceField.ChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.listField.ListField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.dictField.DictField, lsst.pex.config.registry.RegistryField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configChoiceField.ConfigChoiceField, and lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField.
Definition at line 461 of file config.py.
Reimplemented in lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configChoiceField.ConfigChoiceField.
Definition at line 458 of file config.py.
lsst.pex.config.config.Field.__delete__ | ( | self, | |
instance, | |||
at = None, | |||
label = "deletion" ) |
Delete an attribute from a `lsst.pex.config.Config` instance. Parameters ---------- instance : `lsst.pex.config.Config` The config instance that contains this field. at : `list` of `lsst.pex.config.callStack.StackFrame` The call stack (created by `lsst.pex.config.callStack.getCallStack`). label : `str`, optional Event label for the history. Notes ----- This is invoked by the owning `~lsst.pex.config.Config` object and should not be called directly.
Definition at line 794 of file config.py.
FieldTypeVar lsst.pex.config.config.Field.__get__ | ( | self, | |
Config | instance, | ||
Any | owner = None, | ||
Any | at = None, | ||
str | label = "default" ) |
Reimplemented in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.
Definition at line 703 of file config.py.
lsst.pex.config.config.Field.__get__ | ( | self, | |
instance, | |||
owner = None, | |||
at = None, | |||
label = "default" ) |
Define how attribute access should occur on the Config instance This is invoked by the owning config object and should not be called directly. When the field attribute is accessed on a Config class object, it returns the field object itself in order to allow inspection of Config classes. When the field attribute is access on a config instance, the actual value described by the field (and held by the Config instance) is returned.
Reimplemented in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.
Definition at line 707 of file config.py.
Field[FieldTypeVar] lsst.pex.config.config.Field.__get__ | ( | self, | |
None | instance, | ||
Any | owner = None, | ||
Any | at = None, | ||
str | label = "default" ) |
Reimplemented in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.
Definition at line 698 of file config.py.
None lsst.pex.config.config.Field.__set__ | ( | self, | |
Config | instance, | ||
FieldTypeVar | None | value, | ||
Any | at = None, | ||
str | label = "assignment" ) |
Set an attribute on the config instance. Parameters ---------- instance : `lsst.pex.config.Config` The config instance that contains this field. value : obj Value to set on this field. at : `list` of `~lsst.pex.config.callStack.StackFrame` or `None`,\ optional The call stack (created by `lsst.pex.config.callStack.getCallStack`). label : `str`, optional Event label for the history. Notes ----- This method is invoked by the owning `lsst.pex.config.Config` object and should not be called directly. Derived `~lsst.pex.config.Field` classes may need to override the behavior. When overriding ``__set__``, `~lsst.pex.config.Field` authors should follow the following rules: - Do not allow modification of frozen configs. - Validate the new value **before** modifying the field. Except if the new value is `None`. `None` is special and no attempt should be made to validate it until `lsst.pex.config.Config.validate` is called. - Do not modify the `~lsst.pex.config.Config` instance to contain invalid values. - If the field is modified, update the history of the `lsst.pex.config.field.Field` to reflect the changes. In order to decrease the need to implement this method in derived `~lsst.pex.config.Field` types, value validation is performed in the `lsst.pex.config.Field._validateValue`. If only the validation step differs in the derived `~lsst.pex.config.Field`, it is simpler to implement `lsst.pex.config.Field._validateValue` than to reimplement ``__set__``. More complicated behavior, however, may require reimplementation.
Reimplemented in lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.listField.ListField, lsst.pex.config.dictField.DictField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.
Definition at line 734 of file config.py.
|
protected |
Call the _collectImports method on all config objects the field may own, and union them with the supplied imports set. Parameters ---------- instance : instance or subclass of `lsst.pex.config.Config` A config object that has this field defined on it imports : `set` Set of python modules that need imported after persistence
Reimplemented in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.
Definition at line 620 of file config.py.
|
protected |
Compare a field (named `Field.name`) in two `~lsst.pex.config.Config` instances for equality. Parameters ---------- instance1 : `lsst.pex.config.Config` Left-hand side `Config` instance to compare. instance2 : `lsst.pex.config.Config` Right-hand side `Config` instance to compare. shortcut : `bool`, optional **Unused.** 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. Notes ----- This method must be overridden by more complex `Field` subclasses. See Also -------- lsst.pex.config.compareScalars
Reimplemented in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.dictField.DictField, and lsst.pex.config.listField.ListField.
Definition at line 816 of file config.py.
|
staticprotected |
Parse type annotations into keyword constructor arguments. This is a special private method that interprets type arguments (i.e. Field[str]) into keyword arguments to be passed on to the constructor. Subclasses of Field can implement this method to customize how they handle turning type parameters into keyword arguments (see DictField for an example) Parameters ---------- params : `tuple` of `type` or `tuple` of str Parameters passed to the type annotation. These will either be types or strings. Strings are to interpreted as forward references and will be treated as such. kwds : `MutableMapping` with keys of `str` and values of `Any` These are the user supplied keywords that are to be passed to the Field constructor. Returns ------- kwds : `MutableMapping` with keys of `str` and values of `Any` The mapping of keywords that will be passed onto the constructor of the Field. Should be filled in with any information gleaned from the input parameters. Raises ------ ValueError Raised if params is of incorrect length. Raised if a forward reference could not be resolved Raised if there is a conflict between params and values in kwds
Reimplemented in lsst.pex.config.configurableField.ConfigurableField, and lsst.pex.config.dictField.DictField.
Definition at line 404 of file config.py.
|
protected |
Set attributes, usually during initialization.
Definition at line 480 of file config.py.
|
protected |
Validate a value. Parameters ---------- value : object The value being validated. Raises ------ TypeError Raised if the value's type is incompatible with the field's ``dtype``. ValueError Raised if the value is rejected by the ``check`` method.
Reimplemented in lsst.pex.config.choiceField.ChoiceField, and lsst.pex.config.rangeField.RangeField.
Definition at line 592 of file config.py.
lsst.pex.config.config.Field.freeze | ( | self, | |
instance ) |
Make this field read-only (for internal use only). Parameters ---------- instance : `lsst.pex.config.Config` The config instance that contains this field. Notes ----- Freezing is only relevant for fields that hold subconfigs. Fields which hold subconfigs should freeze each subconfig. **Subclasses should implement this method.**
Reimplemented in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.
Definition at line 575 of file config.py.
lsst.pex.config.config.Field.rename | ( | self, | |
instance ) |
Rename the field in a `~lsst.pex.config.Config` (for internal use only). Parameters ---------- instance : `lsst.pex.config.Config` The config instance that contains this field. Notes ----- This method is invoked by the `lsst.pex.config.Config` object that contains this field and should not be called directly. Renaming is only relevant for `~lsst.pex.config.Field` instances that hold subconfigs. `~lsst.pex.config.Field`\s that hold subconfigs should rename each subconfig with the full field name as generated by `lsst.pex.config.config._joinNamePath`.
Reimplemented in lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, and lsst.pex.config.configurableField.ConfigurableField.
Definition at line 525 of file config.py.
lsst.pex.config.config.Field.save | ( | self, | |
outfile, | |||
instance ) |
Save this field to a file (for internal use only). Parameters ---------- outfile : file-like object A writeable field handle. instance : `~lsst.pex.config.Config` The `~lsst.pex.config.Config` instance that contains this field. Notes ----- This method is invoked by the `~lsst.pex.config.Config` object that contains this field and should not be called directly. The output consists of the documentation string (`lsst.pex.config.Field.doc`) formatted as a Python comment. The second line is formatted as an assignment: ``{fullname}={value}``. This output can be executed with Python.
Reimplemented in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.
Definition at line 634 of file config.py.
lsst.pex.config.config.Field.toDict | ( | self, | |
instance ) |
Convert the field value so that it can be set as the value of an item in a `dict` (for internal use only). Parameters ---------- instance : `~lsst.pex.config.Config` The `~lsst.pex.config.Config` that contains this field. Returns ------- value : object The field's value. See *Notes*. Notes ----- This method invoked by the owning `~lsst.pex.config.Config` object and should not be called directly. Simple values are passed through. Complex data structures must be manipulated. For example, a `~lsst.pex.config.Field` holding a subconfig should, instead of the subconfig object, return a `dict` where the keys are the field names in the subconfig, and the values are the field values in the subconfig.
Reimplemented in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.dictField.DictField, and lsst.pex.config.listField.ListField.
Definition at line 670 of file config.py.
lsst.pex.config.config.Field.validate | ( | self, | |
instance ) |
Validate the field (for internal use only). Parameters ---------- instance : `lsst.pex.config.Config` The config instance that contains this field. Raises ------ lsst.pex.config.FieldValidationError Raised if verification fails. Notes ----- This method provides basic validation: - Ensures that the value is not `None` if the field is not optional. - Ensures type correctness. - Ensures that the user-provided ``check`` function is valid. Most `~lsst.pex.config.Field` subclasses should call `lsst.pex.config.Field.validate` if they re-implement `~lsst.pex.config.Field.validate`.
Reimplemented in lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.dictField.DictField, and lsst.pex.config.listField.ListField.
Definition at line 546 of file config.py.
|
static |