squirrels 0.5.0b3__py3-none-any.whl → 0.6.0.post0__py3-none-any.whl

squirrels/_package_data/base_project/pyconfigs/context.py

@@ -1,35 +1,47 @@
-from typing import Any
-from squirrels import arguments as args, parameters as p
+from typing import cast, Any
+from squirrels.arguments import ContextArgs
+from squirrels import parameters as p
 
+from pyconfigs.user import CustomUserFields
 
-def main(ctx: dict[str, Any], sqrl: args.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.
 
     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.
     """
+    custom_fields = cast(CustomUserFields, sqrl.user.custom_fields)
+
     if sqrl.param_exists("group_by"):
         group_by_param = sqrl.prms["group_by"]
         assert isinstance(group_by_param, p.SingleSelectParameter)
         
+        selected_id = group_by_param.get_selected_id()
         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) and len(columns) == len(aliases)
 
-        ctx["group_by_cols"] = columns
-        ctx["rename_dict"] = {x: y for x, y in zip(columns, aliases) if not y.startswith("_")}
-        ctx["select_dim_cols"] = list(x+" as "+y for x, y in ctx["rename_dict"].items())
-        ctx["order_by_cols"] = list(ctx["rename_dict"].values())
-        ctx["order_by_cols_desc"] = list(x+" DESC" for x in ctx["order_by_cols"])
-    
-    if sqrl.param_exists("limit"):
-        limit_param = sqrl.prms["limit"]
-        assert isinstance(limit_param, p.NumberParameter)
+        column_to_alias_mapping = {x: y for x, y in zip(columns, aliases) if not y.startswith("_")}
+        order_by_cols = list(column_to_alias_mapping.values())
 
-        ctx["limit"] = int(limit_param.get_selected_value())
+        ctx["column_to_alias_mapping"] = column_to_alias_mapping
+        ctx["group_by_cols"] = order_by_cols if selected_id != "trans" else None
 
+        # Only used if federate_example is a Python model
+        mask_column = lambda x: x if custom_fields.role == "manager" else "***MASKED***"
+        ctx["order_by_cols"] = order_by_cols
+        ctx["mask_column_function"] = mask_column
+        
+        # Only used if federate_example is a SQL model
+        mask_column = lambda x: x if custom_fields.role == "manager" else "'***MASKED***'"
+        x_as_y = lambda x, y: (mask_column(x) if x in ["description"] else x)+" as "+y
+        ctx["select_dim_cols"] = list(x_as_y(x, y) for x, y in column_to_alias_mapping.items())
+        ctx["aggregator"] = "SUM" if selected_id != "trans" else ""
+        ctx["order_by_cols_desc"] = list(y+" DESC" for y in order_by_cols)
+        
     if sqrl.param_exists("start_date"):
         start_date_param = sqrl.prms["start_date"]
         assert isinstance(start_date_param, p.DateParameter)

squirrels/_package_data/base_project/pyconfigs/parameters.py

@@ -1,98 +1,141 @@
-from squirrels import arguments as args, data_sources as ds, parameter_options as po, parameters as p
+from squirrels import parameters as p, parameter_options as po, data_sources as ds
 
 
-def main(sqrl: args.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 the parameter class. For example, "CreateWithOptions" is the factory method used here:
-    > p.SingleSelectParameter.CreateWithOptions(...)
-
-    The parameter classes available are:
-    - SingleSelectParameter, MultiSelectParameter, DateParameter, DateRangeParameter, NumberParameter, NumberRangeParameter, TextParameter
-    
-    The factory methods available are:
-    - CreateSimple, CreateWithOptions, CreateFromSource
-    """
-
-    ## Example of creating SingleSelectParameter and specifying each option by code
-    user_attribute = "role"
-    group_by_options = [
+## 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(
-            "trans", "Transaction",  
-            columns=["id", "date", "category", "subcategory", "description"],
-            aliases=["_id", "date", "category", "subcategory", "description"], # any alias starting with "_" will not be selected - see context.py for implementation
-            user_groups=["manager"]
+            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"]
         ),
-        po.SelectParameterOption("day", "Day",            columns=["date"], aliases=["day"],   user_groups=["manager", "employee"]),
-        po.SelectParameterOption("month", "Month",        columns=["month"],                   user_groups=["manager", "employee"]),
-        po.SelectParameterOption("cat", "Category",       columns=["category"],                user_groups=["manager", "employee"]),
-        po.SelectParameterOption("subcat", "Subcategory", columns=["category", "subcategory"], user_groups=["manager", "employee"]),
     ]
-    p.SingleSelectParameter.CreateWithOptions(
-        "group_by", "Group By", group_by_options, description="Dimension(s) to aggregate by", user_attribute=user_attribute
-    )
 
-    ## Example of creating NumberParameter with options
-    parent = "group_by"
-    limit_options = [po.NumberParameterOption(0, 1000, increment=10, default_value=1000, parent_option_ids="trans")]
-    p.NumberParameter.CreateWithOptions(
-        "limit", "Max Number of Rows", limit_options, parent_name=parent, description="Maximum number of rows to return"
-    )
 
-    ## Example of creating DateParameter
-    start_date_source = ds.DateDataSource(
-        "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(
-        "start_date", "Start Date", start_date_source, description="Start date to filter transactions by"
+## 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
-    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", "2024-01-01", "2024-12-31", min_date="2024-01-01", max_date="2024-12-31",
-        description="Date range to filter transactions by"
-    )
+## 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 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 transactions by"
-    )
 
-    ## 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 transactions by (available options are based on selected value(s) of 'Category Filter')"
-    )
+## 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 NumberParameter
-    p.NumberParameter.CreateSimple(
-        "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 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 NumberParameter from lookup query/table
-    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"
+
+
+## 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 NumberRangeParameter
-    p.NumberRangeParameter.CreateSimple(
-        "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"
+
+## 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

@@ -1,23 +1,56 @@
-from typing import Literal
-from squirrels import types as t
+from typing import Literal, Any
+from squirrels.auth import CustomUserFields as BaseCustomUserFields, ProviderConfigs, RegisteredUser, provider
+from squirrels.arguments import AuthProviderArgs
 
 
-class User(t.BaseUser):
+class CustomUserFields(BaseCustomUserFields):
     """
-    Extend the BaseUser class with custom attributes. The attributes defined here will be added as columns to the users table. 
+    Extend the CustomUserFields class to add custom user attributes. 
     - 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).
+    - 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"
-
-    @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 []
+    role: Literal["manager", "staff", "customer"] = "staff"
+
+
+# @provider(
+#     name="google", label="Google", 
+#     icon="https://www.google.com/favicon.ico"
+#     # ^ Note: You also can save the google favicon as an image file in "resources/public/logos/google.ico" 
+#     #   and use icon="/public/logos/google.ico" instead
+# )
+def google_auth_provider(sqrl: AuthProviderArgs) -> ProviderConfigs:
+    """
+    Example 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
+
+    IMPORTANT: Avoid using Google OAuth if you set auth_strategy to 'external'.
+    - If auth_strategy is 'external', MCP clients would require Dynamic Client Registration (DCR) to 
+      authenticate with the associated OAuth provider used by the Squirrels MCP server.
+    - Unfortunately, Google OAuth (and many other OAuth providers) do not support DCR. If auth_strategy 
+      is 'external', consider using an alternative that supports DCR instead (such as WorkOS or Keycloak).
+    """
+    def get_sqrl_user(claims: dict[str, Any]) -> RegisteredUser:
+        custom_fields = CustomUserFields(role="customer")
+        return RegisteredUser(
+            username=claims["email"],
+            access_level="member", # or "admin"
+            custom_fields=custom_fields
+        )
+
+    # TODO: Add GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET to the .env file
+    # Then, uncomment the @provider decorator above and set the client_id and client_secret below
+    provider_configs = 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

@@ -1,7 +1,7 @@
 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
+cast_column_types: true  # optional, default is false - if set to true, then SQRL_SEEDS__INFER_SCHEMA is ignored for this seed
 
 columns:
   - name: category_id

squirrels/_package_data/base_project/seeds/seed_subcategories.yml

@@ -1,7 +1,7 @@
 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
+cast_column_types: true  # optional, default is false - if set to true, then SQRL_SEEDS__INFER_SCHEMA is ignored for this seed
 
 columns:
   - name: subcategory_id

squirrels/_package_data/base_project/squirrels.yml.j2

@@ -1,8 +1,9 @@
 project_variables:
-  name: sample
-  label: Sample Project - Expenses
-  description: This is a sample squirrels project for analyzing expense transactions
+  name: expenses
+  label: "Sample Expenses"
+  description: This is a sample Squirrels project for analyzing expense transactions
   major_version: 1
+  auth_type: optional                     ## one of 'optional' (default) or 'required'
 
 
 packages: []
@@ -21,51 +22,40 @@ packages: []
 
 
 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: public                         ## optional - one of 'public' (default), 'protected', or 'private'
+  - name: expense_transactions
+    label: Expense Transactions - DBView Example
+    description: All expense transactions
+    model: dbview_example                 ## optional - if not specified, model name uses the dataset name
+    scope: private                        ## optional - one of 'public', 'protected', or 'private'. Default is 'public' (if auth_type is 'optional') or 'protected' (if auth_type is 'required').
     parameters:                           ## optional - if not specified, then all parameters are used
       - start_date
       - end_date
       - min_filter
       - max_filter
-    traits: {}                            ## optional - defaults to empty object
   
-  - name: federate_dataset_example
-    label: Example Dataset from Federate Model
+  - name: grouped_expenses
+    label: Grouped Expenses - Federate Example
     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
+    model: federate_example
     parameters:
       - group_by
-      - limit
       - 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
-      - dbview_dataset_example
-    parameters:                           ## optional section - if not provided, then assumes no parameters. For unspecified parameters, default value is used
-      start_date: 2024-07-01              ## this parameter only exists for dataset 'dataset_example'
+  - 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: auth_test1
-    datasets:
-      - federate_dataset_example
-    user_attributes:                      ## optional section - required if using test set on non-public datasets
-      role: employee
+  - name: set_date_range
     parameters:
-      date_range: [2024-02-01,2024-12-01] ## this parameter only exists for dataset 'protected_dataset_example'
+      date_range: [2024-02-01,2024-11-30] ## this parameter is only used by model "federate_example"
     
-  - name: auth_test2
-    user_attributes:
-      is_internal: True                   ## optional - defaults to False
-      role: manager
+  - name: use_admin_privileged_group_by
+    user:
+      access_level: admin
     parameters:
-      group_by: g3                        ## this parameter exists for all datasets. "g3" is the id for option "subcategory"
+      group_by: trans

squirrels/_package_data/templates/login_successful.html

@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Signed In</title>
+  <style>
+    body {
+      font-family: -apple-system, system-ui, sans-serif;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      height: 100vh;
+      margin: 0;
+      background-color: #f9fafb;
+      color: #111827;
+    }
+    .card {
+      text-align: center;
+      padding: 24px;
+    }
+    .icon {
+      color: #059669;
+      font-size: 48px;
+      margin-bottom: 16px;
+    }
+    h1 {
+      font-size: 24px;
+      font-weight: 600;
+      margin: 0 0 8px;
+    }
+    p {
+      font-size: 16px;
+      color: #6b7280;
+      margin: 0;
+    }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="icon">✓</div>
+    <h1>Signed in successfully</h1>
+    <p>You can close this window now.</p>
+  </div>
+
+  <script>
+    if (window.opener) {
+      window.opener.postMessage({ type: "squirrels:auth:login-successful" }, "*");
+      setTimeout(function() { window.close(); }, 1000);
+    }
+  </script>
+</body>
+</html>

squirrels/_package_data/templates/squirrels_studio.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link id="favicon" rel="icon" type="image/svg+xml" href="{{ sqrl_studio_base_url }}/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Squirrels Studio</title>
+    <script>
+      // Optional: Set global defaults for project parameters
+      window.DEFAULT_MOUNTPATH = '{{ mount_path }}';
+    </script>
+    <!-- 
+      GitHub Pages serves static files with a Cache-Control header that typically tells the browser to cache for 10 minutes.
+      The implementation of squirrels-studio-v2 should be compatible with all versions of Squirrels from v0.6.0 onwards.
+    -->
+    <script type="module" crossorigin src="{{ sqrl_studio_base_url }}/assets/index.js"></script>
+    <link rel="stylesheet" crossorigin href="{{ sqrl_studio_base_url }}/assets/index.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>