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

squirrels/package_data/base_project/connections.yml

@@ -1,7 +0,0 @@
-## Uses SQLAlchemy URLs. More details here: https://docs.sqlalchemy.org/en/latest/core/engines.html
-connections:
-  - name: default
-    credential: null
-    url: {{ env_vars.sqlite_conn_str }}   ## using Jinja to substitute environment variable from env.yml
-
-

squirrels/package_data/base_project/dashboards/dashboard_example.py

@@ -1,32 +0,0 @@
-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

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

squirrels/package_data/base_project/env.yml

@@ -1,29 +0,0 @@
-## 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. Must have an 'auth.py' file with a 'User' model to use custom attributes like 'role'
-users:
-  alice:
-    is_internal: True
-    password: I<3Squirrels
-    full_name: Alice Doe
-    role: manager
-  bob:
-    is_internal: False
-    password: abcd5678
-    full_name: Bob Doe
-    role: customer
-
-## Custom environment variables / secrets
-env_vars:
-  sqlite_conn_str: sqlite://{username}:{password}@/{project_path}/assets/expenses.db
-
-## Database credentials
-credentials:
-  db_user:
-    username: user1
-    password: pass1
-
-## Predefined secrets used by the squirrels framework
-secrets:
-  jwt_secret: ## generate a random 32 byte hex string here for the jwt secret/private key. For instance, you can run "openssl rand -hex 32" in bash

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

@@ -1,47 +0,0 @@
-from textwrap import dedent
-from squirrels import ModelArgs
-import pandas as pd
-
-
-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
-    # 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
-    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"""
-        WITH
-        transactions_with_masked_id AS (
-            SELECT *, 
-                {masked_id} as masked_id,
-                STRFTIME('%Y-%m', date) AS month
-            FROM transactions
-        )
-        SELECT {sqrl.ctx["select_dim_cols"]}
-            , sum(-amount) as total_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
-    # return sqrl.run_external_sql(query, connection_name="different_key")

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

@@ -1,22 +0,0 @@
-WITH
-transactions_with_masked_id AS (
-    SELECT *,
-{%- if user.role == "manager" %}
-        id as masked_id
-{%- else %}
-        '***' as masked_id
-{%- endif %},
-        STRFTIME('%Y-%m', date) AS month
-    FROM transactions
-)
-SELECT {{ ctx.select_dim_cols }}
-    , SUM(-amount) as total_amount
-FROM transactions_with_masked_id
-WHERE date >= :start_date
-    AND date <= :end_date
-    AND -amount >= :min_amount
-    AND -amount <= :max_amount
-    {% 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/federate_example.py

@@ -1,21 +0,0 @@
-from typing import Sequence
-from squirrels import ModelDepsArgs, ModelArgs
-import pandas as pd
-
-
-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 ["dbview_example"]
-
-
-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.
-    """
-    (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/federate_example.sql

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

squirrels/package_data/base_project/pyconfigs/auth.py

@@ -1,45 +0,0 @@
-from typing import Union
-from squirrels import User as UserBase, AuthArgs, WrongPassword
-
-
-class User(UserBase):
-    def set_attributes(self, **kwargs) -> None:
-        """
-        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.role = kwargs["role"]
-
-
-def get_user_if_valid(sqrl: AuthArgs) -> Union[User, WrongPassword, None]:
-    """
-    This function allows the squirrels framework to know how to authenticate input username and password.
-
-    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 env.yml)
-    """
-    mock_users_db = {
-        "johndoe": {
-            "username": "johndoe",
-            "is_admin": True,
-            "role": "manager",
-            "hashed_password": str(hash("I<3Squirrels"))
-        },
-        "mattdoe": {
-            "username": "mattdoe",
-            "is_admin": False,
-            "role": "customer",
-            "hashed_password": str(hash("abcd5678"))
-        }
-    }
-
-    user_obj = mock_users_db.get(sqrl.username)
-    if user_obj is None:
-        return None
-    
-    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,19 +0,0 @@
-from sqlalchemy import create_engine, Engine
-from squirrels import ConnectionsArgs
-
-
-def main(connections: dict[str, Engine], 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' 
-
-    ## 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)

squirrels/package_data/base_project/pyconfigs/parameters.py

@@ -1,95 +0,0 @@
-from squirrels import ParametersArgs, parameters as p, parameter_options as po, data_sources as ds
-
-
-def main(sqrl: 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
-    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"]),
-    ]
-    p.SingleSelectParameter.CreateWithOptions(
-        "group_by", "Group By", group_by_options, description="Dimension(s) to aggregate by"
-    )
-
-    ## 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 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", 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", 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
-    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 NumberParameter
-    p.NumberParameter.CreateSimple(
-        "min_filter", "Amounts Greater Than", min_value=0, max_value=500, 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'"
-    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 NumberRangeParameter
-    p.NumberRangeParameter.CreateSimple(
-        "between_filter", "Amounts Between", 0, 500, default_lower_value=10, default_upper_value=400,
-        description="Number range to filter on transactions with an amount within this range"
-    )

squirrels/package_data/base_project/seeds/seed_subcategories.csv

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

squirrels/package_data/base_project/squirrels.yml.j2

@@ -1,94 +0,0 @@
-project_variables:
-  name: sample
-  label: Sample Project
-  major_version: 1
-
-
-packages: []
-
-## Example for packages section:
-# packages:
-#   - git: https://.../myrepo.git
-#     revision: v0.1.0
-#     directory: custom_name ## optional
-
-
-{{ connections -}}
-
-
-{{ parameters -}}
-
-
-datasets:
-  - name: 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
-      - 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
-    parameters:
-      - group_by
-      - description_filter
-      - date_range
-      - category
-      - subcategory
-      - between_filter
-    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
-    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'
-  
-  - name: auth_test1
-    datasets:
-      - protected_dataset_example
-    user_attributes:                      ## optional section - required if using test set on non-public datasets
-      role: customer
-    parameters:
-      date_range: [2023-02-01,2023-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]

squirrels/package_data/templates/index.html

@@ -1,18 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <link id="favicon" rel="icon" type="image/x-icon" href="/assets/favicon.ico" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <script>
-      const hostname = '';
-      const projectMetadataURL = '{{ project_metadata_path }}';
-    </script>
-    <title>Squirrels Testing UI</title>
-    <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>
-  </body>
-</html>