Skip to main content

A python module to auto build conversation for a Telegram bot

Project description

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[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.
  • kwargs: kwargs with every parameters you need from Telegram API sendMessage.
# callback handler
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
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
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
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
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
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
add_dynamic_list(function:Callable,start:int=0,left_button:str='<',right_button:str='>',all_elements:bool=False,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.
# custom handler
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)
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.
# get a states by name in the 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
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.

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
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
restart()
# force a state in the conversation
force_state(state:Union[State,str])
  • state: force the conversation to a specific state.

TelegramData Attributes

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

telegram-autoconv-0.0.43.tar.gz (10.0 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page