Skip to main content
Class for creating single-select dropdown parameter widgets that allow users to choose one option from a list. This class can be imported from the squirrels.parameters or the squirrels module.

​
Factory methods

Factory methods are class methods that create and configure parameter instances. These methods are typically used in the pyconfigs/parameters.py file to create the parameter configurations (which describes the “shape” of the parameter but does not include the realtime user selections).

​
create_simple()

Decorator for creating a simple parameter from a function that returns select options. The decorated function must return a list of SelectParameterOption objects. 
@classmethod
def create_simple(
    cls, name: str, label: str, 
    *, description: str = ""
) -> Callable:

​
create_with_options()

Decorator for creating a parameter with options that can vary based on user attributes or parent parameter selections. The decorated function must return a list of SelectParameterOption objects. This is functionally equivalent to create_simple but with additional arguments available for user_attribute and parent_name. 
@classmethod
def create_with_options(
    cls, name: str, label: str, 
    *, description: str = "", user_attribute: str | None = None, 
    parent_name: str | None = None
) -> Callable:

​
create_from_source()

Decorator for creating a parameter populated from a database table or query using a SelectDataSource. The decorated function must return a SelectDataSource object. 
@classmethod
def create_from_source(
    cls, name: str, label: str, 
    *, description: str = "", user_attribute: str | None = None, 
    parent_name: str | None = None
) -> Callable:

​
Instance methods

Instance methods are available on parameter instances at query time (in context.py or data models) to retrieve selected values.

​
get_selected() -> SelectParameterOption

Gets the selected SelectParameterOption object. 
def get_selected(self) -> SelectParameterOption:
​
returns
SelectParameterOption | None
The selected SelectParameterOption object (or None if the parameter has no selectable options).

​
get_selected() -> Any | None

Gets the custom field from the selected option. 
def get_selected(
    self, field: str, 
    *, default_field: str | None = None, default: Any | None = None
) -> Any | None:
​
returns
Any | None
The custom field value, or None if either:
  • the field does not exist and no default is provided, or
  • the parameter has no selectable options.

​
get_selected_id()

Gets the ID of the selected option. 
def get_selected_id(self) -> str | None:
​
returns
str | None
The ID string of the selected option (or None if the parameter has no selectable options).

​
is_enabled()

Returns whether the parameter is enabled. A parameter is enabled if it has at least one selectable option. 
def is_enabled(self) -> bool:
​
returns
bool
True if the parameter has at least one selectable option, False otherwise.

​
Examples for factory methods

All examples below are defined in the pyconfigs/parameters.py file.

​
Using create_simple for basic dropdowns

For parameters that don’t need user-specific or parent-dependent options, you can use create_simple. 
from squirrels import parameters as p, parameter_options as po

@p.SingleSelectParameter.create_simple(
    name="time_period", 
    label="Time Period",
    description="Select reporting period"
)
def time_period_options() -> list[po.SelectParameterOption]:
    return [
        po.SelectParameterOption(id="today", label="Today"),
        po.SelectParameterOption(id="week", label="This Week", is_default=True),
        po.SelectParameterOption(id="month", label="This Month"),
        po.SelectParameterOption(id="year", label="This Year"),
    ]

​
Cascading dropdowns with parent-child relationship

This example shows how to create dependent dropdowns where the child options change based on the parent selection. 
from squirrels import parameters as p, parameter_options as po

# Parent parameter
@p.SingleSelectParameter.create_with_options(
    name="country", 
    label="Country",
    description="Country to filter by"
)
def country_options():
    return [
        po.SelectParameterOption(id="usa", label="United States", is_default=True),
        po.SelectParameterOption(id="canada", label="Canada"),
    ]

# Child parameter with cascading options
@p.SingleSelectParameter.create_with_options(
    name="city", 
    label="City",
    description="City to filter by",
    parent_name="country"
)
def city_options():
    return [
        po.SelectParameterOption(
            id="new-york", 
            label="New York",
            parent_option_ids="usa"
        ),
        po.SelectParameterOption(
            id="toronto", 
            label="Toronto",
            parent_option_ids="canada"
        ),
    ]

​
User-specific options

This example restricts certain options based on user access levels. 
from squirrels import parameters as p, parameter_options as po

@p.SingleSelectParameter.create_with_options(
    name="report_type", 
    label="Report Type",
    description="Type of report to generate",
    user_attribute="access_level"
)
def report_type_options():
    return [
        po.SelectParameterOption(
            id="basic_report", 
            label="Basic Report",
            is_default=True,
            user_groups=["admin", "member", "guest"]
        ),
        po.SelectParameterOption(
            id="detailed_report", 
            label="Detailed Report",
            user_groups=["admin", "member"]
        ),
        po.SelectParameterOption(
            id="financial_report", 
            label="Financial Report (Admin Only)",
            user_groups=["admin"]
        ),
    ]
If custom user fields are defined in pyconfigs/user.py, then they can be used to restrict visibility of parameter options as well. To do so, the user_attribute argument must be prefixed with custom_fields.. 
from squirrels import parameters as p, parameter_options as po

@p.SingleSelectParameter.create_with_options(
    name="report_type", 
    label="Report Type",
    description="Type of report to generate",
    user_attribute="custom_fields.role"
)
def report_type_options():
    return [
        po.SelectParameterOption(
            id="basic_report", 
            label="Basic Report",
            user_groups=["manager", "staff"]
        ),
        po.SelectParameterOption(
            id="detailed_report", 
            label="Detailed Report",
            user_groups=["manager"]
        ),
    ]

​
Single-select from database source

This example populates dropdown options from a database table. 
from squirrels import parameters as p, data_sources as ds

@p.SingleSelectParameter.create_from_source(
    name="product_category", 
    label="Product Category",
    description="Select a product category"
)
def product_category_source() -> ds.SelectDataSource:
    return ds.SelectDataSource(
        table_or_query="""
            SELECT 
                category_id AS id,
                category_name AS name,
                sort_order
            FROM product_categories
            WHERE is_active = 1
        """,
        id_col="id",
        options_col="name",
        order_by_col="sort_order"
    )

​
Cascading dropdown from database with parent

This example shows cascading from a database where products depend on the selected category. 
from squirrels import parameters as p, data_sources as ds

@p.SingleSelectParameter.create_from_source(
    name="product", 
    label="Product",
    description="Select a product from the chosen category",
    parent_name="product_category"
)
def product_source():
    return ds.SelectDataSource(
        table_or_query="""
            SELECT 
                product_id,
                product_name,
                category_id
            FROM products
            WHERE is_active = 1
            ORDER BY product_name
        """,
        id_col="product_id",
        options_col="product_name",
        parent_id_col="category_id"
    )

​
Examples for instance methods

Once parameters are configured, you can use instance methods in your models to access the selected values. The parameter instances are available through the context object (e.g., sqrl.prms).

​
Basic usage in context.py

from squirrels import ContextArgs

def main(ctx: dict[str, Any], sqrl: ContextArgs) -> None:
    if sqrl.param_exists("region"):
        region_param = sqrl.prms["region"]
        assert isinstance(region_param, p.SingleSelectParameter)
        ctx["region_id"] = region_param.get_selected_id()

​
Basic usage in Jinja SQL models

The following example works but is not recommended. See tip below for why. 
-- models/federates/filtered_sales.sql
SELECT *
FROM sales
WHERE region = {{ prms["region"].get_selected_id() | quote }}
It is generally better to only use the instance methods in context.py to transform parameter selections into context variables. Using the instance methods directly in the data models is not recommended.IDEs can provide code suggestions for the available instance methods in Python instead of having to memorize which method (such as get_selected_id) is available to use for SingleSelectParameter objects.

​
Accessing custom fields

Suppose you define a single-select parameter with custom fields as such: 
# In pyconfigs/parameters.py
@p.SingleSelectParameter.create_with_options(
    name="report_template", 
    label="Report Template"
)
def report_template_options():
    return [
        po.SelectParameterOption(
            id="summary", 
            label="Summary",
            table_name="sales_summary"
        ),
        po.SelectParameterOption(
            id="detail", 
            label="Detail",
            table_name="sales_detail"
        ),
    ]
Then you can access the custom field in context.py as follows: 
# In context.py
def main(ctx: dict[str, Any], sqrl: ContextArgs) -> None:
    if sqrl.param_exists("report_template"):
        report_template_param = sqrl.prms["report_template"]
        assert isinstance(report_template_param, p.SingleSelectParameter)

        table_name = report_template_param.get_selected("table_name")
        ctx["report_template_table"] = table_name