squirrels 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

squirrels/package_data/base_project/pyconfigs/parameters.py

@@ -1,55 +1,87 @@
-import squirrels as sr
+from squirrels import ParametersArgs, parameters as p, parameter_options as po, data_sources as ds
 
 
-def main(sqrl: sr.ParametersArgs) -> None:
+def main(sqrl: ParametersArgs) -> None:
     """
     Create all widget parameters in this file. If two or more datasets use a different set of parameters, define them all
     here, and specify the subset of parameters used for each dataset in the "squirrels.yml" file.
 
     Parameters are created by a factory method associated to some parameters class. For example (note the "Create"):
-    > sr.SingleSelectParameter.Create(...)
+    > p.SingleSelectParameter.Create(...)
 
     The parameter classes available are:
-    - SingleSelectParameter, MultiSelectParameter, DateParameter, DateRangeParameter, NumberParameter, NumberRangeParameter
+    - SingleSelectParameter, MultiSelectParameter, DateParameter, DateRangeParameter, NumberParameter, NumberRangeParameter, TextParameter
     
     The factory methods available are:
     - Create, CreateSimple, CreateFromSource
     """
 
-    """ Example of creating SingleSelectParameter and specifying each option by code """
+    ## Example of creating SingleSelectParameter and specifying each option by code
     group_by_options = [
-        sr.SelectParameterOption("g0", "Transaction", columns=["id", "date"]),
-        sr.SelectParameterOption("g1", "Date", columns=["date"]),
-        sr.SelectParameterOption("g2", "Category", columns=["category"]),
-        sr.SelectParameterOption("g3", "Subcategory", columns=["category", "subcategory"]),
+        po.SelectParameterOption("g0", "Transaction", columns=["masked_id", "date", "description"], aliases=["id", "date", "description"]),
+        po.SelectParameterOption("g1", "Date", columns=["date"]),
+        po.SelectParameterOption("g2", "Category", columns=["category"]),
+        po.SelectParameterOption("g3", "Subcategory", columns=["category", "subcategory"]),
     ]
-    sr.SingleSelectParameter.Create("group_by", "Group By", group_by_options)
+    p.SingleSelectParameter.Create(
+        "group_by", "Group By", group_by_options, description="Dimension to aggregate by"
+    )
 
-    """ Example of creating DateParameter """
-    sr.DateParameter.CreateSimple("start_date", "Start Date", "2023-01-01")
+    ## Example of creating a TextParameter
+    parent_name = "group_by"
+    text_options = [po.TextParameterOption(parent_option_ids="g0")]
+    p.TextParameter.Create(
+        "description_filter", "Description Contains", text_options, parent_name=parent_name,
+        description="Filter by transactions with this description"
+    )
 
-    """ Example of creating DateParameter from list of DateParameterOption's """
-    end_date_option = [sr.DateParameterOption("2023-12-31")]
-    sr.DateParameter.Create("end_date", "End Date", end_date_option)
+    ## Example of creating DateParameter
+    p.DateParameter.CreateSimple(
+        "start_date", "Start Date", "2023-01-01", description="Filter by transactions after this date"
+    )
 
-    """ Example of creating DateRangeParameter """
-    sr.DateRangeParameter.CreateSimple("date_range", "Date Range", "2023-01-01", "2023-12-31")
+    ## Example of creating DateParameter from list of DateParameterOption's
+    end_date_option = [po.DateParameterOption("2023-12-31")]
+    p.DateParameter.Create(
+        "end_date", "End Date", end_date_option, description="Filter by transactions before this date"
+    )
 
-    """ Example of creating MultiSelectParameter from lookup query/table """
-    category_ds = sr.MultiSelectDataSource("categories", "category_id", "category")
-    sr.MultiSelectParameter.CreateFromSource("category", "Category Filter", category_ds)
+    ## Example of creating DateRangeParameter
+    p.DateRangeParameter.CreateSimple(
+        "date_range", "Date Range", "2023-01-01", "2023-12-31", description="Filter by transactions within this date range"
+    )
 
-    """ Example of creating MultiSelectParameter with parent from lookup query/table """
-    subcategory_ds = sr.MultiSelectDataSource("subcategories", "subcategory_id", "subcategory", parent_id_col="category_id")
-    sr.MultiSelectParameter.CreateFromSource("subcategory", "Subcategory Filter", subcategory_ds, parent_name="category")
+    ## Example of creating MultiSelectParameter from lookup query/table
+    category_ds = ds.SelectDataSource("seed_categories", "category_id", "category", from_seeds=True)
+    p.MultiSelectParameter.CreateFromSource(
+        "category", "Category Filter", category_ds, description="The expense categories to filter by"
+    )
 
-    """ Example of creating NumberParameter """
-    sr.NumberParameter.CreateSimple("min_filter", "Amounts Greater Than", min_value=0, max_value=500, increment=10)
+    ## Example of creating MultiSelectParameter with parent from lookup query/table
+    parent_name = "category"
+    subcategory_ds = ds.SelectDataSource(
+        "seed_subcategories", "subcategory_id", "subcategory", from_seeds=True, parent_id_col="category_id"
+    )
+    p.MultiSelectParameter.CreateFromSource(
+        "subcategory", "Subcategory Filter", subcategory_ds, parent_name=parent_name,
+        description="The expense subcategories to filter by (available options based on selected 'Category Filter')"
+    )
+
+    ## Example of creating NumberParameter
+    p.NumberParameter.CreateSimple(
+        "min_filter", "Amounts Greater Than", min_value=0, max_value=500, increment=10,
+        description="Filter by transactions greater than this amount"
+    )
     
-    """ Example of creating NumberParameter from lookup query/table """
+    ## Example of creating NumberParameter from lookup query/table
     query = "SELECT 0 as min_value, max(-amount) as max_value, 10 as increment FROM transactions WHERE category <> 'Income'"
-    max_amount_ds = sr.NumberDataSource(query, "min_value", "max_value", increment_col="increment", default_value_col="max_value")
-    sr.NumberParameter.CreateFromSource("max_filter", "Amounts Less Than", max_amount_ds)
+    max_amount_ds = ds.NumberDataSource(query, "min_value", "max_value", increment_col="increment", default_value_col="max_value")
+    p.NumberParameter.CreateFromSource(
+        "max_filter", "Amounts Less Than", max_amount_ds, description="Filter by transactions less than this amount"
+    )
 
-    """ Example of creating NumberRangeParameter """
-    sr.NumberRangeParameter.CreateSimple("between_filter", "Amounts Between", 0, 500, default_lower_value=10, default_upper_value=400)
+    ## Example of creating NumberRangeParameter
+    p.NumberRangeParameter.CreateSimple(
+        "between_filter", "Amounts Between", 0, 500, default_lower_value=10, default_upper_value=400,
+        description="Filter by transaction amounts within this range"
+    )

squirrels/package_data/base_project/seeds/seed_categories.csv

@@ -0,0 +1,6 @@
+"category_id","category"
+"0","Food"
+"1","Bills"
+"2","Shopping"
+"3","Transportation"
+"4","Entertainment"

squirrels/package_data/base_project/seeds/seed_subcategories.csv

@@ -0,0 +1,15 @@
+"subcategory","category_id","subcategory_id"
+"Dining Out","0","0"
+"Groceries","0","1"
+"Utilities","1","2"
+"Electronics","2","3"
+"Ride Sharing","3","4"
+"Mobile","1","5"
+"Home Decor","2","6"
+"Internet","1","7"
+"Theater","4","8"
+"Movies","4","9"
+"Sports","2","10"
+"Public Transit","3","11"
+"Clothing","2","12"
+"Concerts","4","13"

squirrels/package_data/base_project/squirrels.yml.j2

@@ -18,42 +18,57 @@ packages: []
 {{ parameters -}}
 
 
-selection_test_sets:
-  - name: sample_test_set
-    user_attributes:     ## optional unless there are user attributes used by parameters or models
-      is_internal: True
-      organization: org1
-    parameters:          ## optional - for unspecified parameters, default value is used
-      group_by: g3
-      start_date: 2023-02-01
-      end_date: 2023-12-01
-      category: ["1"]
-
-
 datasets:
-  - name: dataset_example  ## model with same name is used unless "model" field is specified for dataset
+  - name: dataset_example                 ## model name uses same name unless "model" field is specified
     label: Dataset Example
-    scope: public          ## optional - one of 'public' (default), 'protected', or 'private'
-    parameters:            ## optional - if not specified, then all parameters are used
+    scope: public                         ## optional - one of 'public' (default), 'protected', or 'private'
+    parameters:                           ## optional - if not specified, then all parameters are used
       - group_by
+      - description_filter
       - start_date
       - end_date
       - category
       - subcategory
       - min_filter
       - max_filter
-    traits: {} ## optional
+    traits: {}                            ## optional - defaults to empty object
   
-  - name: private_dataset_example
+  - name: protected_dataset_example       ## requires auth.py file to work
     label: Dataset Example 2
     model: dataset_example
-    scope: private
+    scope: protected
     parameters:
       - group_by
+      - description_filter
       - date_range
       - category
       - subcategory
       - between_filter
+    default_test_set: auth_test1          ## optional - if not specified, uses setting 'selection_test_sets.default_name_used'
+
+
+selection_test_sets:
+  - name: no_auth_test1
+    datasets:                             ## optional section - if not provided, then test set is applicable for any dataset
+      - dataset_example
+    parameters:                           ## optional section - for unspecified parameters, default value is used
+      start_date: 2023-07-01              ## this parameter only exists for dataset 'dataset_example'
+  
+  - name: auth_test1
+    datasets:
+      - protected_dataset_example
+    user_attributes:                      ## optional section - required if using test set on non-public datasets
+      role: customer
+    parameters:
+      date_range: [2023-02-01,2023-12-01] ## this parameter only exists for dataset 'protected_dataset_example'
+    
+  - name: auth_test2
+    user_attributes:
+      username: alice                     ## optional - defaults to empty string
+      is_internal: True                   ## optional - defaults to False
+      role: manager
+    parameters:
+      group_by: g3                        ## this parameter exists for all datasets. "g3" is the id for option "subcategory"
 
 
 settings: {}
@@ -61,10 +76,12 @@ settings: {}
 ## Default values for settings:
 #   auth.token.expire_minutes: 30
 #   parameters.cache.size: 1024
-#   parameters.cache.ttl_minutes: 0
+#   parameters.cache.ttl_minutes: 60
 #   results.cache.size: 128
-#   results.cache.ttl_minutes: 0
+#   results.cache.ttl_minutes: 60
 #   selection_test_sets.default_name_used: default
 #   connections.default_name_used: default
 #   defaults.federates.materialized: table
 #   in_memory_database: sqlite
+#   seeds.infer_schema: True
+#   seeds.na_values: [NA]

squirrels/parameter_options.py

@@ -50,10 +50,6 @@ class ParameterOption(metaclass=ABCMeta):
         
         return True
     
-    @abstractmethod
-    def _to_json_dict(self):
-        return {}
-
 
 @dataclass
 class SelectParameterOption(ParameterOption):
@@ -143,9 +139,6 @@ class _DateTypeParameterOption(ParameterOption):
         except ValueError as e:
             raise ConfigurationError(f'Invalid format for date "{date_str}".') from e
     
-    def _to_json_dict(self):
-        return {}
-
 
 @dataclass
 class DateParameterOption(_DateTypeParameterOption):
@@ -256,9 +249,9 @@ class _NumericParameterOption(ParameterOption):
     
     def _to_json_dict(self):
         return {
-            "min_value": str(self._min_value),
-            "max_value": str(self._max_value),
-            "increment": str(self._increment)
+            "min_value": float(self._min_value),
+            "max_value": float(self._max_value),
+            "increment": float(self._increment)
         }
 
 
@@ -328,3 +321,30 @@ class NumberRangeParameterOption(_NumericParameterOption):
         self._default_lower_value = self._validate_value(default_lower_value) if default_lower_value is not None else self._min_value
         self._default_upper_value = self._validate_value(default_upper_value) if default_upper_value is not None else self._max_value
         self._validate_lower_upper_values("default_lower_value", self._default_lower_value, "default_upper_value", self._default_upper_value)
+
+
+@dataclass
+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)
+
+    def __init__(
+        self, *, default_text: str = "", user_groups: Union[Iterable[Any], str] = frozenset(), 
+        parent_option_ids: Union[Iterable[str], str] = frozenset(), **kwargs
+    ) -> None:
+        """
+        Constructor for TextParameterOption
+
+        Parameters:
+            ...see Attributes of TextParameterOption
+        """
+        super().__init__(user_groups=user_groups, parent_option_ids=parent_option_ids)
+        self._default_text = default_text
+