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

squirrels/package_data/base_project/.gitignore

@@ -1,4 +1,4 @@
-__pycache__
+**/__pycache__/
 
 # common virtual environment names
 .env/
@@ -6,7 +6,7 @@ __pycache__
 venv/
 
 # squirrels files to ignore
-environcfg.yml
 env.yml
+logs/
 target/
 sqrl_packages/

squirrels/package_data/base_project/connections.yml

@@ -2,6 +2,6 @@
 connections:
   - name: default
     credential: null
-    url: {{ env_vars.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 env.yml
 
 

squirrels/package_data/base_project/dashboards/dashboard_example.py

@@ -0,0 +1,32 @@
+from squirrels import DashboardArgs, dashboards as d
+from matplotlib import pyplot as plt, figure as f, axes as a
+
+
+async def main(sqrl: DashboardArgs) -> d.PngDashboard:
+    """
+    Create a dashboard by retrieving datasets using "sqrl.dataset" method and transform the datasets to return as a PngDashboard or a HtmlDashboard.
+    - The PngDashboard constructor takes a single argument for either a matplotlib.figure.Figure or io.BytesIO/bytes of PNG data
+    - The HtmlDashboard constructor takes a single argument for a io.StringIO/string of HTML data
+
+    It is imperative to set the correct return type in the function signature for "main" above! It allows Squirrels to provide the correct format to 
+    the data catalog without having to run this function.
+    """
+    spending_by_month_df = await sqrl.dataset("dataset_example", fixed_parameters={"group_by": "g4"})
+    spending_by_subcategory_df = await sqrl.dataset("dataset_example", fixed_parameters={"group_by": "g3"})
+
+    # Create a figure with two subplots
+    fig, (ax0, ax1) = plt.subplots(2, 1, figsize=(8, 8), height_ratios=(1, 2))
+    fig: f.Figure; ax0: a.Axes; ax1: a.Axes
+    fig.tight_layout(pad=4, h_pad=6)
+
+    # Create a bar chart of spending by month
+    spending_by_month_df.sort_values("month").plot(x="month", y="total_amount", ax=ax0)
+    ax0.set_title("Spending by Month")
+
+    # Create a pie chart of spending by subcategory
+    df_by_subcategory = spending_by_subcategory_df.set_index("subcategory").sort_values("total_amount", ascending=False)
+    autopct = lambda pct: ('%.1f%%' % pct) if pct > 6 else ''
+    df_by_subcategory.plot(y="total_amount", kind='pie', ax=ax1, autopct=autopct, legend=False, ylabel="")
+    ax1.set_title("Spending by Subcategory")
+    
+    return d.PngDashboard(fig)

squirrels/package_data/base_project/dashboards.yml

@@ -0,0 +1,10 @@
+dashboards:
+  - name: dashboard_example
+    label: Dashboard Example
+    scope: public
+    parameters:
+      - start_date
+      - end_date
+      - category
+
+

squirrels/package_data/base_project/docker/.dockerignore

@@ -1,8 +1,13 @@
-__pycache__
-venv/
-.git
+**/__pycache__/
+
+# common virtual environment names
+.venv/
 
 # squirrels files to ignore
-environcfg.yml
+env.yml
 target/
 sqrl_packages/
+
+# additional files for docker to ignore
+Dockerfile
+.git/

squirrels/package_data/base_project/docker/Dockerfile

@@ -1,15 +1,16 @@
-# Change here to use different python version (ex. 3.12-slim for version 3.12)
-FROM python:3.11-slim
+# Change here to use different python version (ex. 3.11-slim for version 3.11)
+FROM python:3.12-slim
 WORKDIR /app
 
-# Needed if any python dependencies are installed from git, or for 
-# "squirrels deps" command if there are packages defined in "squirrels.yml"
+COPY . .
+
+# Only needed if there are python dependencies installed using git, or for the
+# "sqrl deps" command if there are packages defined in "squirrels.yml"
 RUN apt-get update && apt-get install -y git
 
-COPY requirements-lock.txt .
 RUN pip install --no-cache-dir -r requirements-lock.txt
 
-COPY . .
 RUN squirrels deps
 
+EXPOSE 4465
 CMD ["squirrels", "run", "--host", "0.0.0.0", "--port", "4465"]

squirrels/package_data/base_project/docker/compose.yml

@@ -4,4 +4,4 @@ services:
     ports:
       - "4465:4465"
     volumes:
-      - ./environcfg.yml:/app/environcfg.yml
+      - ./env.yml:/app/env.yml

squirrels/package_data/base_project/env.yml

@@ -7,7 +7,7 @@ users:
     is_internal: True
     password: I<3Squirrels
     full_name: Alice Doe
-    role: employee
+    role: manager
   bob:
     is_internal: False
     password: abcd5678
@@ -16,7 +16,7 @@ users:
 
 ## Custom environment variables / secrets
 env_vars:
-  sqlite_conn_str: sqlite://{username}:{password}@/./assets/expenses.db
+  sqlite_conn_str: sqlite://{username}:{password}@/{project_path}/assets/expenses.db
 
 ## Database credentials
 credentials:

squirrels/package_data/base_project/models/dbviews/{database_view1.py → dbview_example.py}

@@ -24,7 +24,8 @@ def main(sqrl: ModelArgs) -> pd.DataFrame:
         WITH
         transactions_with_masked_id AS (
             SELECT *, 
-                {masked_id} as masked_id
+                {masked_id} as masked_id,
+                STRFTIME('%Y-%m', date) AS month
             FROM transactions
         )
         SELECT {sqrl.ctx["select_dim_cols"]}

squirrels/package_data/base_project/models/dbviews/{database_view1.sql → dbview_example.sql}

@@ -5,11 +5,12 @@ transactions_with_masked_id AS (
         id as masked_id
 {%- else %}
         '***' as masked_id
-{%- endif %}
+{%- endif %},
+        STRFTIME('%Y-%m', date) AS month
     FROM transactions
 )
 SELECT {{ ctx.select_dim_cols }}
-    , sum(-amount) as total_amount
+    , SUM(-amount) as total_amount
 FROM transactions_with_masked_id
 WHERE date >= :start_date
     AND date <= :end_date

squirrels/package_data/base_project/models/federates/{dataset_example.py → federate_example.py}

@@ -1,14 +1,14 @@
-from typing import Iterable
+from typing import Sequence
 from squirrels import ModelDepsArgs, ModelArgs
 import pandas as pd
 
 
-def dependencies(sqrl: ModelDepsArgs) -> Iterable[str]:
+def dependencies(sqrl: ModelDepsArgs) -> Sequence[str]:
     """
     Define list of dependent models here. This will determine the dependencies first, at compile-time, 
     before running the model.
     """
-    return ["database_view1"]
+    return ["dbview_example"]
 
 
 def main(sqrl: ModelArgs) -> pd.DataFrame:
@@ -16,6 +16,6 @@ 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")
-    order_by_cols: str = sqrl.ctx["order_by_cols_list"]
-    return df.sort_values(order_by_cols, ascending=False)
+    (DBVIEW_EXAMPLE,) = dependencies(sqrl)
+    df = sqrl.ref(DBVIEW_EXAMPLE)
+    return df.sort_values(sqrl.ctx["order_by_cols_list"], ascending=False)

squirrels/package_data/base_project/models/federates/{dataset_example.sql → federate_example.sql}

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

squirrels/package_data/base_project/parameters.yml

@@ -36,14 +36,16 @@ parameters:
         - parent_option_ids: g0
   
   - type: DateParameter
-    factory: CreateWithOptions
+    factory: CreateFromSource
     arguments:
       name: start_date
       label: Start Date
       description: Start date to filter transactions by
-      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
+      data_source:
+        table_or_query: SELECT min(date) AS min_date, max(date) AS max_date FROM transactions
+        default_date_col: min_date
+        min_date_col: min_date
+        max_date_col: max_date
   
   - type: DateParameter
     factory: CreateWithOptions

squirrels/package_data/base_project/pyconfigs/auth.py

@@ -18,7 +18,7 @@ def get_user_if_valid(sqrl: AuthArgs) -> Union[User, WrongPassword, None]:
     Return:
         - User instance - if username and password are correct
         - WrongPassword() - if username exists but password is incorrect
-        - None - if the username doesn't exist (and search for username will continue for "fake users" configured in environcfg.yml)
+        - None - if the username doesn't exist (and search for username will continue for "fake users" configured in env.yml)
     """
     mock_users_db = {
         "johndoe": {

squirrels/package_data/base_project/pyconfigs/connections.py

@@ -10,7 +10,7 @@ def main(connections: dict[str, Engine], sqrl: ConnectionsArgs) -> None:
     ## SQLAlchemy URL for a connection engine
     conn_str = 'sqlite:///./assets/expenses.db' 
 
-    ## Can also leverage environment variables and credentials in the environcfg.yml file for connection details
+    ## 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) 

squirrels/package_data/base_project/pyconfigs/context.py

@@ -11,9 +11,12 @@ def main(ctx: dict[str, Any], sqrl: ContextArgs) -> None:
     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"]
+        group_by_param = sqrl.prms["group_by"]
+        assert isinstance(group_by_param, p.SingleSelectParameter)
+        
         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)
 
         ctx["select_dim_cols"] = ", ".join(x+" as "+y for x, y in zip(columns, aliases))
         ctx["group_by_cols"] = ", ".join(columns)
@@ -21,51 +24,76 @@ def main(ctx: dict[str, Any], sqrl: ContextArgs) -> None:
         ctx["order_by_cols_list"] = aliases
 
     if sqrl.param_exists("description_filter"):
-        descript_param: p.TextParameter = sqrl.prms["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)
 
     if sqrl.param_exists("start_date"):
-        start_date_param: p.DateParameter = sqrl.prms["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)
     
     if sqrl.param_exists("end_date"):
-        end_date_param: p.DateParameter = sqrl.prms["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)
 
     if sqrl.param_exists("date_range"):
-        date_range_param: p.DateRangeParameter = sqrl.prms["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)
     
     if sqrl.param_exists("category"):
-        category_param: p.MultiSelectParameter = sqrl.prms["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()
     
     if sqrl.param_exists("subcategory"):
-        subcategory_param: p.MultiSelectParameter = sqrl.prms["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()
     
     if sqrl.param_exists("min_filter"):
-        min_amount_filter: p.NumberParameter = sqrl.prms["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)
     
     if sqrl.param_exists("max_filter"):
-        max_amount_filter: p.NumberParameter = sqrl.prms["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)
 
     if sqrl.param_exists("between_filter"):
-        between_filter: p.NumberRangeParameter = sqrl.prms["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)
     

squirrels/package_data/base_project/pyconfigs/parameters.py

@@ -20,6 +20,7 @@ def main(sqrl: ParametersArgs) -> None:
     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"]),
     ]
@@ -29,26 +30,33 @@ def main(sqrl: ParametersArgs) -> None:
 
     ## Example of creating a TextParameter
     parent_name = "group_by"
-    text_options = [po.TextParameterOption(parent_option_ids="g0")]
+    description_text_options = [
+        po.TextParameterOption(parent_option_ids="g0")
+    ]
     p.TextParameter.CreateWithOptions(
-        "description_filter", "Description Contains", text_options, parent_name=parent_name,
+        "description_filter", "Description Contains", description_text_options, parent_name=parent_name,
         description="Substring of description to filter transactions by"
     )
 
-    ## Example of creating DateParameter
-    p.DateParameter.CreateSimple(
-        "start_date", "Start Date", "2023-01-01", description="Start date to filter transactions by"
+    ## Example of creating DateParameter from lookup query/table
+    start_date_source = ds.DateDataSource(
+        "SELECT min(date) AS min_date, max(date) AS max_date FROM transactions",
+        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 from list of DateParameterOption's
-    end_date_option = [po.DateParameterOption("2023-12-31")]
+    end_date_option = [po.DateParameterOption("2023-12-31", min_date="2023-01-01", max_date="2023-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", description="Date range to filter transactions by"
+        "date_range", "Date Range", "2023-01-01", "2023-12-31", min_date="2023-01-01", max_date="2023-12-31",
+        description="Date range to filter transactions by"
     )
 
     ## Example of creating MultiSelectParameter from lookup query/table

squirrels/package_data/base_project/squirrels.yml.j2

@@ -6,10 +6,11 @@ project_variables:
 
 packages: []
 
-## Example value for packages:
-#  - git: https://.../myrepo.git
-#    revision: v0.1.0
-#    directory: custom_name ## optional
+## Example for packages section:
+# packages:
+#   - git: https://.../myrepo.git
+#     revision: v0.1.0
+#     directory: custom_name ## optional
 
 
 {{ connections -}}
@@ -21,6 +22,7 @@ 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
     scope: public                         ## optional - one of 'public' (default), 'protected', or 'private'
     parameters:                           ## optional - if not specified, then all parameters are used
       - group_by
@@ -35,7 +37,7 @@ datasets:
   
   - name: protected_dataset_example       ## requires auth.py file to work
     label: Dataset Example 2
-    model: dataset_example
+    model: federate_example
     scope: protected
     parameters:
       - group_by
@@ -47,6 +49,9 @@ 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
@@ -77,8 +82,10 @@ settings: {}
 #   auth.token.expire_minutes: 30
 #   parameters.cache.size: 1024
 #   parameters.cache.ttl_minutes: 60
-#   results.cache.size: 128
-#   results.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

squirrels/package_data/templates/index.html

@@ -6,11 +6,11 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <script>
       const hostname = '';
-      const catalogURL = '{{ catalog_path }}';
+      const projectMetadataURL = '{{ project_metadata_path }}';
     </script>
     <title>Squirrels Testing UI</title>
-    <script type="module" crossorigin src="/assets/index.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index.css">
+    <script type="module" crossorigin src="/assets/index.js?version=0.4.0"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index.css?version=0.4.0">
   </head>
   <body>
     <div id="root"></div>