afscgap.param

  1"""
  2Description of request parameters to be used with any implementing backend.
  3
  4(c) 2025 Regents of University of California / The Eric and Wendy Schmidt Center
  5for Data Science and the Environment at UC Berkeley.
  6
  7This file is part of afscgap released under the BSD 3-Clause License. See
  8LICENSE.md.
  9"""
 10from afscgap.typesdef import OPT_FLOAT
 11from afscgap.typesdef import OPT_INT
 12from afscgap.typesdef import OPT_STR
 13
 14
 15class Param:
 16    """Interface for a backend-agnotic parameter."""
 17
 18    def __init__(self):
 19        """Create a new parameter."""
 20        raise NotImplementedError('Use implementor.')
 21
 22    def get_is_ignorable(self) -> bool:
 23        """Determine if this parameter can be ignored during filtering operations.
 24
 25        Returns:
 26            True if ignorable and false otherwise.
 27        """
 28        raise NotImplementedError('Use implementor.')
 29
 30    def get_data_type(self) -> str:
 31        """Get the data type of field on which this parameter operates.
 32
 33        Returns:
 34            Data type of the field like "str".
 35        """
 36        raise NotImplementedError('Use implementor.')
 37
 38    def get_filter_type(self) -> str:
 39        """Get the type of filter being applied by this parameter.
 40
 41        Returns:
 42            Get the type of filter like "equals" being applied.
 43        """
 44        raise NotImplementedError('Use implementor.')
 45
 46
 47class FieldParam:
 48    """Parameter which operates on a specific field."""
 49
 50    def __init__(self, field: str, param: Param):
 51        """Create a new field-specific parameter."""
 52        self._field = field
 53        self._param = param
 54
 55    def get_field(self) -> str:
 56        """Get the name of the field on which this parameter operates.
 57
 58        Returns:
 59            Name of the field on which this parameter operates.
 60        """
 61        return self._field
 62
 63    def get_param(self) -> Param:
 64        """Get the parameter to apply to this field.
 65
 66        Returns:
 67            Object describing the parameter to apply to this field.
 68        """
 69        return self._param
 70
 71
 72class EmptyParam(Param):
 73    """Parameter indicating that all records should be included."""
 74
 75    def __init__(self):
 76        """Create a parameter which matches all records."""
 77        pass
 78
 79    def get_is_ignorable(self) -> bool:
 80        return True
 81
 82    def get_data_type(self) -> str:
 83        return 'None'
 84
 85    def get_filter_type(self) -> str:
 86        return 'empty'
 87
 88
 89class StrEqualsParam(Param):
 90    """Parameter which requires a field to have a specific string value."""
 91
 92    def __init__(self, value: str):
 93        """Create a new string equals parameter.
 94
 95        Args:
 96            value: The string value that the field must have in order for its parent record to be
 97                included in the results set.
 98        """
 99        self._value = value
100
101    def get_value(self) -> str:
102        """Get the value that needs to be matched.
103
104        Returns:
105            String value that must be matched in order ofr a record to be included.
106        """
107        return self._value
108
109    def get_is_ignorable(self) -> bool:
110        return False
111
112    def get_data_type(self) -> str:
113        return 'str'
114
115    def get_filter_type(self) -> str:
116        return 'equals'
117
118
119class StrRangeParam(Param):
120    """Parameter which requires a field to fall within an alphanumeric range."""
121
122    def __init__(self, low: OPT_STR, high: OPT_STR):
123        """Create a new string range parameter.
124
125        Args:
126            low: The minimum value that a field may have for its record to be included or None if
127                no minimum to be enforced.
128            high: The maximum value that a field may have for its record to be incldued or None if
129                no maximum to be enforced.
130        """
131        self._low = low
132        self._high = high
133
134    def get_low(self) -> OPT_STR:
135        """Get the minimum allowed value.
136
137        Returns:
138            The minimum value that a field may have for its record to be included or None if no
139            minimum to be enforced.
140        """
141        return self._low
142
143    def get_high(self) -> OPT_STR:
144        """Get the maximum allowed value.
145
146        Returns:
147            The maximum value that a field may have for its record to be incldued or None if no
148            maximum to be enforced.
149        """
150        return self._high
151
152    def get_is_ignorable(self) -> bool:
153        return False
154
155    def get_data_type(self) -> str:
156        return 'str'
157
158    def get_filter_type(self) -> str:
159        return 'range'
160
161
162class IntEqualsParam(Param):
163    """Parameter which requires a field to have a specific integer value."""
164
165    def __init__(self, value: int):
166        """Create a new int equals parameter.
167
168        Args:
169            value: The int value that the field must have in order for its parent record to be
170                included in the results set.
171        """
172        self._value = value
173
174    def get_value(self) -> int:
175        """Get the value that needs to be matched.
176
177        Returns:
178            Integer value that must be matched in order ofr a record to be included.
179        """
180        return self._value
181
182    def get_is_ignorable(self) -> bool:
183        return False
184
185    def get_data_type(self) -> str:
186        return 'int'
187
188    def get_filter_type(self) -> str:
189        return 'equals'
190
191
192class IntRangeParam(Param):
193    """Parameter which requires a field to fall within an range defined by up to two integers."""
194
195    def __init__(self, low: OPT_INT, high: OPT_INT):
196        """Create a new integer range parameter.
197
198        Args:
199            low: The minimum value that a field may have for its record to be included or None if
200                no minimum to be enforced.
201            high: The maximum value that a field may have for its record to be incldued or None if
202                no maximum to be enforced.
203        """
204        self._low = low
205        self._high = high
206
207    def get_low(self) -> OPT_INT:
208        """Get the minimum allowed value.
209
210        Returns:
211            The minimum value that a field may have for its record to be included or None if no
212            minimum to be enforced.
213        """
214        return self._low
215
216    def get_high(self) -> OPT_INT:
217        """Get the maximum allowed value.
218
219        Returns:
220            The maximum value that a field may have for its record to be incldued or None if no
221            maximum to be enforced.
222        """
223        return self._high
224
225    def get_is_ignorable(self) -> bool:
226        return False
227
228    def get_data_type(self) -> str:
229        return 'int'
230
231    def get_filter_type(self) -> str:
232        return 'range'
233
234
235class FloatEqualsParam(Param):
236    """Parameter which requires a field to have a specific floating point value."""
237
238    def __init__(self, value: float):
239        """Create a new float equals parameter.
240
241        Args:
242            value: The float value that the field must have in order for its parent record to be
243                included in the results set.
244        """
245        self._value = value
246
247    def get_value(self) -> float:
248        """Get the value that needs to be matched.
249
250        Returns:
251            Float value that must be matched in order ofr a record to be included.
252        """
253        return self._value
254
255    def get_is_ignorable(self) -> bool:
256        return False
257
258    def get_data_type(self) -> str:
259        return 'float'
260
261    def get_filter_type(self) -> str:
262        return 'equals'
263
264
265class FloatRangeParam(Param):
266    """Parameter which requires a field to fall within an range defined by up to two floats."""
267
268    def __init__(self, low: OPT_FLOAT, high: OPT_FLOAT):
269        """Create a new float range parameter.
270
271        Args:
272            low: The minimum value that a field may have for its record to be included or None if
273                no minimum to be enforced.
274            high: The maximum value that a field may have for its record to be incldued or None if
275                no maximum to be enforced.
276        """
277        self._low = low
278        self._high = high
279
280    def get_low(self) -> OPT_FLOAT:
281        """Get the minimum allowed value.
282
283        Returns:
284            The minimum value that a field may have for its record to be included or None if no
285            minimum to be enforced.
286        """
287        return self._low
288
289    def get_high(self) -> OPT_FLOAT:
290        """Get the maximum allowed value.
291
292        Returns:
293            The maximum value that a field may have for its record to be incldued or None if no
294            maximum to be enforced.
295        """
296        return self._high
297
298    def get_is_ignorable(self) -> bool:
299        return False
300
301    def get_data_type(self) -> str:
302        return 'float'
303
304    def get_filter_type(self) -> str:
305        return 'range'