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

squirrels/package_data/base_project/connections.yml

@@ -2,6 +2,6 @@
 connections:
   - name: default
     credential: null
-    url: {{ sqlite_conn_str }} ## using Jinja to substitute environment variable from environcfg.yml
+    url: {{ env_vars.sqlite_conn_str }}   ## using Jinja to substitute environment variable from environcfg.yml
 
 

squirrels/package_data/base_project/docker/Dockerfile

@@ -3,7 +3,7 @@ FROM python:3.11-slim
 WORKDIR /app
 
 # Needed if any python dependencies are installed from git, or for 
-# "squirrels deps" if there are modules in "squirrels.yml"
+# "squirrels deps" command if there are packages defined in "squirrels.yml"
 RUN apt-get update && apt-get install -y git
 
 COPY requirements-lock.txt .

squirrels/package_data/base_project/environcfg.yml

@@ -1,18 +1,18 @@
 ## Note: You can copy this file to the .squirrels folder in your home directory to make 
 ##   the configurations global for all squirrels projects on the current machine
 
-## Fake users for local development testing
+## Fake users for local development testing. Must have an 'auth.py' file with a 'User' model to use custom attributes like 'role'
 users:
-  johndoe:
+  alice:
     is_internal: True
     password: I<3Squirrels
-    full_name: John Doe
-    organization: org1
-  mattdoe:
+    full_name: Alice Doe
+    role: employee
+  bob:
     is_internal: False
     password: abcd5678
-    full_name: Matt Doe
-    organization: org2
+    full_name: Bob Doe
+    role: customer
 
 ## Custom environment variables / secrets
 env_vars:

squirrels/package_data/base_project/models/dbviews/database_view1.py

@@ -1,35 +1,46 @@
 from textwrap import dedent
-import pandas as pd, squirrels as sr
+from squirrels import ModelArgs
+import pandas as pd
 
 
-def main(sqrl: sr.ModelArgs) -> pd.DataFrame:
+def main(sqrl: ModelArgs) -> pd.DataFrame:
     """
     Create a database view model in Python by sending an external query to a database or API, and return a 
     pandas DataFrame of the result in this function. Since the result is loaded into server memory, be mindful of 
     the size of the results coming from the external query.
     """
 
-    """ If working with sqlalchemy ORMs, use 'sqrl.connections' to get a sqlalchemy engine """
+    ## If working with sqlalchemy ORMs, use 'sqrl.connections' to get a sqlalchemy engine
     # from typing import Union
     # engine1 = sqrl.connections[sqrl.connection_name] ## using the pre-assigned key
     # engine2 = sqrl.connections["my_connection_name"] ## or use any defined key
     
-    """ Example with building and running a sql query """
-    category_clause = f'AND category IN ({sqrl.ctx["categories"]})\n' if sqrl.ctx["has_categories"] else ''
-    subcategory_clause = f'AND subcategory IN ({sqrl.ctx["subcategories"]})\n' if sqrl.ctx["has_subcategories"] else ''
+    ## Example with building and running a sql query
+    masked_id = "id" if getattr(sqrl.user, "role", "") == "manager" else "'***'"
+    desc_cond = "description LIKE :desc_pattern" if sqrl.is_placeholder("desc_pattern") else "true"
+    category_cond = f"category IN ({sqrl.ctx['categories']})" if sqrl.ctx["has_categories"] else "true"
+    subcategory_cond = f"subcategory IN ({sqrl.ctx['subcategories']})" if sqrl.ctx["has_subcategories"] else "true"
     query = dedent(f"""
-        SELECT {sqrl.ctx["group_by_cols"]}
+        WITH
+        transactions_with_masked_id AS (
+            SELECT *, 
+                {masked_id} as masked_id
+            FROM transactions
+        )
+        SELECT {sqrl.ctx["select_dim_cols"]}
             , sum(-amount) as total_amount
-        FROM transactions
-        WHERE 1=1
-            {category_clause}{subcategory_clause}AND date >= {sqrl.ctx["start_date"]}
-            AND date <= {sqrl.ctx["end_date"]}
-            AND -amount >= {sqrl.ctx["min_amount"]}
-            AND -amount <= {sqrl.ctx["max_amount"]}
+        FROM transactions_with_masked_id
+        WHERE date >= :start_date
+            AND date <= :end_date
+            AND -amount >= :min_amount
+            AND -amount <= :max_amount
+            AND {desc_cond}
+            AND {category_cond}
+            AND {subcategory_cond}
         GROUP BY {sqrl.ctx["group_by_cols"]}
     """).strip()
 
     return sqrl.run_external_sql(query) 
 
-    """ A 'connection_name' argument is available to use a different connection key """
+    ## A 'connection_name' argument is available to use a different connection key
     # return sqrl.run_external_sql(query, connection_name="different_key")

squirrels/package_data/base_project/models/dbviews/database_view1.sql

@@ -1,15 +1,22 @@
-SELECT {{ ctx["group_by_cols"] }}
-    , sum(-amount) as total_amount
-FROM transactions
-WHERE 1=1
-{%- if ctx["has_categories"] %}
-    AND category IN ({{ ctx["categories"] }})
-{%- endif %}
-{%- if ctx["has_subcategories"] %}
-    AND subcategory IN ({{ ctx["subcategories"] }})
+WITH
+transactions_with_masked_id AS (
+    SELECT *,
+{%- if user.role == "manager" %}
+        id as masked_id
+{%- else %}
+        '***' as masked_id
 {%- endif %}
-    AND date >= {{ ctx["start_date"] }}
-    AND date <= {{ ctx["end_date"] }}
-    AND -amount >= {{ ctx["min_amount"] }}
-    AND -amount <= {{ ctx["max_amount"] }}
-GROUP BY {{ ctx["group_by_cols"] }}
+    FROM transactions
+)
+SELECT {{ ctx.select_dim_cols }}
+    , sum(-amount) as total_amount
+FROM transactions_with_masked_id
+WHERE true
+    {% if is_placeholder("start_date") -%} AND date >= :start_date {%- endif %}
+    {% if is_placeholder("end_date") -%} AND date <= :end_date {%- endif %}
+    {% if is_placeholder("min_amount") -%} AND -amount >= :min_amount {%- endif %}
+    {% if is_placeholder("max_amount") -%} AND -amount <= :max_amount {%- endif %}
+    {% if is_placeholder("desc_pattern") -%} AND description LIKE :desc_pattern {%- endif %}
+    {% if ctx.has_categories -%} AND category IN ({{ ctx.categories }}) {%- endif %}
+    {% if ctx.has_subcategories -%} AND subcategory IN ({{ ctx.subcategories }}) {%- endif %}
+GROUP BY {{ ctx.group_by_cols }}

squirrels/package_data/base_project/models/federates/dataset_example.py

@@ -1,8 +1,9 @@
 from typing import Iterable
-import pandas as pd, squirrels as sr
+from squirrels import ModelDepsArgs, ModelArgs
+import pandas as pd
 
 
-def dependencies(sqrl: sr.ModelDepsArgs) -> Iterable[str]:
+def dependencies(sqrl: ModelDepsArgs) -> Iterable[str]:
     """
     Define list of dependent models here. This will determine the dependencies first, at compile-time, 
     before running the model.
@@ -10,11 +11,11 @@ def dependencies(sqrl: sr.ModelDepsArgs) -> Iterable[str]:
     return ["database_view1"]
 
 
-def main(sqrl: sr.ModelArgs) -> pd.DataFrame:
+def main(sqrl: ModelArgs) -> pd.DataFrame:
     """
     Create federated models by joining/processing dependent database views and/or other federated models to
     form and return the result as a new pandas DataFrame.
     """
     df = sqrl.ref("database_view1")
-    group_by_cols: str = sqrl.ctx["group_by_cols_list"]
-    return df.sort_values(group_by_cols, ascending=False)
+    order_by_cols: str = sqrl.ctx["order_by_cols_list"]
+    return df.sort_values(order_by_cols, ascending=False)

squirrels/package_data/base_project/models/federates/dataset_example.sql

@@ -1,3 +1,3 @@
 SELECT *
 FROM {{ ref("database_view1") }}
-ORDER BY {{ ctx["order_by_cols"] }}
+ORDER BY {{ ctx.order_by_cols }}

squirrels/package_data/base_project/parameters.yml

@@ -1,16 +1,18 @@
 parameters:
   - type: SingleSelectParameter
-    factory: Create               ## one of 'Create', 'CreateSimple', or 'CreateFromSource'
-    arguments:                    ## arguments to specify depend on values for 'type' and 'factory'
+    factory: Create                                       ## one of 'Create', 'CreateSimple', or 'CreateFromSource'
+    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
       all_options:
         - id: g0
           label: Transaction
-          columns: [id, date]     ## 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
+          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: [date]
@@ -20,90 +22,117 @@ parameters:
         - id: g3
           label: Subcategory
           columns: [category, subcategory]
-      is_hidden: false            ## optional, default, exists for all parameter types
-      user_attribute: null        ## optional, default, exists for all parameter types
-      parent_name: null           ## optional, default, exists for all parameter types
+      user_attribute: null                                ## optional, default, exists for all parameter types
+      parent_name: null                                   ## optional, default, exists for all parameter types
+  
+  - type: TextParameter
+    factory: Create
+    arguments:
+      name: description_filter
+      label: Description Contains
+      description: Filter by transactions with this description
+      parent_name: group_by
+      all_options:
+        - parent_option_ids: g0
+  
   - type: DateParameter
     factory: Create
     arguments:
       name: start_date
       label: Start Date
+      description: Filter by transactions after this date
       all_options:
         - default_date: 2023-01-01
-          date_format: '%Y-%m-%d' ## optional, default, format comes from python datetime, exists for Date and DateRange parameter options
+          date_format: '%Y-%m-%d'                         ## optional, default, format comes from python datetime, exists for Date and DateRange parameter options
+  
   - type: DateParameter
     factory: Create
     arguments:
       name: end_date
       label: End Date
+      description: Filter by transactions before this date
       all_options:
         - default_date: 2023-12-31
+  
   - type: DateRangeParameter
     factory: Create
     arguments:
       name: date_range
       label: Date Range
+      description: Filter by transactions within this date range
       all_options:
         - default_start_date: 2023-01-01
           default_end_date: 2023-12-31
+  
   - type: MultiSelectParameter
     factory: CreateFromSource
     arguments:
       name: category
       label: Category Filter
+      description: The expense categories to filter by
       data_source:
-        table_or_query: categories
+        table_or_query: seed_categories
         id_col: category_id
         options_col: category
-        order_by_col: null        ## optional, default, exists for SingleSelect and MultiSelect
-        is_default_col: null      ## optional, default, exists for SingleSelect and MultiSelect
-        custom_cols: {}           ## optional, default, exists for SingleSelect and MultiSelect
-        include_all: true         ## optional, default, exists for MultiSelect only
-        order_matters: false      ## optional, default, exists for MultiSelect only
-        user_group_col: null      ## optional, default, exists for all parameters
-        connection_name: default  ## optional, default, exists for all parameters
+        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
+  
   - type: MultiSelectParameter
     factory: CreateFromSource
     arguments:
       name: subcategory
       label: Subcategory Filter
+      description: The expense subcategories to filter by (available options based on selected 'Category Filter')
+      parent_name: category
       data_source:
-        table_or_query: subcategories
+        table_or_query: seed_subcategories
         id_col: subcategory_id
         options_col: subcategory
-        parent_id_col: category_id  ## optional, default is null, exists for all parameter types
-      parent_name: category
+        from_seeds: true
+        parent_id_col: category_id                        ## optional, default is null, exists for all parameter types
+  
   - type: NumberParameter
     factory: Create
     arguments:
       name: min_filter
       label: Amounts Greater Than
+      description: Filter by transactions greater than this amount
       all_options:
         - min_value: 0
           max_value: 500
-          increment: 1            ## optional, default, exists for Number and NumRange options
-          default_value: null     ## optional, default, exists for Number options only
+          increment: 10                                   ## optional, default is 1, exists for Number and NumberRange options
+          default_value: null                             ## optional, default, exists for Number options only
+  
   - type: NumberParameter
     factory: CreateFromSource
     arguments:
       name: max_filter
       label: Amounts Less Than
+      description: Filter by transactions less than this amount
       data_source:
         table_or_query: "SELECT 0 as min_value, max(-amount) as max_value, 10 as increment FROM transactions WHERE category <> 'Income'"
         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
+        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
+  
   - type: NumberRangeParameter
     factory: Create
     arguments:
       name: between_filter
       label: Amounts Between
+      description: Filter by transaction amounts 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
+          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
 
 

squirrels/package_data/base_project/pyconfigs/auth.py

@@ -1,13 +1,14 @@
-from typing import Union, Any
+from typing import Union
 from squirrels import User as UserBase, AuthArgs, WrongPassword
 
 
 class User(UserBase):
-    def set_attributes(self, user_dict: dict[str, Any]) -> None:
+    def set_attributes(self, **kwargs) -> None:
         """
-        Use this method to add custom attributes in the User model that don't exist in UserBase (username, is_internal, etc.)
+        Use this method to add custom attributes in the User model that don't exist in UserBase 
+        (i.e., anything that's not 'username' or 'is_internal')
         """
-        self.organization = user_dict["organization"]
+        self.role = kwargs["role"]
 
 
 def get_user_if_valid(sqrl: AuthArgs) -> Union[User, WrongPassword, None]:
@@ -23,22 +24,22 @@ def get_user_if_valid(sqrl: AuthArgs) -> Union[User, WrongPassword, None]:
         "johndoe": {
             "username": "johndoe",
             "is_admin": True,
-            "organization": "org1",
+            "role": "manager",
             "hashed_password": str(hash("I<3Squirrels"))
         },
         "mattdoe": {
             "username": "mattdoe",
             "is_admin": False,
-            "organization": "org2",
+            "role": "customer",
             "hashed_password": str(hash("abcd5678"))
         }
     }
 
-    user_dict = mock_users_db.get(sqrl.username)
-    if user_dict is None:
+    user_obj = mock_users_db.get(sqrl.username)
+    if user_obj is None:
         return None
     
-    if str(hash(sqrl.password)) == user_dict["hashed_password"]:
-        return User.Create(sqrl.username, user_dict, is_internal=user_dict["is_admin"])
+    if str(hash(sqrl.password)) == user_obj["hashed_password"]:
+        return User.Create(sqrl.username, is_internal=user_obj["is_admin"], role=user_obj["role"])
     else:
         return WrongPassword()

squirrels/package_data/base_project/pyconfigs/connections.py

@@ -1,21 +1,19 @@
 from sqlalchemy import create_engine, Engine
-import squirrels as sr
+from squirrels import ConnectionsArgs
 
 
-def main(connections: dict[str, Engine], sqrl: sr.ConnectionsArgs) -> None:
+def main(connections: dict[str, Engine], sqrl: ConnectionsArgs) -> None:
     """
     Define sqlalchemy engines by adding them to the "connections" dictionary
     """
     
-    """ Example of getting the username and password """
-    # username, password = sqrl.get_credential('my_key')
-    
-    """ SQLAlchemy URL for a connection engine """
+    ## SQLAlchemy URL for a connection engine
     conn_str = 'sqlite:///database/expenses.db' 
 
-    """ Can also leverage environment variables in the environcfg.yml file for connection details """
+    ## Can also leverage environment variables and credentials in the environcfg.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 """
+    ## Assigning names to connection engines
     connections["default"] = create_engine(conn_str)

squirrels/package_data/base_project/pyconfigs/context.py

@@ -1,8 +1,8 @@
 from typing import Any
-import squirrels as sr
+from squirrels import ContextArgs, parameters as p
 
 
-def main(ctx: dict[str, Any], sqrl: sr.ContextArgs) -> None:
+def main(ctx: dict[str, Any], sqrl: 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.
@@ -10,46 +10,62 @@ def main(ctx: dict[str, Any], sqrl: sr.ContextArgs) -> None:
     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.
     """
+    if sqrl.param_exists("group_by"):
+        group_by_param: p.SingleSelectParameter = sqrl.prms["group_by"]
+        columns = group_by_param.get_selected("columns")
+        aliases = group_by_param.get_selected("aliases", default_field="columns")
 
-    if "group_by" in sqrl.prms:
-        group_by_param: sr.SingleSelectParameter = sqrl.prms["group_by"]
-        ctx["group_by_cols_list"] = group_by_param.get_selected("columns")
-        ctx["group_by_cols"] = ",".join(ctx["group_by_cols_list"])
-        ctx["order_by_cols"] = ",".join((x+" DESC") for x in ctx["group_by_cols_list"])
+        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 "start_date" in sqrl.prms:
-        start_date_param: sr.DateParameter = sqrl.prms["start_date"]
-        ctx["start_date"] = start_date_param.get_selected_date_quoted()
+    if sqrl.param_exists("description_filter"):
+        descript_param: p.TextParameter = sqrl.prms["description_filter"]
+        desc_pattern = descript_param.get_entered_text().apply_percent_wrap()
+        sqrl.set_placeholder("desc_pattern", desc_pattern)
+
+    if sqrl.param_exists("start_date"):
+        start_date_param: p.DateParameter = sqrl.prms["start_date"]
+        start_date = start_date_param.get_selected_date()
+        sqrl.set_placeholder("start_date", start_date)
     
-    if "end_date" in sqrl.prms:
-        end_date_param: sr.DateParameter = sqrl.prms["end_date"]
-        ctx["end_date"] = end_date_param.get_selected_date_quoted()
-
-    if "date_range" in sqrl.prms:
-        date_range_param: sr.DateRangeParameter = sqrl.prms["date_range"]
-        ctx["start_date"] = date_range_param.get_selected_start_date_quoted()
-        ctx["end_date"] = date_range_param.get_selected_end_date_quoted()
+    if sqrl.param_exists("end_date"):
+        end_date_param: p.DateParameter = sqrl.prms["end_date"]
+        end_date = end_date_param.get_selected_date()
+        sqrl.set_placeholder("end_date", end_date)
+
+    if sqrl.param_exists("date_range"):
+        date_range_param: p.DateRangeParameter = sqrl.prms["date_range"]
+        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)
     
-    if "category" in sqrl.prms:
-        category_param: sr.MultiSelectParameter = sqrl.prms["category"]
+    if sqrl.param_exists("category"):
+        category_param: p.MultiSelectParameter = sqrl.prms["category"]
         ctx["has_categories"] = category_param.has_non_empty_selection()
         ctx["categories"] = category_param.get_selected_labels_quoted_joined()
     
-    if "subcategory" in sqrl.prms:
-        subcategory_param: sr.MultiSelectParameter = sqrl.prms["subcategory"]
+    if sqrl.param_exists("subcategory"):
+        subcategory_param: p.MultiSelectParameter = sqrl.prms["subcategory"]
         ctx["has_subcategories"] = subcategory_param.has_non_empty_selection()
         ctx["subcategories"] = subcategory_param.get_selected_labels_quoted_joined()
     
-    if "min_filter" in sqrl.prms:
-        min_amount_filter: sr.NumberParameter = sqrl.prms["min_filter"]
-        ctx["min_amount"] = min_amount_filter.get_selected_value()
+    if sqrl.param_exists("min_filter"):
+        min_amount_filter: p.NumberParameter = sqrl.prms["min_filter"]
+        min_amount = min_amount_filter.get_selected_value()
+        sqrl.set_placeholder("min_amount", min_amount)
     
-    if "max_filter" in sqrl.prms:
-        max_amount_filter: sr.NumberParameter = sqrl.prms["max_filter"]
-        ctx["max_amount"] = max_amount_filter.get_selected_value()
-
-    if "between_filter" in sqrl.prms:
-        between_filter: sr.NumberRangeParameter = sqrl.prms["between_filter"]
-        ctx["min_amount"] = between_filter.get_selected_lower_value()
-        ctx["max_amount"] = between_filter.get_selected_upper_value()
+    if sqrl.param_exists("max_filter"):
+        max_amount_filter: p.NumberParameter = sqrl.prms["max_filter"]
+        max_amount = max_amount_filter.get_selected_value()
+        sqrl.set_placeholder("max_amount", max_amount)
+
+    if sqrl.param_exists("between_filter"):
+        between_filter: p.NumberRangeParameter = sqrl.prms["between_filter"]
+        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)