TextValue

Wrapper class for raw text entered into TextParameter widgets. It is returned by methods such as TextParameter.get_entered_text() so that the text cannot be accidentally treated as a plain string (for example, when building SQL). Instead of converting a TextValue directly to a string, you transform it using helper methods or pass it to APIs such as ContextArgs.set_placeholder, which safely unwrap the underlying text. Instances of TextValue are created by Squirrels and returned from parameter methods; you should not instantiate this class directly in your project code. If TextValue is needed for type annotation, it can be imported from the squirrels.types or squirrels module.

Methods

apply()

Transforms the entered text using a function that takes a string and returns a string, and returns a new TextValue.

def apply(self, str_to_str_function: Callable[[str], str]) -> "TextValue":

Hide arguments

Callable[[str], str]

required

Function that receives the raw text and returns a transformed string.

TextValue

A new TextValue with the transformed text.

If the function does not return a string, a configuration error is raised.

apply_percent_wrap()

Returns a new TextValue with percent signs added before and after the entered text (for example, for use in SQL LIKE patterns).

def apply_percent_wrap(self) -> "TextValue":

TextValue

A new TextValue with percent signs wrapping the text.

apply_as_bool()

Transforms the entered text with a function that takes a string and returns a boolean.

def apply_as_bool(self, str_to_bool_function: Callable[[str], bool]) -> bool:

Hide arguments

Callable[[str], bool]

required

Function that receives the raw text and returns a boolean.

bool

The boolean result from the input function.

If the function does not return a boolean, a configuration error is raised.

apply_as_number()

Transforms the entered text with a function that takes a string and returns a number.

def apply_as_number(
    self, str_to_num_function: Callable[[str], int | float]
) -> int | float:

Hide arguments

Callable[[str], int | float]

required

Function that receives the raw text and returns an int or float.

int | float

The numeric result from the input function.

If the function does not return a number, a configuration error is raised.

apply_as_datetime()

Transforms the entered text with a function that takes a string and returns a datetime object.

def apply_as_datetime(
    self, str_to_datetime_function: Callable[[str], datetime]
) -> datetime:

Hide arguments

Callable[[str], datetime]

required

Function that receives the raw text and returns a datetime.

datetime

The datetime result from the input function.

If the function does not return a datetime, a configuration error is raised.

Examples

The TextValue class is primarily used as a type hint in pyconfigs/context.py. You receive TextValue instances from methods like TextParameter.get_entered_text(), then transform them using the provided methods before passing to APIs that safely handle the text.

Using TextValue as a type hint in context.py

from typing import Any, TYPE_CHECKING
from squirrels import arguments as args, parameters as p

if TYPE_CHECKING:
    from squirrels.types import TextValue

def main(ctx: dict[str, Any], sqrl: args.ContextArgs) -> None:
    if sqrl.param_exists("my_text_param"):
        my_text_param = sqrl.prms["my_text_param"]
        assert isinstance(my_text_param, p.TextParameter)
        
        # Get text parameter value as TextValue
        text_value: "TextValue" = my_text_param.get_entered_text()
        
        # Wrap with % for SQL LIKE pattern matching
        search_pattern = text_value.apply_percent_wrap()
        sqrl.set_placeholder("search_pattern", search_pattern)

Transforming text

new_text_value: "TextValue" = text_value.apply(lambda s: s.strip().upper())

Converting text to other types

from datetime import datetime

# Convert TextValue to float
new_float_value: float = text_value.apply_as_number(
    lambda s: float(s.replace(",", ""))
)

# Convert TextValue to datetime
new_datetime_value: datetime = text_value.apply_as_datetime(
    lambda s: datetime.strptime(s, "%Y/%m/%d")
)

arguments

auth

connections

parameters

parameter_options

data_sources

dashboards

types

Methods

apply()

apply_percent_wrap()

apply_as_bool()

apply_as_number()

apply_as_datetime()

Examples

Using TextValue as a type hint in context.py

Transforming text

Converting text to other types

​Methods

​apply()

​apply_percent_wrap()

​apply_as_bool()

​apply_as_number()

​apply_as_datetime()

​Examples

​Using TextValue as a type hint in context.py

​Transforming text

​Converting text to other types

Methods

apply()

apply_percent_wrap()

apply_as_bool()

apply_as_number()

apply_as_datetime()

Examples

Using TextValue as a type hint in context.py

Transforming text

Converting text to other types