telegram-autoconv 0.0.51

A python module to auto build conversation for a Telegram bot

Setup

You can find the package, here.

pip3 install telegram-autoconv

Requirements

• Python 3.8
• telegram-python-bot 13

Import

from autoconv.state import State
from autoconv.conversation import Conversation
from autoconv.autoconv_handler import AutoConvHandler

Documentation

I know you want examples, in fact there is a beautiful folder with some examples.
But here, you can find a little documentation.

State

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 for data dictionary).
• state_text: message you want to print in that state.
• data_type: data type, default or 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: kwargs with every parameters you need from Telegram API sendMessage.

# 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 custom value as key) or a list/tuple (default 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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
)

• 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.
• max_row: max number of buttons in a row.
• 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.

# 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.

Conversation

Conversation(
    start_state: State,
    end_state: Optional[State] = None,
    fallback_state: Optional[State] = None
)

• start_state: first state of the conversation.
• end_state: final state of the conversation.
• fallback_state: fallback handler state of the conversation (if defined, the conversation handle an error in this state).

# define the routes for a state in the conversation (automatically added to conversation)
Conversation.add_routes(
    state: State,
    routes: Optional[dict] = None,
    default: Optional[State] = None,
    back: Optional[State] = None
)

• state: initial state of the ruote.
• routes: routes where a state should go for every possibile data received.
• default: default route if value isn't in ruotes.
• back: route to go when the back button is pressed, if exists. If the state isn't specified and the starting state has a back button, it'll go to back the previous state.

# get a states by name in the conversation
Conversation.get_state(
    state_name: str
)

• state_name: a state name to search in the conversation.

# define a list of users able to access this conversation and an optional fallback State
Conversation.add_authorized_users(
    users_list: Sequence[int],
    no_auth_state: State
)

• users_list: list of users (Telegram ID) able to access the conversation.
• no_auth_state: state in which unauthorized users end up.

# Define default values, a function applied to text and a back button for every States in the conversation
Conversation.add_defaults(
    params: Optional[dict] = None,
    function: Optional[Callable] = None,
    back_button: Optional[str] = None,
)

• params: kwargs with every parameters you need from Telegram API sendMessage.
• function: default function applied to every State text.
• back_button: default back button for every State.

AutoConvHandler

AutoConvHandler(
    conversation: Conversation,
    telegram_state_name: Any
)

• conversation: conversation to handle.
• telegram_state_name: Telegram state name to handle callback, text and other things.

# manage conversation with update and context
AutoConvHandler.manage_conversation(
    update: Telegram.Update,
    context: Telegram.Context,
    delete_first: bool = True
)

• update,context: from telegram bot function.
• delete_first: if you want to delete the user message that trigger this handler.

# restart the conversation to initial configuration
AutoConvHandler.restart(
    update: Telegram.Update,
    context: Telegram.Context
)

• update,context: from telegram bot function.

# force a state in the conversation
AutoConvHandler.force_state(
    state: Union[State, str],
    update: Telegram.Update
)

• state: force the conversation to a specific state.
• update: from telegram bot function.

TelegramData Attributes

• update,context: Telegram update and context.
• telegram_id: Telegram ID of the user.
• udata: context.user_data of the user.
• sdata: data for every state of the user.
• message: message info, if possibile, of the user.
• exception: last Python exception occurred.