LSST Applications g013ef56533+7c9321ec0f,g042eb84c57+c6cfa41bc3,g199a45376c+0ba108daf9,g1fd858c14a+fcad0d0313,g210f2d0738+c0f94c6586,g262e1987ae+a7e710680e,g29ae962dfc+fb55f2edb0,g2ac17093b6+61d6563b1e,g2b1d02342f+df6f932764,g2cef7863aa+aef1011c0b,g2f7ad74990+c0f94c6586,g35bb328faa+8c5ae1fdc5,g3fd5ace14f+53cf87ae69,g47891489e3+4316d04fff,g511e8cfd20+baa56acf6c,g53246c7159+8c5ae1fdc5,g54cd7ddccb+fd7ad03fde,g64539dfbff+c0f94c6586,g67b6fd64d1+4316d04fff,g67fd3c3899+c0f94c6586,g6985122a63+4316d04fff,g74acd417e5+ca833bee28,g786e29fd12+668abc6043,g81db2e9a8d+b2ec8e584f,g87389fa792+8856018cbb,g89139ef638+4316d04fff,g8d7436a09f+0a24083b20,g8ea07a8fe4+760ca7c3fc,g90f42f885a+033b1d468d,g97be763408+11eb8fd5b8,gbf99507273+8c5ae1fdc5,gcdda8b9158+e4c84c9d5c,gce8aa8abaa+8c5ae1fdc5,gd7ef33dd92+4316d04fff,gdab6d2f7ff+ca833bee28,ge410e46f29+4316d04fff,geaed405ab2+c4bbc419c6,gf9a733ac38+8c5ae1fdc5,w.2025.40
LSST Data Management Base Package
Loading...
Searching...
No Matches
choiceField.py
Go to the documentation of this file.
1# This file is part of pex_config.
2#
3# Developed for the LSST Data Management System.
4# This product includes software developed by the LSST Project
5# (http://www.lsst.org).
6# See the COPYRIGHT file at the top-level directory of this distribution
7# for details of code ownership.
8#
9# This software is dual licensed under the GNU General Public License and also
10# under a 3-clause BSD license. Recipients may choose which of these licenses
11# to use; please see the files gpl-3.0.txt and/or bsd_license.txt,
12# respectively. If you choose the GPL option then the following text applies
13# (but note that there is still no warranty even if you opt for BSD instead):
14#
15# This program is free software: you can redistribute it and/or modify
16# it under the terms of the GNU General Public License as published by
17# the Free Software Foundation, either version 3 of the License, or
18# (at your option) any later version.
19#
20# This program is distributed in the hope that it will be useful,
21# but WITHOUT ANY WARRANTY; without even the implied warranty of
22# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23# GNU General Public License for more details.
24#
25# You should have received a copy of the GNU General Public License
26# along with this program. If not, see <http://www.gnu.org/licenses/>.
27
28__all__ = ["ChoiceField"]
29
30from .callStack import getStackFrame
31from .config import Field, FieldTypeVar, _typeStr
32
33
34class ChoiceField(Field[FieldTypeVar]):
35 """A configuration field (`~lsst.pex.config.Field` subclass) that allows a
36 user to select from a predefined set of values.
37
38 Use ``ChoiceField`` when a configuration can only take one of a predefined
39 set of values. Each choice must be of the same type.
40
41 Parameters
42 ----------
43 doc : `str`
44 Documentation string that describes the configuration field.
45 dtype : class
46 The type of the field's choices. For example, `str` or `int`.
47 allowed : `dict`
48 The allowed values. Keys are the allowed choices (of ``dtype``-type).
49 Values are descriptions (`str`-type) of each choice.
50 default : ``dtype``-type, optional
51 The default value, which is of type ``dtype`` and one of the allowed
52 choices.
53 optional : `bool`, optional
54 If `True`, this configuration field is *optional*. Default is `True`.
55 deprecated : None or `str`, optional
56 A description of why this Field is deprecated, including removal date.
57 If not None, the string is appended to the docstring for this Field.
58
59 See Also
60 --------
61 ConfigChoiceField
62 ConfigDictField
63 ConfigField
64 ConfigurableField
65 DictField
66 Field
67 ListField
68 RangeField
69 RegistryField
70 """
71
72 def __init__(self, doc, dtype=None, allowed=None, default=None, optional=True, deprecated=None):
73 if dtype is None:
74 raise ValueError("supplied dtype must not be None")
75 if allowed is None:
76 raise ValueError("supplied allowed mapping must not be None")
77 self.allowed = dict(allowed)
78 if optional and None not in self.allowed:
79 self.allowed[None] = "Field is optional"
80
81 if len(self.allowed) == 0:
82 raise ValueError("ChoiceFields must allow at least one choice")
83
84 Field.__init__(
85 self, doc=doc, dtype=dtype, default=default, check=None, optional=optional, deprecated=deprecated
86 )
87
88 self.__doc__ += "\n\nAllowed values:\n\n"
89 for choice, choiceDoc in self.allowed.items():
90 if choice is not None and not isinstance(choice, dtype):
91 raise ValueError(
92 f"ChoiceField's allowed choice {choice} is of incorrect type "
93 f"{_typeStr(choice)}. Expected {_typeStr(dtype)}"
94 )
95 # Force to a string so that additional quotes are added with !r
96 self.__doc__ += f"``{str(choice)!r}``\n {choiceDoc}\n"
97
98 self.source = getStackFrame()
99
100 def _validateValue(self, value):
101 Field._validateValue(self, value)
102 if value not in self.allowed:
103 msg = "Value {} is not allowed.\n\tAllowed values: [{}]".format(
104 value, ", ".join(str(key) for key in self.allowed)
105 )
106 raise ValueError(msg)
__init__(self, doc, dtype=None, allowed=None, default=None, optional=True, deprecated=None)