Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pysquirrels.com/llms.txt

Use this file to discover all available pages before exploring further.

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":
​
returns
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":
​
returns
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:
​
returns
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:
​
returns
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:
​
returns
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")
)