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

squirrels/{package_data → _package_data}/base_project/parameters.yml

@@ -4,36 +4,48 @@ parameters:
     arguments:                                            ## arguments to specify depend on values for 'type' and 'factory'
       name: group_by
       label: Group By
-      description: Dimension to aggregate by              ## optional, default is empty string
+      description: Dimension(s) to aggregate by           ## optional, default is empty string
+      user_attribute: access_level                        ## optional, default is null
       all_options:
-        - id: g0
+        - id: trans
           label: Transaction
-          columns: ["masked_id", "date", "description"]   ## custom field
-          aliases: ["id", "date", "description"]          ## custom field
-          is_default: false                               ## optional, default, exists for SingleSelect or MultiSelect options only
-          user_groups: []                                 ## optional, default, exists for all parameter options
-          parent_option_ids: []                           ## optional, default, exists for all parameter options
-        - id: g1
-          label: Date
+          columns: ["id", "date", "category", "subcategory", "description"]   ## custom field
+          aliases: ["_id", "date", "category", "subcategory", "description"]  ## custom field (any alias starting with "_" will not be selected - see context.py for implementation)
+          is_default: false                               ## optional, shown is default - exists for SingleSelect or MultiSelect options only
+          user_groups: ["admin"]                          ## optional, default is empty list
+          parent_option_ids: []                           ## optional, shown is default - exists for all parameter options
+        - id: day
+          label: Day
           columns: [date]
-        - id: g2
+          aliases: [day]
+          user_groups: ["admin", "member"]
+        - id: month
+          label: Month
+          columns: [month]
+          user_groups: ["admin", "member", "guest"]
+        - id: cat
           label: Category
           columns: [category]
-        - id: g3
+          user_groups: ["admin", "member", "guest"]
+        - id: subcat
           label: Subcategory
           columns: [category, subcategory]
-      user_attribute: null                                ## optional, default, exists for all parameter types
-      parent_name: null                                   ## optional, default, exists for all parameter types
+          user_groups: ["admin", "member", "guest"]
+      parent_name: null                                   ## optional, shown is default - exists for all parameter types
   
-  - type: TextParameter
+  - type: NumberParameter
     factory: CreateWithOptions
     arguments:
-      name: description_filter
-      label: Description Contains
-      description: Substring of description to filter transactions by
+      name: limit
+      label: Max Number of Rows
+      description: Maximum number of rows to return
       parent_name: group_by
       all_options:
-        - parent_option_ids: g0
+        - min_value: 0
+          max_value: 1000
+          increment: 10
+          default_value: 1000
+          parent_option_ids: trans
   
   - type: DateParameter
     factory: CreateFromSource
@@ -42,7 +54,7 @@ parameters:
       label: Start Date
       description: Start date to filter transactions by
       data_source:
-        table_or_query: SELECT min(date) AS min_date, max(date) AS max_date FROM transactions
+        table_or_query: SELECT min(date) AS min_date, max(date) AS max_date FROM expenses
         default_date_col: min_date
         min_date_col: min_date
         max_date_col: max_date
@@ -54,7 +66,9 @@ parameters:
       label: End Date
       description: End date to filter transactions by
       all_options:
-        - default_date: 2023-12-31
+        - default_date: 2024-12-31
+          min_date: 2024-01-01
+          max_date: 2024-12-31
   
   - type: DateRangeParameter
     factory: CreateWithOptions
@@ -63,8 +77,10 @@ parameters:
       label: Date Range
       description: Date range to filter transactions by
       all_options:
-        - default_start_date: 2023-01-01
-          default_end_date: 2023-12-31
+        - default_start_date: 2024-01-01
+          default_end_date: 2024-12-31
+          min_date: 2024-01-01
+          max_date: 2024-12-31
   
   - type: MultiSelectParameter
     factory: CreateFromSource
@@ -76,14 +92,14 @@ parameters:
         table_or_query: seed_categories
         id_col: category_id
         options_col: category
-        from_seeds: true                                  ## optional, default is false, exists for data_source of any parameters
-        order_by_col: null                                ## optional, default, exists for data_source of SingleSelect and MultiSelect
-        is_default_col: null                              ## optional, default, exists for data_source of SingleSelect and MultiSelect
-        custom_cols: {}                                   ## optional, default, exists for data_source of SingleSelect and MultiSelect
-        include_all: true                                 ## optional, default, exists for data_source of MultiSelect only
-        order_matters: false                              ## optional, default, exists for data_source of MultiSelect only
-        user_group_col: null                              ## optional, default, exists for data_source of any parameters
-        connection_name: default                          ## optional, default, exists for data_source of any parameters
+        source: seeds                                     ## optional, default is "connection" - must be one of "connection", "seeds", or "vdl" - exists for data_source of any parameters
+        order_by_col: null                                ## optional, shown is default - exists for data_source of SingleSelect and MultiSelect
+        is_default_col: null                              ## optional, shown is default - exists for data_source of SingleSelect and MultiSelect
+        custom_cols: {}                                   ## optional, shown is default - exists for data_source of SingleSelect and MultiSelect
+        include_all: true                                 ## optional, shown is default - exists for data_source of MultiSelect only
+        order_matters: false                              ## optional, shown is default - exists for data_source of MultiSelect only
+        user_group_col: null                              ## optional, shown is default - exists for data_source of any parameters
+        connection_name: default                          ## optional, shown is default - exists for data_source of any parameters
   
   - type: MultiSelectParameter
     factory: CreateFromSource
@@ -96,8 +112,8 @@ parameters:
         table_or_query: seed_subcategories
         id_col: subcategory_id
         options_col: subcategory
-        from_seeds: true
-        parent_id_col: category_id                        ## optional, default is null, exists for all parameter types
+        source: seeds
+        parent_id_col: category_id                        ## optional, default is null - exists for all parameter types
   
   - type: NumberParameter
     factory: CreateWithOptions
@@ -107,9 +123,9 @@ parameters:
       description: Number to filter on transactions with an amount greater than this value
       all_options:
         - min_value: 0
-          max_value: 500
-          increment: 10                                   ## optional, default is 1, exists for Number and NumberRange options
-          default_value: null                             ## optional, default, exists for Number options only
+          max_value: 300
+          increment: 10                                   ## optional, default is 1 - exists for Number and NumberRange options
+          default_value: null                             ## optional, shown is default - exists for Number options only
   
   - type: NumberParameter
     factory: CreateFromSource
@@ -118,12 +134,12 @@ parameters:
       label: Amounts Less Than
       description: Number to filter on transactions with an amount less than this value
       data_source:
-        table_or_query: "SELECT 0 as min_value, max(-amount) as max_value, 10 as increment FROM transactions WHERE category <> 'Income'"
+        table_or_query: "SELECT 0 as min_value, 300 as max_value, 10 as increment"
         min_value_col: min_value
         max_value_col: max_value
         increment_col: increment                          ## optional, default is null
         default_value_col: max_value                      ## optional, default is null
-        id_col: null                                      ## optional, default, required for SingleSelect and MultiSelect, optional for all others
+        id_col: null                                      ## optional, shown is default - required for SingleSelect and MultiSelect, optional for others
   
   - type: NumberRangeParameter
     factory: CreateWithOptions
@@ -133,8 +149,8 @@ parameters:
       description: Number range to filter on transactions with an amount within this range
       all_options:
         - min_value: 0
-          max_value: 500
-          default_lower_value: 10                         ## optional, default is null (or min_value), exists for NumRange options only
-          default_upper_value: 400                        ## optional, default is null (or max_value), exists for NumRange options only
+          max_value: 300
+          default_lower_value: 0                          ## optional, default is null (or min_value) - exists for NumberRange options only
+          default_upper_value: 300                        ## optional, default is null (or max_value) - exists for NumberRange options only
 
 

squirrels/_package_data/base_project/pyconfigs/connections.py

@@ -0,0 +1,14 @@
+from typing import Any
+from squirrels import arguments as args, connections as cn
+
+
+def main(connections: dict[str, cn.ConnectionProperties | Any], sqrl: args.ConnectionsArgs) -> None:
+    """
+    Define sqlalchemy engines by adding them to the "connections" dictionary
+    """
+    ## SQLAlchemy URL for a connection engine
+    conn_str: str = sqrl.env_vars["SQLITE_URI"].format(project_path=sqrl.project_path)
+
+    ## Assigning names to connection engines
+    connections["default"] = cn.ConnectionProperties(label="SQLite Expenses Database", type=cn.ConnectionTypeEnum.SQLALCHEMY, uri=conn_str)
+    

squirrels/{package_data → _package_data}/base_project/pyconfigs/context.py

@@ -1,14 +1,14 @@
 from typing import Any
-from squirrels import ContextArgs, parameters as p
+from squirrels import arguments as args, parameters as p
 
 
-def main(ctx: dict[str, Any], sqrl: ContextArgs) -> None:
+def main(ctx: dict[str, Any], sqrl: args.ContextArgs) -> None:
     """
     Define context variables AFTER parameter selections are made by adding entries to the dictionary "ctx". 
     These context variables can then be used in the models.
 
     Note that the code here is used by all datasets, regardless of the parameters they use. You can use 
-    sqrl.prms and/or sqrl.traits to determine the conditions to execute certain blocks of code.
+    sqrl.param_exists to determine the conditions to execute certain blocks of code.
     """
     if sqrl.param_exists("group_by"):
         group_by_param = sqrl.prms["group_by"]
@@ -16,84 +16,65 @@ def main(ctx: dict[str, Any], sqrl: ContextArgs) -> None:
         
         columns = group_by_param.get_selected("columns")
         aliases = group_by_param.get_selected("aliases", default_field="columns")
-        assert isinstance(columns, list) and isinstance(aliases, list)
+        assert isinstance(columns, list) and isinstance(aliases, list) and len(columns) == len(aliases)
 
-        ctx["select_dim_cols"] = ", ".join(x+" as "+y for x, y in zip(columns, aliases))
-        ctx["group_by_cols"] = ", ".join(columns)
-        ctx["order_by_cols"] = ", ".join((x+" DESC") for x in aliases)
-        ctx["order_by_cols_list"] = aliases
-
-    if sqrl.param_exists("description_filter"):
-        descript_param = sqrl.prms["description_filter"]
-        assert isinstance(descript_param, p.TextParameter)
-
-        desc_pattern = descript_param.get_entered_text().apply_percent_wrap()
-
-        sqrl.set_placeholder("desc_pattern", desc_pattern)
+        column_to_alias_mapping = {x: y for x, y in zip(columns, aliases) if not y.startswith("_")}
 
+        ctx["group_by_cols"] = columns
+        ctx["select_dim_cols"] = list(x+" as "+y for x, y in column_to_alias_mapping.items())
+        ctx["order_by_cols"] = list(column_to_alias_mapping.values())
+        ctx["order_by_cols_desc"] = list(x+" DESC" for x in ctx["order_by_cols"])
+        ctx["column_to_alias_mapping"] = column_to_alias_mapping
+    
     if sqrl.param_exists("start_date"):
         start_date_param = sqrl.prms["start_date"]
         assert isinstance(start_date_param, p.DateParameter)
 
-        start_date = start_date_param.get_selected_date()
-        
-        sqrl.set_placeholder("start_date", start_date)
+        ctx["start_date"] = start_date_param.get_selected_date()
     
     if sqrl.param_exists("end_date"):
         end_date_param = sqrl.prms["end_date"]
         assert isinstance(end_date_param, p.DateParameter)
 
-        end_date = end_date_param.get_selected_date()
-
-        sqrl.set_placeholder("end_date", end_date)
+        ctx["end_date"] = end_date_param.get_selected_date()
 
     if sqrl.param_exists("date_range"):
         date_range_param = sqrl.prms["date_range"]
         assert isinstance(date_range_param, p.DateRangeParameter)
 
-        start_date = date_range_param.get_selected_start_date()
-        end_date = date_range_param.get_selected_end_date()
-
-        sqrl.set_placeholder("start_date", start_date)
-        sqrl.set_placeholder("end_date", end_date)
+        ctx["start_date_from_range"] = date_range_param.get_selected_start_date()
+        ctx["end_date_from_range"] = date_range_param.get_selected_end_date()
     
     if sqrl.param_exists("category"):
         category_param = sqrl.prms["category"]
         assert isinstance(category_param, p.MultiSelectParameter)
 
         ctx["has_categories"] = category_param.has_non_empty_selection()
-        ctx["categories"] = category_param.get_selected_labels_quoted_joined()
+        ctx["categories"] = category_param.get_selected_ids_as_list()
     
     if sqrl.param_exists("subcategory"):
         subcategory_param = sqrl.prms["subcategory"]
         assert isinstance(subcategory_param, p.MultiSelectParameter)
 
         ctx["has_subcategories"] = subcategory_param.has_non_empty_selection()
-        ctx["subcategories"] = subcategory_param.get_selected_labels_quoted_joined()
+        ctx["subcategories"] = subcategory_param.get_selected_ids_as_list()
     
     if sqrl.param_exists("min_filter"):
         min_amount_filter = sqrl.prms["min_filter"]
         assert isinstance(min_amount_filter, p.NumberParameter)
 
-        min_amount = min_amount_filter.get_selected_value()
-
-        sqrl.set_placeholder("min_amount", min_amount)
+        ctx["min_amount"] = min_amount_filter.get_selected_value()
     
     if sqrl.param_exists("max_filter"):
         max_amount_filter = sqrl.prms["max_filter"]
         assert isinstance(max_amount_filter, p.NumberParameter)
 
-        max_amount = max_amount_filter.get_selected_value()
-
-        sqrl.set_placeholder("max_amount", max_amount)
+        ctx["max_amount"] = max_amount_filter.get_selected_value()
 
     if sqrl.param_exists("between_filter"):
         between_filter = sqrl.prms["between_filter"]
         assert isinstance(between_filter, p.NumberRangeParameter)
 
-        min_amount = between_filter.get_selected_lower_value()
-        max_amount = between_filter.get_selected_upper_value()
-
-        sqrl.set_placeholder("min_amount", min_amount)
-        sqrl.set_placeholder("max_amount", max_amount)
+        ctx["min_amount_from_range"] = between_filter.get_selected_lower_value()
+        ctx["max_amount_from_range"] = between_filter.get_selected_upper_value()
     

squirrels/_package_data/base_project/pyconfigs/parameters.py

@@ -0,0 +1,141 @@
+from squirrels import parameters as p, parameter_options as po, data_sources as ds
+
+
+## Example of creating SingleSelectParameter and specifying each option by code
+@p.SingleSelectParameter.create_with_options(
+    name="group_by", label="Group By", 
+    description="Dimension(s) to aggregate by", 
+    user_attribute="access_level"
+)
+def group_by_options():
+    return [
+        po.SelectParameterOption(
+            id="trans", label="Transaction",  
+            columns=["id","date","category","subcategory","description"],
+            aliases=["_id","date","category","subcategory","description"], # in context.py, any alias starting with "_" will not be selected
+            user_groups=["admin"]
+        ),
+        po.SelectParameterOption(
+            id="day", label="Day", 
+            columns=["date"], 
+            aliases=["day"], 
+            user_groups=["admin","member"]
+        ),
+        po.SelectParameterOption(
+            id="month", label="Month", 
+            columns=["month"], 
+            user_groups=["admin","member","guest"]
+        ),
+        po.SelectParameterOption(
+            id="cat", label="Category", 
+            columns=["category"], 
+            user_groups=["admin","member","guest"]
+        ),
+        po.SelectParameterOption(
+            id="subcat", label="Subcategory", 
+            columns=["category","subcategory"], 
+            user_groups=["admin","member","guest"]
+        ),
+    ]
+
+
+## Example of creating DateParameter
+@p.DateParameter.create_from_source(
+    name="start_date", label="Start Date", 
+    description="Start date to filter transactions by"
+)
+def start_date_source():
+    return ds.DateDataSource(
+        table_or_query="SELECT min(date) AS min_date, max(date) AS max_date FROM expenses",
+        default_date_col="min_date", 
+        min_date_col="min_date", max_date_col="max_date",
+    )
+
+
+## Example of creating DateParameter from list of DateParameterOption's
+@p.DateParameter.create_with_options(
+    name="end_date", label="End Date", 
+    description="End date to filter transactions by"
+)
+def end_date_options():
+    return [
+        po.DateParameterOption(
+            default_date="2024-12-31", min_date="2024-01-01", max_date="2024-12-31"
+        )
+    ]
+
+
+## Example of creating DateRangeParameter
+@p.DateRangeParameter.create_simple(
+    name="date_range", label="Date Range", 
+    default_start_date="2024-01-01", default_end_date="2024-12-31", 
+    min_date="2024-01-01", max_date="2024-12-31",
+    description="Date range to filter transactions by"
+)
+def date_range_options():
+    pass
+
+
+## Example of creating MultiSelectParameter from lookup query/table
+@p.MultiSelectParameter.create_from_source(
+    name="category", label="Category Filter", 
+    description="The expense categories to filter transactions by"
+)
+def category_source():
+    return ds.SelectDataSource(
+        table_or_query="seed_categories", 
+        id_col="category_id", 
+        options_col="category", 
+        source=ds.SourceEnum.SEEDS
+    )
+
+
+## Example of creating MultiSelectParameter with parent from lookup query/table
+@p.MultiSelectParameter.create_from_source(
+    name="subcategory", label="Subcategory Filter",
+    description="The expense subcategories to filter transactions by (available options are based on selected value(s) of 'Category Filter')", 
+    parent_name="category"
+)
+def subcategory_source():
+    return ds.SelectDataSource(
+        table_or_query="seed_subcategories", 
+        id_col="subcategory_id", 
+        options_col="subcategory", 
+        source=ds.SourceEnum.SEEDS, 
+        parent_id_col="category_id"
+    )
+
+
+## Example of creating NumberParameter
+@p.NumberParameter.create_simple(
+    name="min_filter", label="Amounts Greater Than", 
+    min_value=0, max_value=300, increment=10,
+    description="Number to filter on transactions with an amount greater than this value"
+)
+def min_filter_options():
+    pass
+
+
+## Example of creating NumberParameter from lookup query/table
+@p.NumberParameter.create_from_source(
+    name="max_filter", label="Amounts Less Than",
+    description="Number to filter on transactions with an amount less than this value"
+)
+def max_filter_source():
+    return ds.NumberDataSource(
+        table_or_query="SELECT 0 as min_value, 300 as max_value, 10 as increment",
+        min_value_col="min_value", max_value_col="max_value", 
+        increment_col="increment", 
+        default_value_col="max_value"
+    )
+
+
+## Example of creating NumberRangeParameter
+@p.NumberRangeParameter.create_simple(
+    name="between_filter", label="Amounts Between", 
+    min_value=0, max_value=300, 
+    default_lower_value=0, default_upper_value=300,
+    description="Number range to filter on transactions with an amount within this range"
+)
+def between_filter_options():
+    pass

squirrels/_package_data/base_project/pyconfigs/user.py

@@ -0,0 +1,44 @@
+from typing import Literal
+from squirrels import auth, arguments as args
+
+
+class CustomUserFields(auth.CustomUserFields):
+    """
+    Extend the CustomUserFields class to add custom user attributes. 
+    - Only the following types are supported: [str, int, float, bool, typing.Literal]
+    - Add "| None" after the type to make it nullable. 
+    - Always set a default value for the field (use None if default is null).
+    
+    Example:
+        organization: str | None = None
+    """
+    role: Literal["manager", "employee"] = "employee"
+
+
+# @auth.provider(name="google", label="Google", icon="https://www.google.com/favicon.ico")
+def google_auth_provider(sqrl: args.AuthProviderArgs) -> auth.ProviderConfigs:
+    """
+    Provider configs for authenticating a user using Google credentials.
+
+    See the following page for setting up the CLIENT_ID and CLIENT_SECRET for Google specifically: 
+    https://support.google.com/googleapi/answer/6158849?hl=en
+    """
+    def get_sqrl_user(claims: dict) -> auth.RegisteredUser:
+        custom_fields = CustomUserFields(role="employee")
+        return auth.RegisteredUser(
+            username=claims["email"],
+            access_level="member",
+            custom_fields=custom_fields
+        )
+
+    # TODO: Add GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET to the .env file
+    # Then, uncomment the @auth.provider decorator above and set the client_id and client_secret below
+    provider_configs = auth.ProviderConfigs(
+        client_id="", # sqrl.env_vars["GOOGLE_CLIENT_ID"],
+        client_secret="", # sqrl.env_vars["GOOGLE_CLIENT_SECRET"],
+        server_url="https://accounts.google.com",
+        client_kwargs={"scope": "openid email profile"},
+        get_user=get_sqrl_user
+    )
+
+    return provider_configs

squirrels/_package_data/base_project/seeds/seed_categories.yml

@@ -0,0 +1,15 @@
+description: |
+  Lookup table for the category IDs and names of transactions.
+
+cast_column_types: true  # optional, default is false - setting SQRL_SEEDS__INFER_SCHEMA is ignored for this seed if this is set to true
+
+columns:
+  - name: category_id
+    type: string
+    description: The category ID
+    category: dimension
+  
+  - name: category
+    type: string
+    description: The human-readable category name
+    category: dimension

squirrels/_package_data/base_project/seeds/seed_subcategories.csv

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

squirrels/_package_data/base_project/seeds/seed_subcategories.yml

@@ -0,0 +1,21 @@
+description: |
+  Lookup table for the subcategory IDs and names of transactions.
+
+cast_column_types: true  # optional, default is false - setting SQRL_SEEDS__INFER_SCHEMA is ignored for this seed if this is set to true
+
+columns:
+  - name: subcategory_id
+    type: string
+    description: The subcategory ID
+    category: dimension
+  
+  - name: subcategory
+    type: string
+    description: The human-readable subcategory name
+    category: dimension
+  
+  - name: category_id
+    type: string
+    description: The category ID that the subcategory belongs to
+    category: dimension
+  

squirrels/_package_data/base_project/squirrels.yml.j2

@@ -0,0 +1,61 @@
+project_variables:
+  name: sample_expenses
+  label: "Sample Expenses"
+  description: This is a sample squirrels project for analyzing expense transactions
+  major_version: 1
+
+
+packages: []
+
+## Example for packages section:
+# packages:
+#   - git: https://.../myrepo.git
+#     revision: v0.1.0
+#     directory: custom_name ## optional
+
+
+{{ connections -}}
+
+
+{{ parameters -}}
+
+
+datasets:
+  - name: dbview_dataset_example          ## model name uses same name unless "model" field is specified
+    label: Example Dataset from DBView Model
+    description: Aggregated expense transactions by month using dbview_example model
+    model: dbview_example 
+    scope: private                        ## optional - one of 'public' (default), 'protected', or 'private'
+    parameters:                           ## optional - if not specified, then all parameters are used
+      - start_date
+      - end_date
+      - min_filter
+      - max_filter
+  
+  - name: federate_dataset_example
+    label: Example Dataset from Federate Model
+    description: Aggregated expense transactions by custom dimension using federate_example model
+    model: federate_example 
+    scope: public                         ## using an auth.py file is suggested for protected or private datasets
+    parameters:
+      - group_by
+      - date_range
+      - category
+      - subcategory
+      - between_filter
+
+
+selection_test_sets:
+  - name: set_start_date
+    parameters:                           ## optional section - if not provided, then default value is used for all parameters
+      start_date: 2024-07-01              ## this parameter is only used by model "dbview_example"
+  
+  - name: set_date_range
+    parameters:
+      date_range: [2024-02-01,2024-11-30] ## this parameter is only used by model "federate_example"
+    
+  - name: use_admin_privileged_group_by
+    user:
+      access_level: admin
+    parameters:
+      group_by: trans