squirrels 0.1.0__py3-none-any.whl → 0.6.0.post0__py3-none-any.whl

squirrels/_env_vars.py

@@ -0,0 +1,209 @@
+from typing import Any, Literal, Optional
+from typing_extensions import Self
+from pathlib import Path
+from pydantic import BaseModel, Field, field_validator, model_validator, ConfigDict
+import json
+
+from . import _constants as c
+
+
+class SquirrelsEnvVars(BaseModel):
+    """
+    Pydantic model for managing and validating Squirrels environment variables.
+    These variables are typically loaded from .env files or the system environment.
+    """
+    model_config = ConfigDict(serialize_by_alias=True)
+    project_path: str
+    
+    # Security
+    secret_key: Optional[str] = Field(
+        None, alias=c.SQRL_SECRET_KEY, 
+        description="Secret key for JWT encoding/decoding and other security operations"
+    )
+    secret_admin_password: Optional[str] = Field(
+        None, alias=c.SQRL_SECRET_ADMIN_PASSWORD, 
+        description="Password for the admin user"
+    )
+    
+    # Auth
+    auth_db_file_path: str = Field(
+        "{project_path}/target/auth.sqlite", alias=c.SQRL_AUTH_DB_FILE_PATH, 
+        description="Path to the SQLite authentication database"
+    )
+    auth_token_expire_minutes: float = Field(
+        30, ge=0, alias=c.SQRL_AUTH_TOKEN_EXPIRE_MINUTES, 
+        description="Expiration time for access tokens in minutes"
+    )
+    auth_credential_origins: list[str] = Field(
+        ["https://squirrels-analytics.github.io"], alias=c.SQRL_AUTH_CREDENTIAL_ORIGINS, 
+        description="Allowed origins for credentials (cookies)"
+    )
+
+    # Permissions
+    elevated_access_level: Literal["admin", "member", "guest"] = Field(
+        "admin", alias=c.SQRL_PERMISSIONS_ELEVATED_ACCESS_LEVEL, 
+        description="Minimum access level to access the studio"
+    )
+
+    # Parameters Cache
+    parameters_cache_size: int = Field(
+        1024, ge=0, alias=c.SQRL_PARAMETERS_CACHE_SIZE, 
+        description="Cache size for parameter configs"
+    )
+    parameters_cache_ttl_minutes: float = Field(
+        60, gt=0, alias=c.SQRL_PARAMETERS_CACHE_TTL_MINUTES, 
+        description="Cache TTL for parameter configs in minutes"
+    )
+    parameters_datasource_refresh_minutes: float = Field(
+        60, alias=c.SQRL_PARAMETERS_DATASOURCE_REFRESH_MINUTES, 
+        description="Interval in minutes for refreshing data sources. A non-positive value disables auto-refresh"
+    )
+    
+    # Datasets Cache
+    datasets_cache_size: int = Field(
+        128, ge=0, alias=c.SQRL_DATASETS_CACHE_SIZE, 
+        description="Cache size for dataset results"
+    )
+    datasets_cache_ttl_minutes: float = Field(
+        60, gt=0, alias=c.SQRL_DATASETS_CACHE_TTL_MINUTES, 
+        description="Cache TTL for dataset results in minutes"
+    )
+    datasets_max_rows_for_ai: int = Field(
+        100, ge=0, alias=c.SQRL_DATASETS_MAX_ROWS_FOR_AI, 
+        description="Max rows for AI queries"
+    )
+    datasets_max_rows_output: int = Field(
+        100000, ge=0, alias=c.SQRL_DATASETS_MAX_ROWS_OUTPUT, 
+        description="Max rows for dataset output"
+    )
+    datasets_sql_timeout_seconds: float = Field(
+        2.0, gt=0, alias=c.SQRL_DATASETS_SQL_TIMEOUT_SECONDS, 
+        description="Timeout for SQL operations in seconds"
+    )
+
+    # Dashboards Cache
+    dashboards_cache_size: int = Field(
+        128, ge=0, alias=c.SQRL_DASHBOARDS_CACHE_SIZE, 
+        description="Cache size for dashboards"
+    )
+    dashboards_cache_ttl_minutes: float = Field(
+        60, gt=0, alias=c.SQRL_DASHBOARDS_CACHE_TTL_MINUTES, 
+        description="Cache TTL for dashboards in minutes"
+    )
+    
+    # Seeds
+    seeds_infer_schema: bool = Field(
+        True, alias=c.SQRL_SEEDS_INFER_SCHEMA, 
+        description="Whether to infer schema for seeds"
+    )
+    seeds_na_values: list[str] = Field(
+        ["NA"], alias=c.SQRL_SEEDS_NA_VALUES, 
+        description="List of N/A values for seeds"
+    )
+
+    # Connections
+    connections_default_name_used: str = Field(
+        "default", alias=c.SQRL_CONNECTIONS_DEFAULT_NAME_USED, 
+        description="Default connection name to use"
+    )
+
+    # VDL
+    vdl_catalog_db_path: str = Field(
+        "ducklake:{project_path}/target/vdl_catalog.duckdb", alias=c.SQRL_VDL_CATALOG_DB_PATH, 
+        description="Path to the DuckDB catalog database"
+    )
+    vdl_data_path: str = Field(
+        "{project_path}/target/vdl_data/", alias=c.SQRL_VDL_DATA_PATH, 
+        description="Path to the VDL data directory"
+    )
+
+    # Studio
+    studio_base_url: str = Field(
+        "https://squirrels-analytics.github.io/squirrels-studio-v2", alias=c.SQRL_STUDIO_BASE_URL, 
+        description="Base URL for Squirrels Studio"
+    )
+
+    # Logging
+    logging_level: str = Field(
+        "INFO", alias=c.SQRL_LOGGING_LEVEL, 
+        description="Logging level"
+    )
+    logging_format: str = Field(
+        "text", alias=c.SQRL_LOGGING_FORMAT, 
+        description="Logging format"
+    )
+    logging_to_file: bool | str = Field(
+        False, alias=c.SQRL_LOGGING_TO_FILE, 
+        description="Whether to log to file. Can be set to true to use the default 'logs/' folder, or a folder path to write to a custom folder."
+    )
+    logging_file_size_mb: float = Field(
+        50, gt=0, alias=c.SQRL_LOGGING_FILE_SIZE_MB, 
+        description="Max log file size in MB"
+    )
+    logging_file_backup_count: int = Field(
+        1, ge=0, alias=c.SQRL_LOGGING_FILE_BACKUP_COUNT, 
+        description="Number of backup log files to keep"
+    )
+    
+    @field_validator("project_path")
+    @classmethod
+    def validate_project_path_exists(cls, v: str) -> str:
+        """Validate that the project_path is a folder that contains a squirrels.yml file."""
+        path = Path(v)
+        if not path.exists():
+            raise ValueError(f"Project path does not exist: {v}")
+        if not path.is_dir():
+            raise ValueError(f"Project path must be a directory, not a file: {v}")
+        # squirrels_yml = path / c.MANIFEST_FILE
+        # if not squirrels_yml.exists():
+        #     raise ValueError(f"Project path must contain a {c.MANIFEST_FILE} file: {v}")
+        return v
+    
+    @field_validator("auth_credential_origins", mode="before")
+    @classmethod
+    def parse_origins(cls, v: Any) -> list[str]:
+        if isinstance(v, str):
+            res = [x.strip() for x in v.split(",") if x.strip()]
+            return res or ["https://squirrels-analytics.github.io"]
+        return v
+
+    @field_validator("seeds_na_values", mode="before")
+    @classmethod
+    def parse_json_list(cls, v: Any) -> list[str]:
+        if isinstance(v, str):
+            try:
+                parsed = json.loads(v)
+                if not isinstance(parsed, list):
+                    raise ValueError(f"The {c.SQRL_SEEDS_NA_VALUES} environment variable must be a JSON list")
+                return parsed
+            except json.JSONDecodeError:
+                return []
+        return v
+    
+    @field_validator("logging_to_file", mode="before")
+    @classmethod
+    def parse_logging_to_file(cls, v: Any) -> bool | str:
+        if isinstance(v, str):
+            v_lower = v.lower()
+            if v_lower in ("true", "t", "1", "yes", "y", "on"):
+                return True
+            if v_lower in ("false", "f", "0", "no", "n", "off"):
+                return False
+            return v
+        return bool(v)
+
+    @field_validator("seeds_infer_schema", mode="before")
+    @classmethod
+    def parse_bool(cls, v: Any) -> bool:
+        if isinstance(v, str):
+            return v.lower() in ("true", "t", "1", "yes", "y", "on")
+        return bool(v)
+
+    @model_validator(mode="after")
+    def format_paths_with_filepath(self) -> Self:
+        """Format paths containing {filepath} placeholder with the actual filepath value."""
+        self.auth_db_file_path = self.auth_db_file_path.format(project_path=self.project_path)
+        self.vdl_catalog_db_path = self.vdl_catalog_db_path.format(project_path=self.project_path)
+        self.vdl_data_path = self.vdl_data_path.format(project_path=self.project_path)
+        return self
+    

squirrels/_exceptions.py

@@ -0,0 +1,29 @@
+class InvalidInputError(Exception):
+    """
+    Use this exception when the error is due to providing invalid inputs to the REST API
+
+    Attributes:
+        status_code: The HTTP status code to return
+        error: A short error message that should never change in the future
+        error_description: A detailed error message (that is allowed to change in the future)
+    """
+    def __init__(self, status_code: int, error: str, error_description: str, *args) -> None:
+        self.status_code = status_code
+        self.error = error
+        self.error_description = error_description
+        super().__init__(error_description, *args)
+
+
+class ConfigurationError(Exception):
+    """
+    Use this exception when the server error is due to errors in the squirrels project instead of the squirrels framework/library
+    """
+    pass
+
+
+class FileExecutionError(Exception):
+    def __init__(self, message: str, error: Exception, *args) -> None:
+        t = "  "
+        new_message = f"\n" + message + f"\n{t}Produced error message:\n{t}{t}{error} (see above for more details on handled exception)"
+        super().__init__(new_message, *args)
+        self.error = error

squirrels/_http_error_responses.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from ._exceptions import InvalidInputError
+
+
+def _strip_path_suffix_from_base_url(request: Request, *, strip_path_suffix: str | None) -> str:
+    """
+    Return a base URL with a known mount suffix removed.
+
+    In Squirrels, the main app mounts sub-apps like `/api/0` and `/mcp`. When we're
+    handling a request inside those sub-apps, `request.base_url` includes the mount
+    path. For `WWW-Authenticate` we want to point to a top-level endpoint on the main
+    app (same mount as the main app itself), so we strip only the *sub-app mount*
+    suffix (e.g. `/api/0` or `/mcp`), not any outer mount path.
+    """
+    base_url = str(request.base_url).rstrip("/")
+    if strip_path_suffix:
+        suffix = strip_path_suffix.rstrip("/")
+        if suffix and base_url.endswith(suffix):
+            base_url = base_url[: -len(suffix)]
+    return base_url.rstrip("/")
+
+
+def invalid_input_error_to_json_response(
+    request: Request,
+    exc: InvalidInputError,
+    *,
+    oauth_resource_metadata_path: str = "/.well-known/oauth-protected-resource",
+    strip_path_suffix: str | None = None,
+    is_mcp: bool = False,
+) -> JSONResponse:
+    """
+    Convert an InvalidInputError into the standard Squirrels JSON error response.
+
+    For 401s, also sets `WWW-Authenticate` with a top-level `resource_metadata` URL.
+    """
+    response = JSONResponse(
+        status_code=exc.status_code,
+        content={"error": exc.error, "error_description": exc.error_description},
+    )
+
+    if exc.status_code == 401:
+        top_level_base_url = _strip_path_suffix_from_base_url(request, strip_path_suffix=strip_path_suffix)
+        resource_metadata_url = f"{top_level_base_url}{oauth_resource_metadata_path}"
+        realm = "mcp" if is_mcp else "api"
+        response.headers["WWW-Authenticate"] = f'Bearer realm="{realm}", resource_metadata="{resource_metadata_url}"'
+
+    return response
+