MateWrapper

This package contains all the basic classes that wrap around the python telegram bot ext package to ease bot development, like handlers, prompts & getters.

bot module

This module contains the base bot wrapper and the defualt error handler.

class MateWrapper.bot.TelegramBot(token: str, error_handler: Optional[Callable[[telegram.update.Update, telegram.ext.callbackcontext.CallbackContext], any]] = None, name: str = '')

class that wraps Updater and Dispatcher in a convenient way

__init__(token: str, error_handler: Optional[Callable[[telegram.update.Update, telegram.ext.callbackcontext.CallbackContext], any]] = None, name: str = '')

Parameters

• token – the token necessary to run the bot, acquired through BotFather.

• error_handler – a custom error handler if you don’t want to use the default one

• name – the name of this bot, currently unused.

MateWrapper.bot.default_error_handler(update: telegram.update.Update, context: telegram.ext.callbackcontext.CallbackContext)

Built in error handler, just sends the given error message to the user if TelegramUserError and logs the Exception while notifying the user if it’s not.

generics module

This module contains stuff that is used all around the wrapper & Chains.

class MateWrapper.generics.Chain(*args: Callable[[telegram.update.Update, telegram.ext.callbackcontext.CallbackContext], object], next_state: Optional[object] = None)

Used to call multiple functions from a single handle, useful to avoid creating custom functions for most interactions with the Bot. Chains can be Nested in other chains to create subroutines.

This class is callable.

__init__(*args: Callable[[telegram.update.Update, telegram.ext.callbackcontext.CallbackContext], object], next_state: Optional[object] = None)

Parameters

• args (Callable[[Update, CallbackContext], object]) – a tuple containing the functions that will be called, starting from the first and finishing with the last, returning the last non-None value if return_value is not defined.

• next_state (object or None) – if defined then the chain will return the given value, if not it will return the last non-None value. By default, it’s not defined, the last non-None value is returned.

class MateWrapper.generics.TelegramEvent(update: telegram.update.Update, context: telegram.ext.callbackcontext.CallbackContext)

A convenient wrapper of received events. Automatically instanced by the wrapper.

__init__(update: telegram.update.Update, context: telegram.ext.callbackcontext.CallbackContext)

Parameters

• update (Update) – The telegram update that caused the event

• context (CallbackContext) – The telegram context tied to the user that caused the event

reply(text: str, **kwargs)

send message to the user that generated this event. Supports all kwargs of send_message.

class MateWrapper.generics.TelegramFunctionBlueprint

The generic Telegram Function class that needs to be implemented.

This class is callable.

logic(event: MateWrapper.generics.TelegramEvent) → object

How this method is implemented determines what the function is going to do. What this method returns defines the next state that the menu needs to be in.

exception MateWrapper.generics.TelegramUserError

This exception is raised if the wrapper detects an error from a user, for example when the validation regex in GetText does not match the input.

It’s handled automatically by the default error handler, but you can implement your own handler.

handlers module

This module contains convenient wrappers for handlers from the basic telegram wrapper.

class MateWrapper.handlers.ButtonHandler(callback: Callable[[telegram.update.Update, telegram.ext.utils.types.CCT], telegram.ext.callbackqueryhandler.RT], pass_update_queue: bool = False, pass_job_queue: bool = False, pattern: Optional[Union[str, Pattern, type, Callable[[object], Optional[bool]]]] = None, pass_groups: bool = False, pass_groupdict: bool = False, pass_user_data: bool = False, pass_chat_data: bool = False, run_async: Union[bool, telegram.utils.helpers.DefaultValue] = False)

Handles Button inputs, it’s just an alias for CallbackQueryHandler

class MateWrapper.handlers.PhotoHandler(callback: callable, **kwargs)

Handles Photo messages, wraps MessageHandler

__init__(callback: callable, **kwargs)

class MateWrapper.handlers.TextHandler(callback: callable, **kwargs)

Handles text messages, wraps MessageHandler

__init__(callback: callable, **kwargs)

prompts module

This module contains all functions & classes related to prompts, the easy way to handle complex responses.

class MateWrapper.prompts.Prompt(text: Union[str, Callable[[MateWrapper.generics.TelegramEvent], str]], keyboard: Optional[Union[telegram.inline.inlinekeyboardmarkup.InlineKeyboardMarkup, Callable[[MateWrapper.generics.TelegramEvent], telegram.inline.inlinekeyboardmarkup.InlineKeyboardMarkup]]] = None, format_text: Optional[bool] = None, next_state: Optional[object] = None, delete_last_message: bool = False, use_markdown: bool = False, use_web_preview: bool = False)

Class to handle sending prompts via Telegram. Automatically optimizes itself depending on the text & keyboard you pass in.

__init__(text: Union[str, Callable[[MateWrapper.generics.TelegramEvent], str]], keyboard: Optional[Union[telegram.inline.inlinekeyboardmarkup.InlineKeyboardMarkup, Callable[[MateWrapper.generics.TelegramEvent], telegram.inline.inlinekeyboardmarkup.InlineKeyboardMarkup]]] = None, format_text: Optional[bool] = None, next_state: Optional[object] = None, delete_last_message: bool = False, use_markdown: bool = False, use_web_preview: bool = False)

Parameters

• text (Union[str, Callable[[TelegramEvent], str]]) – text of the message to send or the function used to generate it. If ‘{something}’ is found in the text then the TelegramWrapper will try to format the text replacing all ‘{something}’ instances with whatever context.chat_data[‘something’] contains see MATEVarHandler for more info on special characters in format string Can be callable, the logic defined above still applies, see the format_text parameter for more info.

• keyboard (Union[InlineKeyboardMarkup, Callable[[TelegramEvent], InlineKeyboardMarkup]]) – the inline keyboard to send or the function that will generate the inline keyboard to send. Leave as None to not send any keyboard.

• format_text (bool or None) – manually set if the text should be formatted, by default the wrapper will automatically determine if the prompt needs to be formatted. It is only taken into account if the text is of type ‘callable’, that is to say if the text is programmatically generated by a function and is not known beforehand by the program.

• next_state (object or None) – the return value of the function, used to change state in conversation handlers. Leave at None to not change state.

• delete_last_message (bool) – if true it will delete either the last message sent by the user or the keyboard that generated the update.

• use_markdown (bool) – tells telegram to format the message using markdown V2. By default it’s false.

• use_web_preview (bool) – tells telegram to render the web preview of the first link found in the message if true. By default it’s false.

logic(event: MateWrapper.generics.TelegramEvent)

How this method is implemented determines what the function is going to do. What this method returns defines the next state that the menu needs to be in.

variables module

This module contains all functions & classes used by the wrapper to access the context. Normally you are not going to touch this module but it’s documented for posterity.

class MateWrapper.variables.GetKeyboardInput(var_name: str, transformation_function: Optional[Callable[[object, MateWrapper.generics.TelegramEvent], object]] = None, next_state: Optional[int] = None, custom_setter_function: Optional[Callable[[object, str], object]] = None)

Gets an input from a keyboard, use in conjunction with ButtonHandler

class MateWrapper.variables.GetPhoto(var_name: str, transformation_function: Optional[Callable[[object, MateWrapper.generics.TelegramEvent], object]] = None, next_state: Optional[int] = None, custom_setter_function: Optional[Callable[[object, str], object]] = None)

Gets a photo from a PhotoMessage, use in conjunction with PhotoHandler

class MateWrapper.variables.GetText(var_name: str, transformation_function: Optional[callable] = None, validation_regex: Optional[str] = None, error_message: Optional[str] = None, next_state: Optional[object] = None, custom_setter_function: Optional[callable] = None)

Gets a text input from the user and optionally validates it, use in conjunction with TextHandler

__init__(var_name: str, transformation_function: Optional[callable] = None, validation_regex: Optional[str] = None, error_message: Optional[str] = None, next_state: Optional[object] = None, custom_setter_function: Optional[callable] = None)

Parameters

• validation_regex (str) – The regular expression used to validate the text input. Leave empty if you don’t want to validate

• error_message (str) – The error message to send the user in case the given input wasn’t validated correctly. Leave empty for a default, generic response

Raises

TelegramUserError – if validation is enabled and the given text doesn’t match the given regex this function will raise a TelegramUserError with the given error_message as error message.

class MateWrapper.variables.GetVariableGeneric(var_name: str, transformation_function: Optional[Callable[[object, MateWrapper.generics.TelegramEvent], object]] = None, next_state: Optional[int] = None, custom_setter_function: Optional[Callable[[object, str], object]] = None)

Generic class to handle getting variables in the wrapper, needs to be implemented

__init__(var_name: str, transformation_function: Optional[Callable[[object, MateWrapper.generics.TelegramEvent], object]] = None, next_state: Optional[int] = None, custom_setter_function: Optional[Callable[[object, str], object]] = None)

Parameters

• var_name (str or None) –

  name of the variable to store, this will be put in context.chat_data

  if you pass None (and return value is None), this handler will just return the retrieved value. Useful in combination with transformation functions to use the gathered data in some way and then throw it away or to create main menus that lead to submenus.

  if you pass something like “dict_name:aaa” then this handler will try to put the received value in dict_name[“aaa”], where dict_name is the context key for the dict and aaa is a parameter of said dict

  if you pass something like “obj_name.var” then this handler will try to put the received value in obj_name.var, where onj_name is the context key for the object and var is a variable of said object

• transformation_function (Union[Callable[[object, TelegramEvent], object], None]) –

  a function that will take the variable and transform it somehow before storing it.

  the function should have 2 inputs and 1 output, like this:

  func(input, event: TelegramEvent):

  return something

• next_state (int or None) – the return value of the function, used to change state in conversation handlers. Leave at None to not change state.

• custom_setter_function (Union[Callable[[object, str], object], None]) –

  a custom setter function useful for interacting with objects outside of the context.

  the function should have 2 inputs and optionally an integer output, like this:

  func(input, var_name: str)

  …

  next_state: int = 1

  return next_state

class MateWrapper.variables.InitDefaultContext(default_context: dict, clear_context: bool = False)

Used to set the given dictionary as the current user’s context.

__init__(default_context: dict, clear_context: bool = False)

Parameters

• default_context (dict) – the desired context

• clear_context (bool) – defines whether the user’s context should be cleared before initializing the new one

logic(event: MateWrapper.generics.TelegramEvent)

How this method is implemented determines what the function is going to do. What this method returns defines the next state that the menu needs to be in.

MateWrapper.variables.clear_vars(update: telegram.update.Update, context: telegram.ext.callbackcontext.CallbackContext)

Used to clear the current user context

globals module

This module contains a bunch of constants & globals used all around the wrapper.

class MateWrapper.globals.Globals

Contains a bunch of useful shortcuts and globals used across the wrapper.

BACK_BUTTON = <telegram.inline.inlinekeyboardbutton.InlineKeyboardButton object>

The default back button used by the wrapper.

BACK_KEYBOARD = <telegram.inline.inlinekeyboardmarkup.InlineKeyboardMarkup object>

A keyboard only containing the back button.

BACK_PATTERN = '__back__'

The callback pattern globally used by the back button, assign this as callback data to a custom button to give it the function of going to the previous panel.

CONVERSATION_END_PROMPT = <MateWrapper.prompts.Prompt object>

The default prompt shown by the wrapper when exiting a menu

END_CONVERSATION = -1

If you assign this as next_state to any function it will close the current menu.

END_HANDLER = <telegram.ext.callbackqueryhandler.CallbackQueryHandler object>

An handler for BACK_PATTERN that will end the conversation (close the menu)

ENTRY_POINT(c)

A placeholder function that does nothing that will be automatically replaced by the wrapper with the prompt associated with the defined main panel.

This process happens at init time so it has no impact on runtime performance.