State

Overview

State is the first element you will need to build a conversation. Think about a FSM, this is a state of it.
In every State you can do different thing, like how the user will interact with it (with a keyboard or text) or what under the hood the State must do.

Basic

In a State you have a keyboard (will result in a grid of button) and an action (what to do in this State).
You can also define a dynamic keyboard (different keyboard in a single State, based on what you want) or a custom keyboard (for advanced user).
In alternative, you can set a text handler in the State, if you want the user to write (or a custom handler for video, photo, ...)

Dynamic

When a State has different dynamic elements to compute, it will compute them when its state is reached.
Following, the order in which all the dynamic elements are computed:

1. action: function of add_action
2. text: function of add_dynamic_text
3. routes: function of add_dynamic_routes
4. keyboard: function of add_dynamic_keyboard
5. list: function of add_dynamic_list
6. auth: function of add_refresh_auth

The custom keybord overrides the dynamic keyboard (if both are specified) and it's in the same order position.

Doc

State(
    state_name: str,
    state_text: str = "@@@",
    data_type: Callable = int,
    back_button: Optional[Union[bool, str]] = None,
    **kwargs
)

• state_name: state name (and key in user_data.data dictionary).
• state_text: text to send in the message.
• data_type: data type, can be custom.
• back_button: text for back button. False if you have a default button (defined in the Conversation) and you don't want it in this State.
• kwargs: parameters you need from Telegram API sendMessage.

Add Keyboard

Usage example: keyboards.py

# callback handler
State.add_keyboard(
    keyboard: Union[Sequence[str],Mapping[int, str]],
    size: Optional[Sequence[int]] = None,
    max_row: int = 3
)

• keyboard: inline keyboard. Can be a dict (with different int as key) or a list/tuple (default increasing int value as key).
• size: size for each row of the keyboard.
• max_row: max number of buttons in a row, ignored if size is specified.

Add Text

Usage example: actions.py

# text handler
State.add_text(
    regex: str = r'^.*$',
    error_message: Optional[str] = None
)

• regex: regex for input text.
• error_message: error message when regex fails.

Add Dynamic Text

Usage example: actions.py

# function to create custom regex and error message
State.add_dynamic_text(
    function: Callable
)

• function: function must take one parameter (TelegramData object). It must return a regex (optional with None) and a message (optional with None), this function need to be exhaustive in order to work (defined for every case). Called when its state is reached.

Add Action

Usage example: actions.py

# function to execute in this state
State.add_action(
    function: Callable
)

• function: function must take one parameter (TelegramData object). It can return a str, repleacing 3 @ (@@@) in the message. Called when its state is reached.

Add Dynamic Keyboard

Usage example: keyboards.py

# function to create dynamic keyboard
State.add_dynamic_keyboard(
    function: Callable,
    max_row: int = 3
)

• function: function must take one parameter (TelegramData object). It must return a keyboard. Called when its state is reached.
• max_row: max number of buttons in a row.

Add Custom Keyboard

Usage example: keyboards.py

# function to create custom keyboard
State.add_custom_keyboard(
    function: Callable
)

• function: function must take one parameter (TelegramData object). It must return a list of InlineKeyboardButton. Called when its state is reached and it override the dynamic keyboard.

Add Dynamic Routes

Usage example: keyboards.py

# function to create dynamic routes
State.add_dynamic_routes(
    function: Callable
)

• function: function must take one parameter (TelegramData object). It must return a triplet (routes,default,back) [see Conversation.add_routes() to better understanding]. Suggested to use in combo with dynamic keyboard. Called when its state is reached.

Add Dynamic List

Usage example: dynamic_list.py

# function to create dynamic list
State.add_dynamic_list(
    function: Callable,
    start: int = 0,
    left_button: str = '<',
    right_button: str = '>',
    all_elements: bool = False,
    labels: Optional[Callable] = None,
    max_row: int = 4,
    preserve_index: bool = False,
)

• function: function must take one parameter (TelegramData object). It must return a list of element. Called when its state is reached.
• start: starting position in the list.
• left_button,right_button: button labels to move in the list.
• all_elements: if you want to have all the elements in the list as buttons.
• labels: function must take one parameter (TelegramData object). Combined with all_elements = True, it must return a list of string in order to change buttons labels. Called when its state is reached.
• max_row: max number of buttons in a row.
• preserve_index: store the last index of the dynamic list, if the state is reached again, it will start from that index. Basically, a dynamic start.

You can access the list in the TelegramData.udata, you can find useful attributes:

• list: the list itself.
• list_i: current index of the list.
• list_el: current element (equals to list[list_i]).

Add Custom Handler

Usage example: handlers.py

# function to create a custom handler
State.add_custom_handler(
    handler: Callable,
    error_message: Optional[str] = None
)

• handler: function must take one parameter (TelegramData object). It must return an hashable value used to get to next state (by routes) or None if the handler fails.
• error_message: error message when handler fails.

Set Long Task

Usage example: actions.py

# function to set a long task
State.set_long_task(
    text: str
)

• text: text for a message that will be sent before the main one (for long task).

Add Refresh Auth

Usage example: authorization.py

# function that return a new list of authorized users
State.add_refresh_auth(
    func: Callable
)

• func: function must take one parameter (TelegramData object). It must return a list of Telegram ids. Called when its state is reached.

Add Operation Buttons

Usage example: keyboards.py

# Add functions for keyboard buttons, performed without changing the state
State.add_operation_buttons(
        operations: Union[Sequence[Callable], Mapping[int, Callable]]
    ):

• operations: functions called in the State when the button is pressed. The state remain the same. Indexes in the dictionary refer to buttons position.