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
: total values 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 have two parameters (update
andcontext
). It can return astr
, 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 have two parameters (update
andcontext
). It must return a keyboard. Called when its state is reached.max_row
: total values in a row, as non dynamic method.
# function to create custom keyboard
add_custom_keyboard(function:Callable)
function
: function must have two parameters (update
andcontext
). 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 have two parameters (update
andcontext
). 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)
function
: function must have two parameters (update
andcontext
). 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.
# custom handler
add_custom_handler(handler:Callable,error_message:Optional[str]=None)
handler
: function must have two parameters (update
andcontext
). 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.
# add extra states to the conversation
add_states(states:Union[Sequence[State],State])
state
: Add a state or a list/set of state to the conversation.
# get a states by name in the conversation
get_state(state_name:str)
state_name
: a state name to search in the conversation.
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()
# restart the conversation to initial configuration
force_state(state:State)
state
: force the conversation to this state.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.