LSSTApplications  17.0+11,17.0+34,17.0+56,17.0+57,17.0+59,17.0+7,17.0-1-g377950a+33,17.0.1-1-g114240f+2,17.0.1-1-g4d4fbc4+28,17.0.1-1-g55520dc+49,17.0.1-1-g5f4ed7e+52,17.0.1-1-g6dd7d69+17,17.0.1-1-g8de6c91+11,17.0.1-1-gb9095d2+7,17.0.1-1-ge9fec5e+5,17.0.1-1-gf4e0155+55,17.0.1-1-gfc65f5f+50,17.0.1-1-gfc6fb1f+20,17.0.1-10-g87f9f3f+1,17.0.1-11-ge9de802+16,17.0.1-16-ga14f7d5c+4,17.0.1-17-gc79d625+1,17.0.1-17-gdae4c4a+8,17.0.1-2-g26618f5+29,17.0.1-2-g54f2ebc+9,17.0.1-2-gf403422+1,17.0.1-20-g2ca2f74+6,17.0.1-23-gf3eadeb7+1,17.0.1-3-g7e86b59+39,17.0.1-3-gb5ca14a,17.0.1-3-gd08d533+40,17.0.1-30-g596af8797,17.0.1-4-g59d126d+4,17.0.1-4-gc69c472+5,17.0.1-6-g5afd9b9+4,17.0.1-7-g35889ee+1,17.0.1-7-gc7c8782+18,17.0.1-9-gc4bbfb2+3,w.2019.22
LSSTDataManagementBasePackage
Public Member Functions | Public Attributes | Static Public Attributes | List of all members
lsst.pex.config.configField.ConfigField Class Reference
Inheritance diagram for lsst.pex.config.configField.ConfigField:
lsst.pex.config.config.Field

Public Member Functions

def __init__ (self, doc, dtype, default=None, check=None)
 
def __get__ (self, instance, owner=None)
 
def __set__ (self, instance, value, at=None, label="assignment")
 
def rename (self, instance)
 
def save (self, outfile, instance)
 
def freeze (self, instance)
 
def toDict (self, instance)
 
def validate (self, instance)
 
def __get__ (self, instance, owner=None, at=None, label="default")
 
def __delete__ (self, instance, at=None, label='deletion')
 

Public Attributes

 dtype
 
 doc
 
 default
 
 check
 
 optional
 
 source
 

Static Public Attributes

 supportedTypes = set((str, bool, float, int, complex))
 

Detailed Description

A configuration field (`~lsst.pex.config.Field` subclass) that takes a
`~lsst.pex.config.Config`-type as a value.

Parameters
----------
doc : `str`
    A description of the configuration field.
dtype : `lsst.pex.config.Config`-type
    The type of the field, which must be a subclass of
    `lsst.pex.config.Config`.
default : `lsst.pex.config.Config`, optional
    If default is `None`, the field will default to a default-constructed
    instance of ``dtype``. Additionally, to allow for fewer deep-copies,
    assigning an instance of ``ConfigField`` to ``dtype`` itself, is
    considered equivalent to assigning a default-constructed sub-config.
    This means that the argument default can be ``dtype``, as well as an
    instance of ``dtype``.
check : callable, optional
    A callback function that validates the field's value, returning `True`
    if the value is valid, and `False` otherwise.

See also
--------
ChoiceField
ConfigChoiceField
ConfigDictField
ConfigurableField
DictField
Field
ListField
RangeField
RegistryField

Notes
-----
The behavior of this type of field is much like that of the base `Field`
type.

Assigning to ``ConfigField`` will update all of the fields in the
configuration.

Definition at line 30 of file configField.py.

Constructor & Destructor Documentation

◆ __init__()

def lsst.pex.config.configField.ConfigField.__init__ (   self,
  doc,
  dtype,
  default = None,
  check = None 
)

Definition at line 73 of file configField.py.

73  def __init__(self, doc, dtype, default=None, check=None):
74  if not issubclass(dtype, Config):
75  raise ValueError("dtype=%s is not a subclass of Config" %
76  _typeStr(dtype))
77  if default is None:
78  default = dtype
79  source = getStackFrame()
80  self._setup(doc=doc, dtype=dtype, default=default, check=check,
81  optional=False, source=source)
82 
lsst.pex.config.callStack.getStackFrame
def getStackFrame(relative=0)
Definition: callStack.py:52
lsst::afw.display.rgb.rgbContinued.__init__
def __init__(self, minimum, dataRange, Q)
Definition: rgbContinued.py:476

Member Function Documentation

◆ __delete__()

def lsst.pex.config.config.Field.__delete__ (   self,
  instance,
  at = None,
  label = 'deletion' 
)
inherited 
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 551 of file config.py.

551  def __delete__(self, instance, at=None, label='deletion'):
552  """Delete an attribute from a `lsst.pex.config.Config` instance.
553 
554  Parameters
555  ----------
556  instance : `lsst.pex.config.Config`
557  The config instance that contains this field.
558  at : `list` of `lsst.pex.config.callStack.StackFrame`
559  The call stack (created by
560  `lsst.pex.config.callStack.getCallStack`).
561  label : `str`, optional
562  Event label for the history.
563 
564  Notes
565  -----
566  This is invoked by the owning `~lsst.pex.config.Config` object and
567  should not be called directly.
568  """
569  if at is None:
570  at = getCallStack()
571  self.__set__(instance, None, at=at, label=label)
572 
lsst.pex.config.callStack.getCallStack
def getCallStack(skip=0)
Definition: callStack.py:169

◆ __get__() [1/2]

def lsst.pex.config.configField.ConfigField.__get__ (   self,
  instance,
  owner = None 
)

Definition at line 83 of file configField.py.

83  def __get__(self, instance, owner=None):
84  if instance is None or not isinstance(instance, Config):
85  return self
86  else:
87  value = instance._storage.get(self.name, None)
88  if value is None:
89  at = getCallStack()
90  at.insert(0, self.source)
91  self.__set__(instance, self.default, at=at, label="default")
92  return value
93 
lsst.pex.config.callStack.getCallStack
def getCallStack(skip=0)
Definition: callStack.py:169

◆ __get__() [2/2]

def lsst.pex.config.config.Field.__get__ (   self,
  instance,
  owner = None,
  at = None,
  label = "default" 
)
inherited 
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.

Definition at line 476 of file config.py.

476  def __get__(self, instance, owner=None, at=None, label="default"):
477  """Define how attribute access should occur on the Config instance
478  This is invoked by the owning config object and should not be called
479  directly
480 
481  When the field attribute is accessed on a Config class object, it
482  returns the field object itself in order to allow inspection of
483  Config classes.
484 
485  When the field attribute is access on a config instance, the actual
486  value described by the field (and held by the Config instance) is
487  returned.
488  """
489  if instance is None or not isinstance(instance, Config):
490  return self
491  else:
492  return instance._storage[self.name]
493 

◆ __set__()

def lsst.pex.config.configField.ConfigField.__set__ (   self,
  instance,
  value,
  at = None,
  label = "assignment" 
)

Definition at line 94 of file configField.py.

94  def __set__(self, instance, value, at=None, label="assignment"):
95  if instance._frozen:
96  raise FieldValidationError(self, instance,
97  "Cannot modify a frozen Config")
98  name = _joinNamePath(prefix=instance._name, name=self.name)
99 
100  if value != self.dtype and type(value) != self.dtype:
101  msg = "Value %s is of incorrect type %s. Expected %s" % \
102  (value, _typeStr(value), _typeStr(self.dtype))
103  raise FieldValidationError(self, instance, msg)
104 
105  if at is None:
106  at = getCallStack()
107 
108  oldValue = instance._storage.get(self.name, None)
109  if oldValue is None:
110  if value == self.dtype:
111  instance._storage[self.name] = self.dtype(__name=name, __at=at, __label=label)
112  else:
113  instance._storage[self.name] = self.dtype(__name=name, __at=at,
114  __label=label, **value._storage)
115  else:
116  if value == self.dtype:
117  value = value()
118  oldValue.update(__at=at, __label=label, **value._storage)
119  history = instance._history.setdefault(self.name, [])
120  history.append(("config value set", at, label))
121 
lsst.pex.config.callStack.getCallStack
def getCallStack(skip=0)
Definition: callStack.py:169
type
table::Key< int > type
Definition: Detector.cc:167

◆ freeze()

def lsst.pex.config.configField.ConfigField.freeze (   self,
  instance 
) 
Make this field read-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.**

Definition at line 173 of file configField.py.

173  def freeze(self, instance):
174  """Make this field read-only.
175 
176  Parameters
177  ----------
178  instance : `lsst.pex.config.Config`
179  The config instance that contains this field.
180 
181  Notes
182  -----
183  Freezing is only relevant for fields that hold subconfigs. Fields which
184  hold subconfigs should freeze each subconfig.
185 
186  **Subclasses should implement this method.**
187  """
188  value = self.__get__(instance)
189  value.freeze()
190 

◆ rename()

def lsst.pex.config.configField.ConfigField.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.Fields` that hold subconfigs should
rename each subconfig with the full field name as generated by
`lsst.pex.config.config._joinNamePath`.

Definition at line 122 of file configField.py.

122  def rename(self, instance):
123  """Rename the field in a `~lsst.pex.config.Config` (for internal use
124  only).
125 
126  Parameters
127  ----------
128  instance : `lsst.pex.config.Config`
129  The config instance that contains this field.
130 
131  Notes
132  -----
133  This method is invoked by the `lsst.pex.config.Config` object that
134  contains this field and should not be called directly.
135 
136  Renaming is only relevant for `~lsst.pex.config.Field` instances that
137  hold subconfigs. `~lsst.pex.config.Fields` that hold subconfigs should
138  rename each subconfig with the full field name as generated by
139  `lsst.pex.config.config._joinNamePath`.
140  """
141  value = self.__get__(instance)
142  value._rename(_joinNamePath(instance._name, self.name))
143 

◆ save()

def lsst.pex.config.configField.ConfigField.save (   self,
  outfile,
  instance 
) 
Save this field to a file (for internal use only).

Parameters
----------
outfile : file-like object
    A writeable field handle.
instance : `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.

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.

Definition at line 149 of file configField.py.

149  def save(self, outfile, instance):
150  """Save this field to a file (for internal use only).
151 
152  Parameters
153  ----------
154  outfile : file-like object
155  A writeable field handle.
156  instance : `Config`
157  The `Config` instance that contains this field.
158 
159  Notes
160  -----
161  This method is invoked by the `~lsst.pex.config.Config` object that
162  contains this field and should not be called directly.
163 
164  The output consists of the documentation string
165  (`lsst.pex.config.Field.doc`) formatted as a Python comment. The second
166  line is formatted as an assignment: ``{fullname}={value}``.
167 
168  This output can be executed with Python.
169  """
170  value = self.__get__(instance)
171  value._save(outfile)
172 

◆ toDict()

def lsst.pex.config.configField.ConfigField.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 : `Config`
    The `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.

Definition at line 191 of file configField.py.

191  def toDict(self, instance):
192  """Convert the field value so that it can be set as the value of an
193  item in a `dict` (for internal use only).
194 
195  Parameters
196  ----------
197  instance : `Config`
198  The `Config` that contains this field.
199 
200  Returns
201  -------
202  value : object
203  The field's value. See *Notes*.
204 
205  Notes
206  -----
207  This method invoked by the owning `~lsst.pex.config.Config` object and
208  should not be called directly.
209 
210  Simple values are passed through. Complex data structures must be
211  manipulated. For example, a `~lsst.pex.config.Field` holding a
212  subconfig should, instead of the subconfig object, return a `dict`
213  where the keys are the field names in the subconfig, and the values are
214  the field values in the subconfig.
215  """
216  value = self.__get__(instance)
217  return value.toDict()
218 

◆ validate()

def lsst.pex.config.configField.ConfigField.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.Field.validate` if they re-implement
`~lsst.pex.config.field.Field.validate`.

Definition at line 219 of file configField.py.

219  def validate(self, instance):
220  """Validate the field (for internal use only).
221 
222  Parameters
223  ----------
224  instance : `lsst.pex.config.Config`
225  The config instance that contains this field.
226 
227  Raises
228  ------
229  lsst.pex.config.FieldValidationError
230  Raised if verification fails.
231 
232  Notes
233  -----
234  This method provides basic validation:
235 
236  - Ensures that the value is not `None` if the field is not optional.
237  - Ensures type correctness.
238  - Ensures that the user-provided ``check`` function is valid.
239 
240  Most `~lsst.pex.config.Field` subclasses should call
241  `lsst.pex.config.field.Field.validate` if they re-implement
242  `~lsst.pex.config.field.Field.validate`.
243  """
244  value = self.__get__(instance)
245  value.validate()
246 
247  if self.check is not None and not self.check(value):
248  msg = "%s is not a valid value" % str(value)
249  raise FieldValidationError(self, instance, msg)
250 

Member Data Documentation

◆ check

lsst.pex.config.config.Field.check
inherited

Definition at line 293 of file config.py.

◆ default

lsst.pex.config.config.Field.default
inherited

Definition at line 289 of file config.py.

◆ doc

lsst.pex.config.config.Field.doc
inherited

Definition at line 280 of file config.py.

◆ dtype

lsst.pex.config.config.Field.dtype
inherited

Definition at line 276 of file config.py.

◆ optional

lsst.pex.config.config.Field.optional
inherited

Definition at line 297 of file config.py.

◆ source

lsst.pex.config.config.Field.source
inherited

Definition at line 304 of file config.py.

◆ supportedTypes

lsst.pex.config.config.Field.supportedTypes = set((str, bool, float, int, complex))
staticinherited

Definition at line 262 of file config.py.

The documentation for this class was generated from the following file:
Generated on Sat Jun 8 2019 08:10:20 for LSSTApplications by   doxygen 1.8.13