squirrels 0.3.3__tar.gz → 0.4.0__tar.gz

{squirrels-0.3.3 → squirrels-0.4.0}/PKG-INFO

@@ -1,16 +1,15 @@
 Metadata-Version: 2.1
 Name: squirrels
-Version: 0.3.3
+Version: 0.4.0
 Summary: Squirrels - API Framework for Data Analytics
 Home-page: https://squirrels-analytics.github.io
 License: Apache-2.0
 Author: Tim Huang
 Author-email: tim.yuting@hotmail.com
-Requires-Python: >=3.9,<4.0
+Requires-Python: >=3.10,<4.0
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -27,6 +26,7 @@ Requires-Dist: jinja2 (>=3.1.3,<4.0.0)
 Requires-Dist: matplotlib (>=3.8.3,<4.0.0)
 Requires-Dist: networkx (>=3.2.1,<4.0.0)
 Requires-Dist: pandas (>=2.1.4,<3.0.0)
+Requires-Dist: pydantic (>=2.8.2,<3.0.0)
 Requires-Dist: pyjwt (>=2.8.0,<3.0.0)
 Requires-Dist: python-multipart (>=0.0.9,<0.0.10)
 Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
@@ -77,19 +77,7 @@ The sections below describe how to set up your local environment for squirrels d
 
 ### Setup
 
-This project requires python version 3.9 or above to be installed. It also uses the python build tool `poetry` which can be installed as follows.
-
-**Linux, MacOS, Windows (WSL):**
-
-```bash
-curl -sSL https://install.python-poetry.org | python3 -
-```
-
-**Windows (Powershell):**
-
-```bash
-(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
-```
+This project requires python version 3.10 or above to be installed. It also uses the python build tool `poetry`. Information on setting up poetry can be found at: https://python-poetry.org/docs/.
 
 Then, to install all dependencies, run:
 
@@ -106,10 +94,10 @@ poetry shell
 To confirm that the setup worked, run the following to show the help page for all squirrels CLI commands:
 
 ```bash
-squirrels -h
+sqrl -h
 ```
 
-You can enter `exit` to exit the virtual environment shell. You can also run `poetry run squirrels -h` to run squirrels commands without activating the virtual environment.
+You can enter `exit` to exit the virtual environment shell. You can also run `poetry run sqrl -h` to run squirrels commands without activating the virtual environment.
 
 ### Testing
 
@@ -121,9 +109,9 @@ From the root of the git repo, the source code can be found in the `squirrels` f
 
 To understand what a specific squirrels command is doing, start from the `_command_line.py` file as your entry point.
 
-The library version is maintained in both the `pyproject.toml` and the `squirrels/__init__.py` files.
+The library version is maintained in both the `pyproject.toml` and the `squirrels/_version.py` files.
 
-When a user initializes a squirrels project using `squirrels init`, the files are copied from the `squirrels/package_data/base_project` folder. The contents in the `database` subfolder were constructed from the scripts in the `database_elt` folder.
+When a user initializes a squirrels project using `sqrl init`, the files are copied from the `squirrels/package_data/base_project` folder. The contents in the `database` subfolder were constructed from the scripts in the `database_elt` folder.
 
-For the Squirrels UI activated by `squirrels run`, the HTML, CSS, and Javascript files can be found in the `static` and `templates` subfolders of `squirrels/package_data`.
+For the Squirrels UI activated by `sqrl run`, the HTML, CSS, and Javascript files can be found in the `static` and `templates` subfolders of `squirrels/package_data`. The CSS and Javascript files are minified and built from the source files in this project: https://github.com/squirrels-analytics/squirrels-testing-ui.
 

{squirrels-0.3.3 → squirrels-0.4.0}/README.md

@@ -39,19 +39,7 @@ The sections below describe how to set up your local environment for squirrels d
 
 ### Setup
 
-This project requires python version 3.9 or above to be installed. It also uses the python build tool `poetry` which can be installed as follows.
-
-**Linux, MacOS, Windows (WSL):**
-
-```bash
-curl -sSL https://install.python-poetry.org | python3 -
-```
-
-**Windows (Powershell):**
-
-```bash
-(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
-```
+This project requires python version 3.10 or above to be installed. It also uses the python build tool `poetry`. Information on setting up poetry can be found at: https://python-poetry.org/docs/.
 
 Then, to install all dependencies, run:
 
@@ -68,10 +56,10 @@ poetry shell
 To confirm that the setup worked, run the following to show the help page for all squirrels CLI commands:
 
 ```bash
-squirrels -h
+sqrl -h
 ```
 
-You can enter `exit` to exit the virtual environment shell. You can also run `poetry run squirrels -h` to run squirrels commands without activating the virtual environment.
+You can enter `exit` to exit the virtual environment shell. You can also run `poetry run sqrl -h` to run squirrels commands without activating the virtual environment.
 
 ### Testing
 
@@ -83,8 +71,8 @@ From the root of the git repo, the source code can be found in the `squirrels` f
 
 To understand what a specific squirrels command is doing, start from the `_command_line.py` file as your entry point.
 
-The library version is maintained in both the `pyproject.toml` and the `squirrels/__init__.py` files.
+The library version is maintained in both the `pyproject.toml` and the `squirrels/_version.py` files.
 
-When a user initializes a squirrels project using `squirrels init`, the files are copied from the `squirrels/package_data/base_project` folder. The contents in the `database` subfolder were constructed from the scripts in the `database_elt` folder.
+When a user initializes a squirrels project using `sqrl init`, the files are copied from the `squirrels/package_data/base_project` folder. The contents in the `database` subfolder were constructed from the scripts in the `database_elt` folder.
 
-For the Squirrels UI activated by `squirrels run`, the HTML, CSS, and Javascript files can be found in the `static` and `templates` subfolders of `squirrels/package_data`.
+For the Squirrels UI activated by `sqrl run`, the HTML, CSS, and Javascript files can be found in the `static` and `templates` subfolders of `squirrels/package_data`. The CSS and Javascript files are minified and built from the source files in this project: https://github.com/squirrels-analytics/squirrels-testing-ui.

{squirrels-0.3.3 → squirrels-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "squirrels"
-version = "0.3.3"
+version = "0.4.0"
 description = "Squirrels - API Framework for Data Analytics"
 license = "Apache-2.0"
 authors = ["Tim Huang <tim.yuting@hotmail.com>"]
@@ -20,21 +20,22 @@ squirrels = "squirrels._command_line:main"
 sqrl = "squirrels._command_line:main"
 
 [tool.poetry.dependencies]
-python = "^3.9"
+python = "^3.10"
 cachetools = "^5.3.2"
 fastapi = "^0.112.1"
 gitpython = "^3.1.41"
 inquirer = "^3.2.1"
 jinja2 = "^3.1.3"
+matplotlib = "^3.8.3"
+networkx = "^3.2.1"
 pandas = "^2.1.4"
+pydantic = "^2.8.2"
 pyjwt = "^2.8.0"
+python-multipart = "^0.0.9"
 pyyaml = "^6.0.1"
 sqlalchemy = "^2.0.25"
 uvicorn = "^0.30.6"
 duckdb-engine = { version = ">=0.13.0,<1.0.0", optional = true }
-matplotlib = "^3.8.3"
-networkx = "^3.2.1"
-python-multipart = "^0.0.9"
 
 
 [tool.poetry.extras]
@@ -46,6 +47,7 @@ pytest = "^7.4.4"
 
 [tool.poetry.group.dev.dependencies]
 ipykernel = "^6.29.4"
+plotly = "^5.24.0"
 
 [build-system]
 requires = ["poetry-core"]

{squirrels-0.3.3 → squirrels-0.4.0}/squirrels/__init__.py

@@ -1,15 +1,19 @@
-__version__ = '0.3.3'
+from ._version import __version__
 
 from .arguments.init_time_args import ConnectionsArgs, ParametersArgs
-from .arguments.run_time_args import AuthArgs, ContextArgs, ModelDepsArgs, ModelArgs
+from .arguments.run_time_args import AuthArgs, ContextArgs, ModelDepsArgs, ModelArgs, DashboardArgs
 
 from .parameter_options import SelectParameterOption, DateParameterOption, DateRangeParameterOption
 from .parameter_options import NumberParameterOption, NumberRangeParameterOption, TextParameterOption
 
 from .parameters import SingleSelectParameter, MultiSelectParameter, DateParameter, DateRangeParameter
-from .parameters import NumberParameter, NumberRangeParameter, TextParameter
+from .parameters import NumberParameter, NumberRangeParameter, TextParameter, TextValue
 
 from .data_sources import SingleSelectDataSource, MultiSelectDataSource, SelectDataSource, DateDataSource, DateRangeDataSource
 from .data_sources import NumberDataSource, NumberRangeDataSource, TextDataSource
 
 from .user_base import User, WrongPassword
+
+from .dashboards import PngDashboard, HtmlDashboard
+
+from .project import SquirrelsProject

squirrels-0.4.0/squirrels/_api_response_models.py

@@ -0,0 +1,141 @@
+from typing import Annotated
+from pydantic import BaseModel, Field
+from datetime import datetime, date
+
+
+class LoginReponse(BaseModel):
+    access_token: Annotated[str, Field(examples=["encoded_jwt_token"], description="An encoded JSON web token to use subsequent API requests")]
+    token_type: Annotated[str, Field(examples=["bearer"], description='Always "bearer" for Bearer token')]
+    username: Annotated[str, Field(examples=["johndoe"], description='The username authenticated with from the form data')]
+    expiry_time: Annotated[datetime, Field(examples=["2023-08-01T12:00:00.000000Z"], description="The expiry time of the access token in yyyy-MM-dd'T'hh:mm:ss.SSSSSS'Z' format")]
+
+
+## Datasets / Dashboards Catalog Response Models
+
+name_description = "The name of the dataset / dashboard (usually in snake case)"
+label_description = "The human-friendly display name for the dataset / dashboard"
+description_description = "The description of the dataset / dashboard"
+parameters_path_description = "The API path to the parameters for the dataset / dashboard"
+result_path_description = "The API path to the results for the dataset / dashboard"
+
+class DatasetItemModel(BaseModel):
+    name: Annotated[str, Field(examples=["mydataset"], description=name_description)]
+    label: Annotated[str, Field(examples=["My Dataset"], description=label_description)]
+    description: Annotated[str, Field(examples=[""], description=description_description)]
+    parameters_path: Annotated[str, Field(examples=["/squirrels-v0/myproject/v1/dataset/mydataset/parameters"], description=parameters_path_description)]
+    result_path: Annotated[str, Field(examples=["/squirrels-v0/myproject/v1/dataset/mydataset"], description=result_path_description)]
+
+class DashboardItemModel(BaseModel):
+    name: Annotated[str, Field(examples=["mydashboard"], description=name_description)]
+    label: Annotated[str, Field(examples=["My Dashboard"], description=label_description)]
+    description: Annotated[str, Field(examples=[""], description=description_description)]
+    parameters_path: Annotated[str, Field(examples=["/squirrels-v0/myproject/v1/dashboard/mydashboard/parameters"], description=parameters_path_description)]
+    result_path: Annotated[str, Field(examples=["/squirrels-v0/myproject/v1/dashboard/mydashboard"], description=result_path_description)]
+    result_format: Annotated[str, Field(examples=["png", "html"], description="The format of the dashboard's result API response (one of 'png' or 'html')")]
+
+class CatalogModel(BaseModel):
+    datasets: Annotated[list[DatasetItemModel], Field(description="The list of accessible datasets")]
+    dashboards: Annotated[list[DashboardItemModel], Field(description="The list of accessible dashboards")]
+
+
+## Parameters Response Models
+
+class ParameterOptionModel(BaseModel):
+    id: Annotated[str, Field(examples=["my_option_id"], description="The unique identifier for the option")]
+    label: Annotated[str, Field(examples=["My Option"], description="The human-friendly display name for the option")]
+
+class ParameterModelBase(BaseModel):
+    widget_type: Annotated[str, Field(examples=["none"], description="The parameter type (set to 'none' for this model)")]
+    name: Annotated[str, Field(examples=["my_unique_param_name"], description="The name of the parameter. Use this as the key when providing the API request parameters")]
+    label: Annotated[str, Field(examples=["My Parameter"], description="The human-friendly display name for the parameter")]
+    description: Annotated[str, Field(examples=[""], description="The description of the parameter")]
+
+class NoneParameterModel(ParameterModelBase):
+    pass
+
+class SelectParameterModel(ParameterModelBase):
+    options: Annotated[list[ParameterOptionModel], Field(description="The list of dropdown options as JSON objects containing 'id' and 'label' fields")]
+    trigger_refresh: Annotated[bool, Field(description="A boolean that's set to true for parent parameters that require a new parameters API call when the selection changes")]
+
+class SingleSelectParameterModel(SelectParameterModel):
+    widget_type: Annotated[str, Field(examples=["single_select"], description="The parameter type (set to 'single_select' for this model)")]
+    selected_id: Annotated[str | None, Field(examples=["my_option_id"], description="The ID of the selected / default option")]
+
+class MultiSelectParameterModel(SelectParameterModel):
+    widget_type: Annotated[str, Field(examples=["multi_select"], description="The parameter type (set to 'multi_select' for this model)")]
+    show_select_all: Annotated[bool, Field(description="A boolean for whether there should be a toggle to select all options")]
+    order_matters: Annotated[bool, Field(description="A boolean for whether the ordering of the input selections would affect the result of the dataset")]
+    selected_ids: Annotated[list[str], Field(examples=[["my_option_id"]], description="A list of ids of the selected / default options")]
+
+class _DateTypeParameterModel(ParameterModelBase):
+    min_date: Annotated[date | None, Field(examples=["2023-01-01"], description='A string in "yyyy-MM-dd" format for the minimum date')]
+    max_date: Annotated[date | None, Field(examples=["2023-12-31"], description='A string in "yyyy-MM-dd" format for the maximum date')]
+
+class DateParameterModel(_DateTypeParameterModel):
+    widget_type: Annotated[str, Field(examples=["date"], description="The parameter type (set to 'date' for this model)")]
+    selected_date: Annotated[date, Field(examples=["2023-01-01"], description='A string in "yyyy-MM-dd" format for the selected / default date')]
+
+class DateRangeParameterModel(_DateTypeParameterModel):
+    widget_type: Annotated[str, Field(examples=["date_range"], description="The parameter type (set to 'date_range' for this model)")]
+    selected_start_date: Annotated[date, Field(examples=["2023-01-01"], description='A string in "yyyy-MM-dd" format for the selected / default start date')]
+    selected_end_date: Annotated[date, Field(examples=["2023-12-31"], description='A string in "yyyy-MM-dd" format for the selected / default end date')]
+
+class _NumericParameterModel(ParameterModelBase):
+    min_value: Annotated[float, Field(examples=[0], description="A number for the lower bound of the selectable number")]
+    max_value: Annotated[float, Field(examples=[10], description="A number for the upper bound of the selectable number")]
+    increment: Annotated[float, Field(examples=[1], description="A number for the selectable increments between the lower bound and upper bound")]
+
+class NumberParameterModel(_NumericParameterModel):
+    widget_type: Annotated[str, Field(examples=["number"], description="The parameter type (set to 'number' for this model)")]
+    selected_value: Annotated[float, Field(examples=[2], description="A number for the selected / default number")]
+
+class NumberRangeParameterModel(_NumericParameterModel):
+    widget_type: Annotated[str, Field(examples=["number_range"], description="The parameter type (set to 'number_range' for this model)")]
+    selected_lower_value: Annotated[float, Field(examples=[2], description="A number for the selected / default lower number")]
+    selected_upper_value: Annotated[float, Field(examples=[8], description="A number for the selected / default upper number")]
+
+class TextParameterModel(ParameterModelBase):
+    widget_type: Annotated[str, Field(examples=["text"], description="The parameter type (set to 'text' for this model)")]
+    entered_text: Annotated[str, Field(examples=["sushi"], description="A string for the default entered text")]
+    input_type: Annotated[str, Field(
+        examples=["text", "textarea", "number", "date", "datetime-local", "month", "time", "color", "password"],
+        description='A string for the input type (one of "text", "textarea", "number", "date", "datetime-local", "month", "time", "color", or "password")'
+    )]
+
+class ParametersModel(BaseModel):
+    parameters: list[
+        NoneParameterModel | SingleSelectParameterModel | MultiSelectParameterModel | DateParameterModel | DateRangeParameterModel | 
+        NumberParameterModel | NumberRangeParameterModel | TextParameterModel
+    ]
+
+
+## Dataset Results Response Models
+
+class ColumnModel(BaseModel):
+    name: Annotated[str, Field(examples=["mycol"], description="Name of column")]
+    type: Annotated[str, Field(examples=["string", "number", "integer", "boolean", "datetime"], description='Column type. One of "string", "number", "integer", "boolean", and "datetime"')]
+
+class SchemaModel(BaseModel):
+    fields: Annotated[list[ColumnModel], Field(description="A list of JSON objects containing the 'name' and 'type' for each of the columns in the result")]
+    dimensions: Annotated[list[str], Field(examples=[["mycol"]], description="A list of column names that are dimensions")]
+
+class DatasetResultModel(BaseModel):
+    data_schema: Annotated[SchemaModel, Field(alias="schema", description="JSON object describing the schema of the dataset")]
+    data: Annotated[list[dict], Field(
+        examples=[[{"mycol": "myval"}]],
+        description="A list of JSON objects where each object is a row of the tabular results. The keys and values of the object are column names (described in fields) and values of the row."
+    )]
+
+
+## Project Metadata Response Models
+
+class ProjectVersionModel(BaseModel):
+    major_version: int
+    minor_versions: list[int]
+    token_path: Annotated[str, Field(examples=["/squirrels-v0/myproject/v1/token"])]
+    data_catalog_path: Annotated[str, Field(examples=["/squirrels-v0/myproject/v1/datasets"])]
+
+class ProjectModel(BaseModel):
+    name: Annotated[str, Field(examples=["myproject"])]
+    label: Annotated[str, Field(examples=["My Project"])]
+    versions: list[ProjectVersionModel]