squirrels 0.3.3__py3-none-any.whl → 0.4.0__py3-none-any.whl

squirrels/parameter_options.py

@@ -1,13 +1,13 @@
-from typing import Set, Iterable, Optional, Union, Any
-from dataclasses import dataclass, field
+from typing import TypeVar, Iterable, Any
+from dataclasses import dataclass
 from decimal import Decimal, InvalidOperation as InvalidDecimalConversion
 from datetime import datetime, date
 from abc import ABCMeta, abstractmethod
-import re
 
 from ._utils import ConfigurationError
 
-Number = Union[Decimal, int, str]
+Number = Decimal | int | float | str
+Comparables = TypeVar("Comparables", Decimal, date)
 
 
 @dataclass
@@ -15,26 +15,25 @@ class ParameterOption(metaclass=ABCMeta):
     """
     Abstract class for parameter options
     """
-    _user_groups: Set[Any] # = field(default_factory=frozenset, kw_only=True)
-    _parent_option_ids: Set[str] # = field(default_factory=frozenset, kw_only=True)
+    _user_groups: frozenset[Any]
+    _parent_option_ids: frozenset[str]
 
     @abstractmethod
     def __init__(
-        self, *, user_groups: Union[Iterable[Any], str] = frozenset(), parent_option_ids: Union[Iterable[str], str] = frozenset(), **kwargs
+        self, *, user_groups: Iterable[Any] | str = frozenset(), parent_option_ids: Iterable[str] | str = frozenset(), **kwargs
     ) -> None:
         self._user_groups = frozenset({user_groups} if isinstance(user_groups, str) else user_groups)
         self._parent_option_ids = frozenset({parent_option_ids} if isinstance(parent_option_ids, str) else parent_option_ids)
 
-    def _validate_lower_upper_values(self, lower_label: str, lower_value: Union[Decimal, date], 
-                                     upper_label: str, upper_value: Union[Decimal, date]):
+    def _validate_lower_upper_values(self, lower_label: str, lower_value: Comparables, upper_label: str, upper_value: Comparables):
         if lower_value > upper_value:
             raise ConfigurationError(f'The {lower_label} "{lower_value}" must be less than or equal to the {upper_label} "{upper_value}"')
 
-    def _is_valid(self, user_group: Any, selected_parent_option_ids: Optional[Iterable[str]]) -> bool:
+    def _is_valid(self, user_group: Any, selected_parent_option_ids: Iterable[str] | None) -> bool:
         """
         Checks if this option is valid given the selected parent options and user group of user if applicable.
         
-        Parameters:
+        Arguments:
             user_group: The value of the user's "user group attribute". Only None when "user_attribute" is not specified
                 for the Parameter factory. Note that when user is None but "user_attribute" is specified, an error is thrown
             selected_parent_option_ids: List of selected option ids from the parent parameter. Only None when the Parameter
@@ -56,29 +55,26 @@ class ParameterOption(metaclass=ABCMeta):
 class SelectParameterOption(ParameterOption):
     """
     Parameter option for a select parameter
-
-    Attributes:
-        identifier: Unique identifier for this option that never changes over time
-        label: Human readable label that gets shown as a dropdown option
-        is_default: True if this is a default option, False otherwise
-        user_groups: The user groups this parameter option would show for if "user_attribute" is specified in the Parameter factory
-        parent_option_ids: Set of parent option ids this parameter option would show for if "parent" is specified in the Parameter factory
-        custom_fields: Dictionary to associate custom attributes to the parameter option
     """
     _identifier: str
     _label: str
-    _is_default: bool # = field(default=False, kw_only=True)
-    custom_fields: dict[str, Any] # = field(default_factory=False, kw_only=True)
+    _is_default: bool
+    custom_fields: dict[str, Any]
 
     def __init__(
-        self, id: str, label: str, *, is_default: bool = False, user_groups: Union[Iterable[Any], str] = frozenset(), 
-        parent_option_ids: Union[Iterable[str], str] = frozenset(), custom_fields: dict[str, Any] = {}, **kwargs
+        self, id: str, label: str, *, is_default: bool = False, user_groups: Iterable[Any] | str = frozenset(), 
+        parent_option_ids: Iterable[str] | str = frozenset(), custom_fields: dict[str, Any] = {}, **kwargs
     ) -> None:
         """
         Constructor for SelectParameterOption
 
-        Parameters:
-            ...see Attributes of SelectParameterOption
+        Arguments:
+            identifier: Unique identifier for this option that never changes over time
+            label: Human readable label that gets shown as a dropdown option
+            is_default: True if this is a default option, False otherwise
+            user_groups: The user groups this parameter option would show for if "user_attribute" is specified in the Parameter factory
+            parent_option_ids: Set of parent option ids this parameter option would show for if "parent" is specified in the Parameter factory
+            custom_fields: Dictionary to associate custom attributes to the parameter option
             **kwargs: Any additional keyword arguments specified (except the ones above) gets included into custom_fields as well
         """
         super().__init__(user_groups=user_groups, parent_option_ids=parent_option_ids)
@@ -89,11 +85,11 @@ class SelectParameterOption(ParameterOption):
             **kwargs, **custom_fields, **self._to_json_dict()
         }
 
-    def get_custom_field(self, field: str, *, default_field: Optional[str] = None, default: Any = None, **kwargs) -> Any:
+    def get_custom_field(self, field: str, *, default_field: str | None = None, default: Any = None, **kwargs) -> Any:
         """
         Get field value from the custom_fields attribute
 
-        Parameters:
+        Arguments:
             field: The key to use to fetch the custom field from "custom_fields"
             default_field: If value at "field" key does not exist in "custom_fields", then this is used instead as the field (if not None)
             default: If value at "field" or "default_field" (if not None) key does not exist in "custom_fields", then this value 
@@ -124,47 +120,62 @@ class _DateTypeParameterOption(ParameterOption):
     """
     Abstract class (or type) for date type parameter options
     """
-    _date_format: str # = field(default="%Y-%m-%d", kw_only=True)
+    _min_date: date | None
+    _max_date: date | None
+    _date_format: str
 
     @abstractmethod
     def __init__(
-        self, *, date_format: str = '%Y-%m-%d', user_groups: Union[Iterable[Any], str] = frozenset(), 
-        parent_option_ids: Union[Iterable[str], str] = frozenset(), **kwargs
+        self, *, min_date: str | date | None = None, max_date: str | date | None = None, date_format: str = '%Y-%m-%d', 
+        user_groups: Iterable[Any] | str = frozenset(), parent_option_ids: Iterable[str] | str = frozenset(), **kwargs
     ) -> None:
         super().__init__(user_groups=user_groups, parent_option_ids=parent_option_ids)
         self._date_format = date_format
-    
-    def _validate_date(self, date_str: Union[str, date]) -> date:
+        self._min_date, self._max_date = None, None # preset for using _validate_date()
+        self._min_date = self._validate_date(min_date) if min_date is not None else None
+        self._max_date = self._validate_date(max_date) if max_date is not None else None
+        if self._min_date is not None and self._max_date is not None:
+            self._validate_lower_upper_values("min_date", self._min_date, "max_date", self._max_date)
+
+    def _validate_date(self, date_str: str | date) -> date:
         try:
-            return datetime.strptime(date_str, self._date_format).date() if isinstance(date_str, str) else date_str
+            date_obj = datetime.strptime(date_str, self._date_format).date() if isinstance(date_str, str) else date_str
         except ValueError as e:
             raise ConfigurationError(f'Invalid format for date "{date_str}".') from e
+        
+        if self._min_date is not None and date_obj < self._min_date:
+            raise ConfigurationError(f'The provided date "{date_obj}" is less than the min date "{self._min_date}"')
+        if self._max_date is not None and date_obj > self._max_date:
+            raise ConfigurationError(f'The provided date "{date_obj}" is greater than the max date "{self._max_date}"')
+        
+        return date_obj
     
 
 @dataclass
 class DateParameterOption(_DateTypeParameterOption):
     """
     Parameter option for default dates if it varies based on selection of another parameter
-
-    Attributes:
-        default_date: Default date for this option
-        date_format: Format of the default date, default is '%Y-%m-%d'
-        user_groups: The user groups this parameter option would show for if "user_attribute" is specified in the Parameter factory
-        parent_option_ids: Set of parent option ids this parameter option would show for if "parent" is specified in the Parameter factory
     """
     _default_date: date
 
     def __init__(
-        self, default_date: Union[str, date], *, date_format: str = '%Y-%m-%d', user_groups: Union[Iterable[Any], str] = frozenset(), 
-        parent_option_ids: Union[Iterable[str], str] = frozenset(), **kwargs
+        self, default_date: str | date, *, min_date: str | date | None = None, max_date: str | date | None = None, date_format: str = '%Y-%m-%d',
+        user_groups: Iterable[Any] | str = frozenset(), parent_option_ids: Iterable[str] | str = frozenset(), **kwargs
     ) -> None:
         """
         Constructor for DateParameterOption
 
-        Parameters:
-            ...see Attributes of DateParameterOption
+        Arguments:
+            default_date: Default date for this option
+            min_date: Minimum date for this option
+            max_date: Maximum date for this option
+            date_format: Format of the default date, default is '%Y-%m-%d'
+            user_groups: The user groups this parameter option would show for if "user_attribute" is specified in the Parameter factory
+            parent_option_ids: Set of parent option ids this parameter option would show for if "parent" is specified in the Parameter factory
         """
-        super().__init__(date_format=date_format, user_groups=user_groups, parent_option_ids=parent_option_ids)
+        super().__init__(
+            date_format=date_format, min_date=min_date, max_date=max_date, user_groups=user_groups, parent_option_ids=parent_option_ids
+        )
         self._default_date = self._validate_date(default_date)
 
 
@@ -172,28 +183,30 @@ class DateParameterOption(_DateTypeParameterOption):
 class DateRangeParameterOption(_DateTypeParameterOption):
     """
     Parameter option for default dates if it varies based on selection of another parameter
-
-    Attributes:
-        default_start_date: Default start date for this option
-        default_end_date: Default end date for this option
-        date_format: Format of the default date, default is '%Y-%m-%d'
-        user_groups: The user groups this parameter option would show for if "user_attribute" is specified in the Parameter factory
-        parent_option_ids: Set of parent option ids this parameter option would show for if "parent" is specified in the Parameter factory
     """
     _default_start_date: date
     _default_end_date: date
 
     def __init__(
-        self, default_start_date: Union[str, date], default_end_date: Union[str, date], *, date_format: str = '%Y-%m-%d', 
-        user_groups: Union[Iterable[Any], str] = frozenset(), parent_option_ids: Union[Iterable[str], str] = frozenset(), **kwargs
+        self, default_start_date: str | date, default_end_date: str | date, *, min_date: str | date | None = None, 
+        max_date: str | date | None = None, date_format: str = '%Y-%m-%d', user_groups: Iterable[Any] | str = frozenset(), 
+        parent_option_ids: Iterable[str] | str = frozenset(), **kwargs
     ) -> None:
         """
         Constructor for DateRangeParameterOption
 
-        Parameters:
-            ...see Attributes of DateRangeParameterOption
+        Arguments:
+            default_start_date: Default start date for this option
+            default_end_date: Default end date for this option
+            min_date: Minimum date for this option
+            max_date: Maximum date for this option
+            date_format: Format of the default date, default is '%Y-%m-%d'
+            user_groups: The user groups this parameter option would show for if "user_attribute" is specified in the Parameter factory
+            parent_option_ids: Set of parent option ids this parameter option would show for if "parent" is specified in the Parameter factory
         """
-        super().__init__(date_format=date_format, user_groups=user_groups, parent_option_ids=parent_option_ids)
+        super().__init__(
+            date_format=date_format, min_date=min_date, max_date=max_date, user_groups=user_groups, parent_option_ids=parent_option_ids
+        )
         self._default_start_date = self._validate_date(default_start_date)
         self._default_end_date = self._validate_date(default_end_date)
         self._validate_lower_upper_values("default_start_date", self._default_start_date, "default_end_date", self._default_end_date)
@@ -206,12 +219,12 @@ class _NumericParameterOption(ParameterOption):
     """
     _min_value: Decimal
     _max_value: Decimal
-    _increment: Decimal # = field(default=1, kw_only=True)
+    _increment: Decimal
 
     @abstractmethod
     def __init__(
-        self, min_value: Number, max_value: Number, *, increment: Number = 1, user_groups: Union[Iterable[Any], str] = frozenset(), 
-        parent_option_ids: Union[Iterable[str], str] = frozenset(), **kwargs
+        self, min_value: Number, max_value: Number, *, increment: Number = 1, user_groups: Iterable[Any] | str = frozenset(), 
+        parent_option_ids: Iterable[str] | str = frozenset(), **kwargs
     ) -> None:
         super().__init__(user_groups=user_groups, parent_option_ids=parent_option_ids)
         try:
@@ -247,41 +260,31 @@ class _NumericParameterOption(ParameterOption):
             raise ConfigurationError(f'The difference between selected value "{value}" and lower value ' +
                 f'"{self._min_value}" must be a multiple of increment "{self._increment}".')
         return value
-    
-    def _to_json_dict(self):
-        return {
-            "min_value": float(self._min_value),
-            "max_value": float(self._max_value),
-            "increment": float(self._increment)
-        }
 
 
 @dataclass
 class NumberParameterOption(_NumericParameterOption):
     """
     Parameter option for default numbers if it varies based on selection of another parameter
-
-    Attributes:
-        min_value: Minimum selectable value
-        max_value: Maximum selectable value
-        increment: Increment of selectable values, and must fit evenly between min_value and max_value
-        default_value: Default value for this option, and must be selectable based on min_value, max_value, and increment
-        user_groups: The user groups this parameter option would show for if "user_attribute" is specified in the Parameter factory
-        parent_option_ids: Set of parent option ids this parameter option would show for if "parent" is specified in the Parameter factory
     """
-    _default_value: Decimal # = field(default=None, kw_only=True)
+    _default_value: Decimal
 
     def __init__(
-        self, min_value: Number, max_value: Number, *, increment: Number = 1, default_value: Optional[Number] = None,
-        user_groups: Union[Iterable[Any], str] = frozenset(), parent_option_ids: Union[Iterable[str], str] = frozenset(), **kwargs
+        self, min_value: Number, max_value: Number, *, increment: Number = 1, default_value: Number | None = None,
+        user_groups: Iterable[Any] | str = frozenset(), parent_option_ids: Iterable[str] | str = frozenset(), **kwargs
     ) -> None:
         """
         Constructor for NumberParameterOption
         
         * Note that the "Number" type denotes an int, a Decimal (from decimal module), or a string that can be parsed to Decimal
 
-        Parameters:
-            ...see Attributes of NumberParameterOption
+        Arguments:
+            min_value: Minimum selectable value
+            max_value: Maximum selectable value
+            increment: Increment of selectable values, and must fit evenly between min_value and max_value
+            default_value: Default value for this option, and must be selectable based on min_value, max_value, and increment
+            user_groups: The user groups this parameter option would show for if "user_attribute" is specified in the Parameter factory
+            parent_option_ids: Set of parent option ids this parameter option would show for if "parent" is specified in the Parameter factory
         """
         super().__init__(min_value, max_value, increment=increment, user_groups=user_groups, parent_option_ids=parent_option_ids)
         self._default_value = self._validate_value(default_value) if default_value is not None else self._min_value
@@ -291,32 +294,29 @@ class NumberParameterOption(_NumericParameterOption):
 class NumberRangeParameterOption(_NumericParameterOption):
     """
     Parameter option for default numeric ranges if it varies based on selection of another parameter
-    
-    Attributes:
-        min_value: Minimum selectable value
-        max_value: Maximum selectable value
-        increment: Increment of selectable values, and must fit evenly between min_value and max_value
-        default_lower_value: Default lower value for this option, and must be selectable based on min_value, max_value, and increment
-        default_upper_value: Default upper value for this option, and must be selectable based on min_value, max_value, and increment. 
-                Must also be greater than default_lower_value
-        user_groups: The user groups this parameter option would show for if "user_attribute" is specified in the Parameter factory
-        parent_option_ids: Set of parent option ids this parameter option would show for if "parent" is specified in the Parameter factory
     """
-    _default_lower_value: Decimal # = field(default=None, kw_only=True)
-    _default_upper_value: Decimal # = field(default=None, kw_only=True)
+    _default_lower_value: Decimal
+    _default_upper_value: Decimal
 
     def __init__(
-        self, min_value: Number, max_value: Number, *, increment: Number = 1, default_lower_value: Optional[Number] = None, 
-        default_upper_value: Optional[Number] = None, user_groups: Union[Iterable[Any], str] = frozenset(), 
-        parent_option_ids: Union[Iterable[str], str] = frozenset(), **kwargs
+        self, min_value: Number, max_value: Number, *, increment: Number = 1, default_lower_value: Number | None = None, 
+        default_upper_value: Number | None = None, user_groups: Iterable[Any] | str = frozenset(), 
+        parent_option_ids: Iterable[str] | str = frozenset(), **kwargs
     ) -> None:
         """
         Constructor for NumberRangeParameterOption
         
         * Note that the "Number" type denotes an int, a Decimal (from decimal module), or a string that can be parsed to Decimal
 
-        Parameters:
-            ...see Attributes of NumberRangeParameterOption
+        Arguments:
+            min_value: Minimum selectable value
+            max_value: Maximum selectable value
+            increment: Increment of selectable values, and must fit evenly between min_value and max_value
+            default_lower_value: Default lower value for this option, and must be selectable based on min_value, max_value, and increment
+            default_upper_value: Default upper value for this option, and must be selectable based on min_value, max_value, and increment. 
+                    Must also be greater than default_lower_value
+            user_groups: The user groups this parameter option would show for if "user_attribute" is specified in the Parameter factory
+            parent_option_ids: Set of parent option ids this parameter option would show for if "parent" is specified in the Parameter factory
         """
         super().__init__(min_value, max_value, increment=increment, user_groups=user_groups, parent_option_ids=parent_option_ids)
         self._default_lower_value = self._validate_value(default_lower_value) if default_lower_value is not None else self._min_value
@@ -328,23 +328,20 @@ class NumberRangeParameterOption(_NumericParameterOption):
 class TextParameterOption(ParameterOption):
     """
     Parameter option for default text values if it varies based on selection of another parameter
-
-    Attributes:
-        default_text: Default text for this option
-        user_groups: The user groups this parameter option would show for if "user_attribute" is specified in the Parameter factory
-        parent_option_ids: Set of parent option ids this parameter option would show for if "parent" is specified in the Parameter factory
     """
-    _default_text: str # = field(default=None, kw_only=True)
+    _default_text: str
 
     def __init__(
-        self, *, default_text: str = "", user_groups: Union[Iterable[Any], str] = frozenset(), 
-        parent_option_ids: Union[Iterable[str], str] = frozenset(), **kwargs
+        self, *, default_text: str = "", user_groups: Iterable[Any] | str = frozenset(), 
+        parent_option_ids: Iterable[str] | str = frozenset(), **kwargs
     ) -> None:
         """
         Constructor for TextParameterOption
 
-        Parameters:
-            ...see Attributes of TextParameterOption
+        Arguments:
+            default_text: Default text for this option
+            user_groups: The user groups this parameter option would show for if "user_attribute" is specified in the Parameter factory
+            parent_option_ids: Set of parent option ids this parameter option would show for if "parent" is specified in the Parameter factory
         """
         super().__init__(user_groups=user_groups, parent_option_ids=parent_option_ids)
         self._default_text = default_text