MateMenus#

This package is an extension to MateWrapper and provides functions & classes useful for easily building complex menu based interfaces. This basically makes MATE it’s own framework.

generics module#

Contains all the generics classes & functions that are implemented all around the package.

class MateMenus.generics.AuthCheck(auth_function: Callable[[MateWrapper.generics.TelegramEvent], bool], error_text: str)[source]#

Configurable function that allows to check for some kind of authentication

__init__(auth_function: Callable[[MateWrapper.generics.TelegramEvent], bool], error_text: str)[source]#

Parameters

auth_function (Callable[[TelegramEvent], bool]) – The function used to authenticate the user; It should return True if the user was authenticated, else False.
error_text (str or None) – The Text the user will be shown if auth_function returns False. By default, it shows “Access denied”.

Returns

None if the authorization was successful

Raise

TelegramUserError if the authorization was not successful.

class MateMenus.generics.Button(text: str, custom_handle: Optional[str] = None)[source]#

generic keyboard button class to implement

__init__(text: str, custom_handle: Optional[str] = None)[source]#

sets the buttons text & generates a unique handle (callback pattern) for this button.

Parameters

text (str) – the text that will be shown on the button (Long texts will be shortened).
custom_handle (str or None) – Sets a custom handle for the button instead of autogenerating it.

compile(context: MateMenus.generics.MenuContext)[source]#

This function should only be called ad init time by a Menu object.

Compiles the button given the menu context, useful if the button needs some context info to function, like for example buttons that change panel need to access the destination panel’s prompt.

By default, it does nothing and isn’t mandatory to implement.

get_handler() → telegram.ext.handler.Handler[source]#: returns this buttons Handlers

get_keyboard_button() → telegram.inline.inlinekeyboardbutton.InlineKeyboardButton[source]#: by default generates the button with its handle as callback data

get_next_state_handlers() → telegram.ext.handler.Handler[source]#: Used mainly by input buttons. If this function returns a Handler or a list of Handlers then it tells the menu that this button spawns a sub-panel with its own handlers that then immediately returns to the current panel.

class MateMenus.generics.GenericPanel[source]#

Panel prototype that needs to be implemented

get_handlers(context: MateMenus.generics.MenuContext) → List[telegram.ext.handler.Handler][source]#: This is used by the menu object to compile panels into handlers.

prompt: MateWrapper.prompts.Prompt#: the prompt to set with set_prompt

set_prompt(current_state: object)[source]#: This sets the prompt tied to the panel that needs to be shown when switching to it.

class MateMenus.generics.Menu(entry_points: List[telegram.ext.handler.Handler], panels: Dict[object, MateMenus.generics.GenericPanel], main_panel: object, fallbacks: List[telegram.ext.handler.Handler])[source]#

A menu, container for one or more (usually more) panels.

At init time it automatically “compiles” the panels into handlers and callback handlers to ensure maximum runtime performance while retaining the simplicity of the wrapper.

__init__(entry_points: List[telegram.ext.handler.Handler], panels: Dict[object, MateMenus.generics.GenericPanel], main_panel: object, fallbacks: List[telegram.ext.handler.Handler])[source]#

Parameters

entry_points – The list of handlers that will activate this menu from the “main” state.
panels – A dictionary containing the name-panel pair.
main_panel – Defines which panel to show when first entering the menu
fallbacks – A list of extra handlers valid in the entire menu, useful for example for commands.

class MateMenus.generics.MenuContext(current_menu: MateMenus.generics.Menu, current_panel: MateMenus.generics.GenericPanel, panels: Dict[object, MateMenus.generics.GenericPanel])[source]#

Private class used by Menus to compile buttons and panels

__init__(current_menu: MateMenus.generics.Menu, current_panel: MateMenus.generics.GenericPanel, panels: Dict[object, MateMenus.generics.GenericPanel])[source]#

MateMenus.generics.get_back_button_handler(current_panel: MateMenus.generics.GenericPanel) → telegram.ext.callbackqueryhandler.CallbackQueryHandler[source]#

returns a Handler for BACK_PATTERN that returns the user to current_panel

Parameters: current_panel (GenericPanel) – the destination panel
Returns: a CallbackQueryHandler for BACK_PATTERN that returns the user to current_panel

buttons module#

Contains all the buttons usable with Panels.

class MateMenus.buttons.FuncButton(text: str, function: callable, custom_handle: Optional[str] = None)[source]#

button that executes a function (or a chain of functions) when clicked

__init__(text: str, function: callable, custom_handle: Optional[str] = None)[source]#

sets the buttons text & generates a unique handle (callback pattern) for this button.

Parameters

text (str) – the text that will be shown on the button (Long texts will be shortened).
custom_handle (str or None) – Sets a custom handle for the button instead of autogenerating it.

get_handler() → telegram.ext.handler.Handler[source]#: returns this buttons Handlers

class MateMenus.buttons.GotoButton(text: str, next_panel: str, custom_handle: Optional[str] = None)[source]#

button that allows for Panel changing

__init__(text: str, next_panel: str, custom_handle: Optional[str] = None)[source]#

sets the buttons text & generates a unique handle (callback pattern) for this button.

Parameters

text (str) – the text that will be shown on the button (Long texts will be shortened).
custom_handle (str or None) – Sets a custom handle for the button instead of autogenerating it.

compile(context: MateMenus.generics.MenuContext)[source]#

This function should only be called ad init time by a Menu object.

Compiles the button given the menu context, useful if the button needs some context info to function, like for example buttons that change panel need to access the destination panel’s prompt.

By default, it does nothing and isn’t mandatory to implement.

get_handler() → telegram.ext.handler.Handler[source]#: returns this buttons Handlers

class MateMenus.buttons.InputButton(text: str, prompt: MateWrapper.prompts.Prompt, input_handlers: telegram.ext.handler.Handler, custom_handle: Optional[str] = None)[source]#

button that makes getting inputs from users a lot easier by automating callback and state handling.

__init__(text: str, prompt: MateWrapper.prompts.Prompt, input_handlers: telegram.ext.handler.Handler, custom_handle: Optional[str] = None)[source]#

Parameters

(str) (text) – The text that will be shown in the button
(Prompt) (prompt) – The prompt that will be shown when acquiring the input from the user
List[Handler]) (input_handle (Handler or) – The function(s) that will be used to handle the user’s input

compile(context: MateMenus.generics.MenuContext)[source]#

This function should only be called ad init time by a Menu object.

Compiles the button given the menu context, useful if the button needs some context info to function, like for example buttons that change panel need to access the destination panel’s prompt.

By default, it does nothing and isn’t mandatory to implement.

get_handler() → telegram.ext.handler.Handler[source]#: returns this buttons Handlers

get_next_state_handlers() → List[telegram.ext.handler.Handler][source]#: Used mainly by input buttons. If this function returns a Handler or a list of Handlers then it tells the menu that this button spawns a sub-panel with its own handlers that then immediately returns to the current panel.

class MateMenus.buttons.UrlButton(text: str, url: str)[source]#

button that redirects the user to the specified url when clicked

__init__(text: str, url: str)[source]#

sets the buttons text & generates a unique handle (callback pattern) for this button.

Parameters

text (str) – the text that will be shown on the button (Long texts will be shortened).
custom_handle (str or None) – Sets a custom handle for the button instead of autogenerating it.

get_keyboard_button() → telegram.inline.inlinekeyboardbutton.InlineKeyboardButton[source]#: by default generates the button with its handle as callback data

panels module#

Contains all the implementations of GenericPanel.

class MateMenus.panels.CustomPanel(prompt: MateWrapper.prompts.Prompt, handlers: List[telegram.ext.handler.Handler], auto_handle_state: bool = True)[source]#

An extremely simple implementation of a Panel, useful for building very dynamic apps

__init__(prompt: MateWrapper.prompts.Prompt, handlers: List[telegram.ext.handler.Handler], auto_handle_state: bool = True)[source]#

Parameters

prompt – The prompt that will be shown by this panel
handlers – The list of handlers tied to this panel
auto_handle_state – Define if the prompt’s state will be automatically handled by the wrapper.

get_handlers(context: MateMenus.generics.MenuContext) → List[telegram.ext.handler.Handler][source]#: This is used by the menu object to compile panels into handlers.

set_prompt(current_state: object)[source]#: This sets the prompt tied to the panel that needs to be shown when switching to it.

class MateMenus.panels.GOTO(destination_panel: str)[source]#

Compiles to the prompt of the panel given as destination_panel, useful for Changing Panel in a custom Panel

__init__(destination_panel: str)[source]#

class MateMenus.panels.Panel(prompt_text: Union[str, Callable[[MateWrapper.generics.TelegramEvent], str]], buttons: List[Union[MateMenus.generics.Button, List[MateMenus.generics.Button]]], back_to: str, extra_handlers: Optional[List[telegram.ext.handler.Handler]] = None)[source]#

A complex implementation of a Panel that automatically handles callbacks & states

__init__(prompt_text: Union[str, Callable[[MateWrapper.generics.TelegramEvent], str]], buttons: List[Union[MateMenus.generics.Button, List[MateMenus.generics.Button]]], back_to: str, extra_handlers: Optional[List[telegram.ext.handler.Handler]] = None)[source]#

Parameters

prompt_text (Union[str, Callable[[TelegramEvent], str]]) – The text that will be sent when this panel is shown, supports all the same formatting options as the Panel object. Can be callable.
buttons (List[Union[Button, List[Button]]]) – The list of Button objects (or of List[Button]) that will define the functionality of this panel.
back_to (str) – The name of the Panel to go back to. If “__end__” the back button will close the menu.
extra_handlers (List[Handler] or None) – A list of extra handlers that can do extra stuff, like read text inputs and stuff like that.

get_handlers(context: MateMenus.generics.MenuContext) → List[telegram.ext.handler.Handler][source]#: returns a dictionary used to extend the main menu dictionary

set_prompt(current_state: object)[source]#: Generates the Prompt, call this before compiling handlers

panel_decorators module#

Defines some classes that can be used to wrap panels in order to add functionality in a convenient way.

class MateMenus.panel_decorators.Auth(wrapped_panel: MateMenus.generics.GenericPanel, auth_function: Callable[[MateWrapper.generics.TelegramEvent], bool], error_text: Optional[MateWrapper.prompts.Prompt] = None)[source]#

A ready-made wrapper of GenericPanel useful for building panels that require some kind of authentication to access.

__init__(wrapped_panel: MateMenus.generics.GenericPanel, auth_function: Callable[[MateWrapper.generics.TelegramEvent], bool], error_text: Optional[MateWrapper.prompts.Prompt] = None)[source]#

Parameters

wrapped_panel (GenericPanel) – the panel wrapped by this class.
auth_function (Callable[[TelegramEvent], bool]) – see AuthCheck.
error_text (str or None) – see AuthCheck.

class MateMenus.panel_decorators.Decorated(wrapped_panel: MateMenus.generics.GenericPanel, function: Callable[[telegram.update.Update, telegram.ext.callbackcontext.CallbackContext], object], mode: int = 0)[source]#

A Wrapper of GenericPanel that adds the passed function to the start/end of every function in wrapped_panel.

__init__(wrapped_panel: MateMenus.generics.GenericPanel, function: Callable[[telegram.update.Update, telegram.ext.callbackcontext.CallbackContext], object], mode: int = 0)[source]#

Parameters

wrapped_panel (GenericPanel) – the panel wrapped by this class.
function (Callable[[TelegramEvent], object]) – The function that will be executed first/last by every handler in wrapped_panel.
mode (int) – if 0, function will be added before every other function. if 1, function will be added after every other function. By default, it’s 0.

get_handlers(context: MateMenus.generics.MenuContext) → List[telegram.ext.handler.Handler][source]#: This is used by the menu object to compile panels into handlers.

set_prompt(current_state: object)[source]#: This sets the prompt tied to the panel that needs to be shown when switching to it.

keyboards module#

Contains functions useful for generation keyboards from data.

MateMenus.keyboards.get_keyboard_from_list(input_list: List[MateMenus.keyboards.T], pre_keyboard: Optional[List[List[telegram.inline.inlinekeyboardbutton.InlineKeyboardButton]]] = None, post_keyboard: Optional[List[List[telegram.inline.inlinekeyboardbutton.InlineKeyboardButton]]] = None, custom_text_generator: Optional[Callable[[MateMenus.keyboards.T], str]] = None, custom_data_generator: Optional[Callable[[MateMenus.keyboards.T], str]] = None, add_back_button: bool = False, custom_back_text: Optional[str] = None, buttons_per_line: int = 1, urls: bool = False) → telegram.inline.inlinekeyboardmarkup.InlineKeyboardMarkup[source]#

Generates a keyboard from a list of objects (that can be stringified).

Parameters

input_list (List[T]) – the list you wish to transform into a keyboard.
pre_keyboard (Union[List[List[InlineKeyboardButton]], None]) – if passed all new buttons will be appended to this base keyboard.
post_keyboard (Union[List[List[InlineKeyboardButton]], None]) – if passed this keyboard will be appended to the generated keyboard.
custom_text_generator (Union[Callable[[T], str], None]) – the function that should be used to generate the text of the button, if not defined it will just do str(element).
custom_data_generator (Union[Callable[[T], str], None]) – the function that should be used to generate the callback data (or the url, if the function is set to generate a url keyboard) of the button.
add_back_button (bool) – if true automatically adds a back button at the bottom of the keyboard.
custom_back_text (str or None) – if set changes the back button’s text.
buttons_per_line (int) – defines the maximum amount of buttons that will be in each line.
urls (bool) – Defines if the data of the buttons should be callback data (default behaviour) or urls.

Returns

InlineKeyboardMarkup

MateMenus.keyboards.get_keyboard_from_list_custom_row(input_list: List[MateMenus.keyboards.T], row_generator_function: Callable[[MateMenus.keyboards.T], List[telegram.inline.inlinekeyboardbutton.InlineKeyboardButton]], pre_keyboard: Optional[List[List[telegram.inline.inlinekeyboardbutton.InlineKeyboardButton]]] = None, post_keyboard: Optional[List[List[telegram.inline.inlinekeyboardbutton.InlineKeyboardButton]]] = None, add_back_button: bool = False, custom_back_text: Optional[str] = None) → telegram.inline.inlinekeyboardmarkup.InlineKeyboardMarkup[source]#

Generates a custom keyboard from a given list and a given row_generator_function.

Parameters

input_list (List[T]) – the list you wish to transform into a keyboard.
row_generator_function (Callable[[T], List[InlineKeyboardButton]]) – The function to use to generate a row of the keyboard given an element of the list.
pre_keyboard (Union[List[List[InlineKeyboardButton]], None]) – if passed all new buttons will be appended to this base keyboard.
post_keyboard (Union[List[List[InlineKeyboardButton]], None]) – if passed this keyboard will be appended to the generated keyboard.
add_back_button (bool) – if true automatically adds a back button at the bottom of the keyboard.
custom_back_text (str or None) – if set changes the back button’s text.

Returns

InlineKeyboardMarkup