squirrels 0.4.1__py3-none-any.whl → 0.5.0rc0__py3-none-any.whl

squirrels/package_data/base_project/parameters.yml

@@ -4,36 +4,47 @@ 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: role                                ## optional, default is null
       all_options:
         - id: g0
           label: Transaction
-          columns: ["masked_id", "date", "description"]   ## custom field
-          aliases: ["id", "date", "description"]          ## custom field
+          columns: ["date", "category", "subcategory", "description"]   ## custom field
           is_default: false                               ## optional, default, exists for SingleSelect or MultiSelect options only
-          user_groups: []                                 ## optional, default, exists for all parameter options
+          user_groups: ["manager"]                        ## optional, default is empty list
           parent_option_ids: []                           ## optional, default, exists for all parameter options
         - id: g1
-          label: Date
+          label: Day
           columns: [date]
+          aliases: [day]                                  ## custom field
+          user_groups: ["manager", "employee"]
+        - id: g4
+          label: Month
+          columns: [month]
+          user_groups: ["manager", "employee"]
         - id: g2
           label: Category
           columns: [category]
+          user_groups: ["manager", "employee"]
         - id: g3
           label: Subcategory
           columns: [category, subcategory]
-      user_attribute: null                                ## optional, default, exists for all parameter types
+          user_groups: ["manager", "employee"]
       parent_name: null                                   ## optional, 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: g0
   
   - type: DateParameter
     factory: CreateFromSource
@@ -42,7 +53,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 +65,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 +76,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
@@ -107,7 +122,7 @@ parameters:
       description: Number to filter on transactions with an amount greater than this value
       all_options:
         - min_value: 0
-          max_value: 500
+          max_value: 300
           increment: 10                                   ## optional, default is 1, exists for Number and NumberRange options
           default_value: null                             ## optional, default, exists for Number options only
   
@@ -118,12 +133,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, default, required for SingleSelect and MultiSelect, optional for others
   
   - type: NumberRangeParameter
     factory: CreateWithOptions
@@ -133,8 +148,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 NumRange options only
+          default_upper_value: 300                        ## optional, default is null (or max_value), exists for NumRange options only
 
 

squirrels/package_data/base_project/pyconfigs/connections.py

@@ -1,19 +1,14 @@
-from sqlalchemy import create_engine, Engine
-from squirrels import ConnectionsArgs
+from typing import Any
+from squirrels import ConnectionsArgs, ConnectionProperties, ConnectionType
 
 
-def main(connections: dict[str, Engine], sqrl: ConnectionsArgs) -> None:
+def main(connections: dict[str, ConnectionProperties | Any], sqrl: ConnectionsArgs) -> None:
     """
     Define sqlalchemy engines by adding them to the "connections" dictionary
     """
-    
     ## SQLAlchemy URL for a connection engine
-    conn_str = 'sqlite:///./assets/expenses.db' 
+    conn_str: str = sqrl.env_vars["SQLITE_URI"].format(project_path=sqrl.project_path)
 
-    ## Can also leverage environment variables and credentials in the env.yml file for connection details
-    # conn_str_raw: str = sqrl.env_vars["sqlite_conn_str"]
-    # username, password = sqrl.get_credential('my_key')
-    # conn_str = conn_str_raw.format(username=username, password=password) 
-    
     ## Assigning names to connection engines
-    connections["default"] = create_engine(conn_str)
+    connections["default"] = ConnectionProperties(label="SQLite Expenses Database", type=ConnectionType.SQLALCHEMY, uri=conn_str)
+    

squirrels/package_data/base_project/pyconfigs/context.py

@@ -16,84 +16,71 @@ 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()
+        ctx["group_by_cols_list"] = columns
+        ctx["rename_dict"] = {old: new for old, new in zip(columns, aliases)}
+    
+    if sqrl.param_exists("limit"):
+        limit_param = sqrl.prms["limit"]
+        assert isinstance(limit_param, p.NumberParameter)
 
-        sqrl.set_placeholder("desc_pattern", desc_pattern)
+        ctx["limit_clause"] = f"LIMIT {limit_param.get_selected_value()}"
+    else:
+        ctx["limit_clause"] = ""
 
     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_quoted()
     
     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_quoted()
 
     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_quoted()
+        ctx["end_date_from_range"] = date_range_param.get_selected_end_date_quoted()
     
     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_quoted_joined()
     
     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_quoted_joined()
     
     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

@@ -17,30 +17,28 @@ def main(sqrl: ParametersArgs) -> None:
     """
 
     ## Example of creating SingleSelectParameter and specifying each option by code
+    user_attribute = "role"
     group_by_options = [
-        po.SelectParameterOption("g0", "Transaction", columns=["masked_id", "date", "description"], aliases=["id", "date", "description"]),
-        po.SelectParameterOption("g1", "Date", columns=["date"]),
-        po.SelectParameterOption("g4", "Month", columns=["month"]),
-        po.SelectParameterOption("g2", "Category", columns=["category"]),
-        po.SelectParameterOption("g3", "Subcategory", columns=["category", "subcategory"]),
+        po.SelectParameterOption("g0", "Transaction", columns=["date", "category", "subcategory", "description"], user_groups=["manager"]),
+        po.SelectParameterOption("g1", "Day", columns=["date"], aliases=["day"], user_groups=["manager", "employee"]),
+        po.SelectParameterOption("g4", "Month", columns=["month"], user_groups=["manager", "employee"]),
+        po.SelectParameterOption("g2", "Category", columns=["category"], user_groups=["manager", "employee"]),
+        po.SelectParameterOption("g3", "Subcategory", columns=["category", "subcategory"], user_groups=["manager", "employee"]),
     ]
     p.SingleSelectParameter.CreateWithOptions(
-        "group_by", "Group By", group_by_options, description="Dimension(s) to aggregate by"
+        "group_by", "Group By", group_by_options, description="Dimension(s) to aggregate by", user_attribute=user_attribute
     )
 
-    ## Example of creating a TextParameter
-    parent_name = "group_by"
-    description_text_options = [
-        po.TextParameterOption(parent_option_ids="g0")
-    ]
-    p.TextParameter.CreateWithOptions(
-        "description_filter", "Description Contains", description_text_options, parent_name=parent_name,
-        description="Substring of description to filter transactions by"
+    ## Example of creating NumberParameter with options
+    parent = "group_by"
+    limit_options = [po.NumberParameterOption(0, 1000, increment=10, default_value=1000, parent_option_ids="g0")]
+    p.NumberParameter.CreateWithOptions(
+        "limit", "Max Number of Rows", limit_options, parent_name=parent, description="Maximum number of rows to return"
     )
 
-    ## Example of creating DateParameter from lookup query/table
+    ## Example of creating DateParameter
     start_date_source = ds.DateDataSource(
-        "SELECT min(date) AS min_date, max(date) AS max_date FROM transactions",
+        "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"
     )
     p.DateParameter.CreateFromSource(
@@ -48,14 +46,14 @@ def main(sqrl: ParametersArgs) -> None:
     )
 
     ## Example of creating DateParameter from list of DateParameterOption's
-    end_date_option = [po.DateParameterOption("2023-12-31", min_date="2023-01-01", max_date="2023-12-31")]
+    end_date_option = [po.DateParameterOption("2024-12-31", min_date="2024-01-01", max_date="2024-12-31")]
     p.DateParameter.CreateWithOptions(
         "end_date", "End Date", end_date_option, description="End date to filter transactions by"
     )
 
     ## Example of creating DateRangeParameter
     p.DateRangeParameter.CreateSimple(
-        "date_range", "Date Range", "2023-01-01", "2023-12-31", min_date="2023-01-01", max_date="2023-12-31",
+        "date_range", "Date Range", "2024-01-01", "2024-12-31", min_date="2024-01-01", max_date="2024-12-31",
         description="Date range to filter transactions by"
     )
 
@@ -77,12 +75,12 @@ def main(sqrl: ParametersArgs) -> None:
 
     ## Example of creating NumberParameter
     p.NumberParameter.CreateSimple(
-        "min_filter", "Amounts Greater Than", min_value=0, max_value=500, increment=10,
+        "min_filter", "Amounts Greater Than", min_value=0, max_value=300, increment=10,
         description="Number to filter on transactions with an amount greater than this value"
     )
     
     ## 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'"
+    query = "SELECT 0 as min_value, 300 as max_value, 10 as increment"
     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="Number to filter on transactions with an amount less than this value"
@@ -90,6 +88,6 @@ def main(sqrl: ParametersArgs) -> None:
 
     ## Example of creating NumberRangeParameter
     p.NumberRangeParameter.CreateSimple(
-        "between_filter", "Amounts Between", 0, 500, default_lower_value=10, default_upper_value=400,
+        "between_filter", "Amounts Between", 0, 300, default_lower_value=0, default_upper_value=300,
         description="Number range to filter on transactions with an amount within this range"
     )

squirrels/package_data/base_project/pyconfigs/user.py

@@ -0,0 +1,23 @@
+from typing import Literal
+from squirrels import BaseUser
+
+
+class User(BaseUser):
+    """
+    Extend the BaseUser class with custom attributes. The attributes defined here will be added as columns to the users table. 
+    - Only the following types are supported: [str, int, float, bool, typing.Literal]
+    - For str, int, and float types, add "| None" after the type to make it nullable. 
+    - Always set a default value for the column (use None if default is null).
+    
+    Example:
+        organization: str | None = None
+    """
+    role: Literal["manager", "employee"] = "employee"
+
+    @classmethod
+    def dropped_columns(cls) -> list[str]:
+        """
+        The fields defined above cannot be modified once added to the database. 
+        However, you can choose to drop columns by adding them to this list.
+        """
+        return []

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

@@ -1,15 +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"
+"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

@@ -1,6 +1,7 @@
 project_variables:
   name: sample
-  label: Sample Project
+  label: Sample Project - Expenses
+  description: This is a sample squirrels project for analyzing expense transactions
   major_version: 1
 
 
@@ -20,28 +21,26 @@ packages: []
 
 
 datasets:
-  - name: dataset_example                 ## model name uses same name unless "model" field is specified
-    label: Dataset Example
-    model: federate_example               ## optional - if not specified, then the "name" field is used
+  - 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: 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 - defaults to empty object
   
-  - name: protected_dataset_example       ## requires auth.py file to work
-    label: Dataset Example 2
-    model: federate_example
-    scope: protected
+  - 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: protected                      ## using an auth.py file is suggested for protected or private datasets
     parameters:
       - group_by
-      - description_filter
+      - limit
       - date_range
       - category
       - subcategory
@@ -49,46 +48,24 @@ datasets:
     default_test_set: auth_test1          ## optional - if not specified, uses setting 'selection_test_sets.default_name_used'
 
 
-{{ dashboards -}}
-
-
 selection_test_sets:
   - name: no_auth_test1
     datasets:                             ## optional section - if not provided, then test set is applicable for any dataset
-      - dataset_example
+      - dbview_dataset_example
     parameters:                           ## optional section - if not provided, then assumes no parameters. For unspecified parameters, default value is used
-      start_date: 2023-07-01              ## this parameter only exists for dataset 'dataset_example'
+      start_date: 2024-07-01              ## this parameter only exists for dataset 'dataset_example'
   
   - name: auth_test1
     datasets:
-      - protected_dataset_example
+      - federate_dataset_example
     user_attributes:                      ## optional section - required if using test set on non-public datasets
-      role: customer
+      role: employee
     parameters:
-      date_range: [2023-02-01,2023-12-01] ## this parameter only exists for dataset 'protected_dataset_example'
+      date_range: [2024-02-01,2024-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: {}
-
-## Default values for settings:
-#   auth.token.expire_minutes: 30
-#   parameters.cache.size: 1024
-#   parameters.cache.ttl_minutes: 60
-#   datasets.cache.size: 128
-#   datasets.cache.ttl_minutes: 60
-#   dashboards.cache.size: 128
-#   dashboards.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]