diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 4afa081..447c77c 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,7 +1,7 @@ version: 2 updates: - package-ecosystem: "pip" - directory: "/" # Location of package manifests + directory: "/" schedule: interval: "daily" assignees: diff --git a/CHANGELOG.md b/CHANGELOG.md index cd81b47..7270aea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ ### Documentation + - Add docstrings to `BaseMenu` - Add issue templates ([64c006258e373a97d0a9f83318af02c4310b585b](https://github.com/hearot/pyrubrum/commit/64c006258e373a97d0a9f83318af02c4310b585b)) - Add the official pronunciation for Pyrubrum ([b6d1fe8e01f79007338cd4a6dfe409c406c12cba](https://github.com/hearot/pyrubrum/commit/b6d1fe8e01f79007338cd4a6dfe409c406c12cba)) - Delete duplicate issue templates ([10cba65c31a5c3556b39cc328d097b62dfbd5e1b](https://github.com/hearot/pyrubrum/commit/10cba65c31a5c3556b39cc328d097b62dfbd5e1b)) @@ -24,7 +25,7 @@ - Add space before reference links ([dfbf7a55f3a7de666703b1dced404d1ce7b0ee7a](https://github.com/hearot/pyrubrum/commit/dfbf7a55f3a7de666703b1dced404d1ce7b0ee7a)) - Capitalize only the first character of a commit message ([2996f7c91723902b4e998fb94b6d31c60685d386](https://github.com/hearot/pyrubrum/commit/2996f7c91723902b4e998fb94b6d31c60685d386)) - Do no more raise `TypeError` while formatting commits ([56f1e533c12bdf75e63714d125319bb72da7d916](https://github.com/hearot/pyrubrum/commit/56f1e533c12bdf75e63714d125319bb72da7d916)) - - Fix `commit-message` for Dependabot + - Fix `commit-message` for Dependabot ([a13cfeae848d83339a902373ddcb0287fc306d87](https://github.com/hearot/pyrubrum/commit/a13cfeae848d83339a902373ddcb0287fc306d87)) - Hide the sha-1 hash of the current commit ([ab6478e610ef828744d5c6e54a1d54fff92372e8](https://github.com/hearot/pyrubrum/commit/ab6478e610ef828744d5c6e54a1d54fff92372e8)) ### New features diff --git a/pyrubrum/base_menu.py b/pyrubrum/base_menu.py index 6f6dfe9..ffa6a5c 100644 --- a/pyrubrum/base_menu.py +++ b/pyrubrum/base_menu.py @@ -35,38 +35,110 @@ @dataclass(eq=False, init=False, repr=True) class BaseMenu(ABC): + """Basic represention of a menu, which is an entity that has got by definition + a name and a unique identifier. + + The purpose of this class is to give a general interface for a menu, as it + doesn't implement anything except for the generation of both buttons and + hashes. + + A sample implementation of this interface is `Menu`. + + Attributes: + name (str): The name you give to the menu, which will be used as the + text of callback button, if needed. + menu_id (str): The unique identifier given to the menu, which will + refer unequivocally to this entity. The hash for this class is + generated relying on the content of this field. + + Note: + In order to create a subclass or to access this interface, you will + need to implement all the defined abstract methods, which are + `get_content`, `keyboard, `on_callback`, `on_message`. Otherwise, you + will get an error. + + Warning: + Avoid using the same identifier for other entities, as it will result + in ambiguity. + """ + name: str menu_id: str - def __hash__(self): + def __hash__(self) -> int: + """The hash generator of a menu, relying on the unique identifier + (`menu_id`) which is assigned to it. + + Returns: + int: The unique hash which is generated for this entity. + """ return hash(self.menu_id) def __init__(self, name: str, menu_id: str): + """Initialize the class with a custom name and unique identifier. + + Args: + name (str): The name you give to the menu, which will be used as + the text of callback button, if needed. + menu_id (str): The unique identifier given to the menu, which will + refer unequivocally to this entity. The hash for this class is + generated relying on the content of this field. + """ self.name = name self.menu_id = menu_id - @abstractmethod - def get_content(self) -> Union[InputMedia, str]: - raise NotImplementedError - - @abstractmethod - def on_callback( + def button( self, handler: BaseHandler, client: Client, - callback: CallbackQuery, + context: Union[CallbackQuery, Message], parameters: Dict[str, Any], - ): - raise NotImplementedError + ) -> Button: + """Create an inline button which refers to this menu, using `name` as + the content of the text field and `menu_id` as the unique identifier + of the `Button` object. - def button( + Args: + handler (BaseHandler): The handler which coordinates the management + of the menus. + client (Client): The client which is linked to the handler. + context (Union[CallbackQuery, Message]): The context which the + button is generated for. + parameters (Dict[str, Any]): The parameters which were passed to + the handler. + + Returns: + Button: The generated button. + """ + return Button(self.name, self.menu_id, parameters) + + @abstractmethod + def get_content( self, handler: BaseHandler, client: Client, context: Union[CallbackQuery, Message], parameters: Dict[str, Any], - ) -> Button: - return Button(self.name, self.menu_id, parameters) + ) -> Union[InputMedia, str]: + """This abstract method is intended to be implemented as a generator + for the content of the menu (i.e. what the user will see after clicking + on the inline button or referencing to the menu using a bot command). + + Args: + handler (BaseHandler): The handler which coordinates the management + of the menus. + client (Client): The client which is linked to the handler. + context (Union[CallbackQuery, Message]): The context which the + button is generated for. + parameters (Dict[str, Any]): The parameters which were passed to + the handler. + + Returns: + Union[InputMedia, str]: The content of the menu, which is then + displayed to the user as a media (if it is a subclass of + `InputMedia`) or a message (if it is just a string). + """ + raise NotImplementedError @abstractmethod def keyboard( @@ -76,6 +148,44 @@ def keyboard( context: Union[CallbackQuery, Message], parameters: Dict[str, Any], ) -> InlineKeyboardMarkup: + """This abstract method is intended to be implemented as a generator + for the keyboard of the menu (aka the inline keyboard). + + Args: + handler (BaseHandler): The handler which coordinates the management + of the menus. + client (Client): The client which is linked to the handler. + context (Union[CallbackQuery, Message]): The context which the + button is generated for. + parameters (Dict[str, Any]): The parameters which were passed to + the handler. + + Returns: + InlineKeyboardMarkup: The generated inline keyboard, which is then + displayed to the user + """ + raise NotImplementedError + + @abstractmethod + def on_callback( + self, + handler: BaseHandler, + client: Client, + callback: CallbackQuery, + parameters: Dict[str, Any], + ): + """This abstract method is intended to be implemented and is called + whenever a callback query is handled and refers to this menu. + + Args: + handler (BaseHandler): The handler which coordinates the management + of the menus. + client (Client): The client which is linked to the handler. + context (Union[CallbackQuery, Message]): The context which the + button is generated for. + parameters (Dict[str, Any]): The parameters which were passed to + to the handler. + """ raise NotImplementedError @abstractmethod @@ -86,4 +196,16 @@ def on_message( message: Message, parameters: Dict[str, Any], ): + """This abstract method is intended to be implemented and is called + whenever a message is handled and refers to this menu. + + Args: + handler (BaseHandler): The handler which coordinates the management + of the menus. + client (Client): The client which is linked to the handler. + context (Union[CallbackQuery, Message]): The context which the + button is generated for. + parameters (Dict[str, Any]): The parameters which were passed to + to the handler. + """ raise NotImplementedError