docs(handler): add docstrings to ParameterizedBaseHandler

It also adds docstrings to the functions that are related to it (i.e. `pass_handler_and_clean`).
hearot · Jun 12, 2020 · 579ad09 · 579ad09
1 parent a7a6060
commit 579ad09
Show file tree

Hide file tree

Showing 3 changed files with 127 additions and 8 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,7 +17,7 @@
    - Add a code of conduct ([95694f93986ede7545a782e6b34b8ec7ca2a2c93](https://github.com/hearot/pyrubrum/commit/95694f93986ede7545a782e6b34b8ec7ca2a2c93))
    - Add a security policy ([ba507a8b2a6a386d7ad2d561d9b805d341e8b284](https://github.com/hearot/pyrubrum/commit/ba507a8b2a6a386d7ad2d561d9b805d341e8b284))
    - Add a statement about the return value of `Node.__hash__()` ([5a9a257ef122bd47f0a010dc5e1ebcb5e1cb1b90](https://github.com/hearot/pyrubrum/commit/5a9a257ef122bd47f0a010dc5e1ebcb5e1cb1b90))
-   - Add disclaimer notice
+   - Add disclaimer notice ([a7a6060a7243a1ed7857b2b78649d573cbe7feab](https://github.com/hearot/pyrubrum/commit/a7a6060a7243a1ed7857b2b78649d573cbe7feab))
    - Add docstrings to `BaseDatabase` ([d3fd9a769e62196f01d3764b87896761bbaf77d6](https://github.com/hearot/pyrubrum/commit/d3fd9a769e62196f01d3764b87896761bbaf77d6))
    - Add docstrings to `BaseHandler` ([455a0a94977c1652b445b623df561f9606a0615e](https://github.com/hearot/pyrubrum/commit/455a0a94977c1652b445b623df561f9606a0615e))
    - Add docstrings to `BaseMenu` ([3a7ad4e3b23bfb85a9faa8c3c056e76abb87b771](https://github.com/hearot/pyrubrum/commit/3a7ad4e3b23bfb85a9faa8c3c056e76abb87b771))
@@ -28,6 +28,7 @@
    - Add docstrings to `Keyboard` ([c3b4f5f879eec2d953ed47be26e03241a7b0cfe7](https://github.com/hearot/pyrubrum/commit/c3b4f5f879eec2d953ed47be26e03241a7b0cfe7))
    - Add docstrings to `Menu` ([15c11e4f737c0c63bad29d6c3c758d2b775c9ea4](https://github.com/hearot/pyrubrum/commit/15c11e4f737c0c63bad29d6c3c758d2b775c9ea4))
    - Add docstrings to `Node` ([caf69bb8f7c6542bb731b7df6bf0f7ab7b3d4bd9](https://github.com/hearot/pyrubrum/commit/caf69bb8f7c6542bb731b7df6bf0f7ab7b3d4bd9))
+   - Add docstrings to `ParameterizedBaseHandler`
    - Add docstrings to `RedisDatabase` ([784b8f112d561b9a346b7f986710df2b1455e691](https://github.com/hearot/pyrubrum/commit/784b8f112d561b9a346b7f986710df2b1455e691))
    - Add docstrings to all the database exceptions ([0e561554d9d37ef755202cb7ef2905aadbd84700](https://github.com/hearot/pyrubrum/commit/0e561554d9d37ef755202cb7ef2905aadbd84700))
    - Add issue templates ([64c006258e373a97d0a9f83318af02c4310b585b](https://github.com/hearot/pyrubrum/commit/64c006258e373a97d0a9f83318af02c4310b585b))

diff --git a/FEATURES.md b/FEATURES.md
@@ -3,7 +3,7 @@
    - Add a code of conduct ([95694f93986ede7545a782e6b34b8ec7ca2a2c93](https://github.com/hearot/pyrubrum/commit/95694f93986ede7545a782e6b34b8ec7ca2a2c93))
    - Add a security policy ([ba507a8b2a6a386d7ad2d561d9b805d341e8b284](https://github.com/hearot/pyrubrum/commit/ba507a8b2a6a386d7ad2d561d9b805d341e8b284))
    - Add a statement about the return value of `Node.__hash__()` ([5a9a257ef122bd47f0a010dc5e1ebcb5e1cb1b90](https://github.com/hearot/pyrubrum/commit/5a9a257ef122bd47f0a010dc5e1ebcb5e1cb1b90))
-   - Add disclaimer notice
+   - Add disclaimer notice ([a7a6060a7243a1ed7857b2b78649d573cbe7feab](https://github.com/hearot/pyrubrum/commit/a7a6060a7243a1ed7857b2b78649d573cbe7feab))
    - Add docstrings to `BaseDatabase` ([d3fd9a769e62196f01d3764b87896761bbaf77d6](https://github.com/hearot/pyrubrum/commit/d3fd9a769e62196f01d3764b87896761bbaf77d6))
    - Add docstrings to `BaseHandler` ([455a0a94977c1652b445b623df561f9606a0615e](https://github.com/hearot/pyrubrum/commit/455a0a94977c1652b445b623df561f9606a0615e))
    - Add docstrings to `BaseMenu` ([3a7ad4e3b23bfb85a9faa8c3c056e76abb87b771](https://github.com/hearot/pyrubrum/commit/3a7ad4e3b23bfb85a9faa8c3c056e76abb87b771))
@@ -14,6 +14,7 @@
    - Add docstrings to `Keyboard` ([c3b4f5f879eec2d953ed47be26e03241a7b0cfe7](https://github.com/hearot/pyrubrum/commit/c3b4f5f879eec2d953ed47be26e03241a7b0cfe7))
    - Add docstrings to `Menu` ([15c11e4f737c0c63bad29d6c3c758d2b775c9ea4](https://github.com/hearot/pyrubrum/commit/15c11e4f737c0c63bad29d6c3c758d2b775c9ea4))
    - Add docstrings to `Node` ([caf69bb8f7c6542bb731b7df6bf0f7ab7b3d4bd9](https://github.com/hearot/pyrubrum/commit/caf69bb8f7c6542bb731b7df6bf0f7ab7b3d4bd9))
+   - Add docstrings to `ParameterizedBaseHandler`
    - Add docstrings to `RedisDatabase` ([784b8f112d561b9a346b7f986710df2b1455e691](https://github.com/hearot/pyrubrum/commit/784b8f112d561b9a346b7f986710df2b1455e691))
    - Add docstrings to all the database exceptions ([0e561554d9d37ef755202cb7ef2905aadbd84700](https://github.com/hearot/pyrubrum/commit/0e561554d9d37ef755202cb7ef2905aadbd84700))
    - Add issue templates ([64c006258e373a97d0a9f83318af02c4310b585b](https://github.com/hearot/pyrubrum/commit/64c006258e373a97d0a9f83318af02c4310b585b))

diff --git a/pyrubrum/parameterized_base_handler.py b/pyrubrum/parameterized_base_handler.py
@@ -18,17 +18,18 @@
 
 from dataclasses import dataclass
 from json import JSONDecodeError
-from typing import Any
-from typing import Callable
 from typing import List
 
 from pyrogram import CallbackQuery
 from pyrogram import CallbackQueryHandler
 from pyrogram import Client
 from pyrogram import InlineKeyboardButton
 from pyrogram.client.filters.filters import create
+from pyrogram.client.filters.filters import Filter
 
 from .base_handler import BaseHandler
+from .base_handler import Callback
+from .base_handler import PyrogramHandlerCallback
 from .button import Button
 from .database.base_database import BaseDatabase
 
@@ -40,13 +41,62 @@
 
 @dataclass(eq=False, init=False, repr=True)
 class ParameterizedBaseHandler(BaseHandler):
+    """Basic implementation of an handler which has got, by definition, a database,
+    with which it is able to perform parameterization (i.e. supports
+    parameters).
+
+    The purpose of this class is to give a general interface for an handler
+    which supports parameterization, as it doesn't implement anything except
+    for a basic setup of the client (see `setup`) and a filter that allows the
+    recognition of parameterized queries (see `filter`).
+
+    Attributes:
+        database (BaseDatabase): The storage for all the query parameters. It
+            is used to pass parameters between menus.
+    """
+
     database: BaseDatabase
 
     def __init__(self, database: BaseDatabase):
+        """Initialize the object.
+
+        Attributes:
+            database (BaseDatabase): The storage for all the query parameters.
+                It is used to pass parameters between menus.
+        """
         self.database = database
 
-    def filter(self, menu_id: str):
-        def func(flt, callback: CallbackQuery):
+    def filter(self, menu_id: str) -> Filter:
+        """Generate a function which is used by `CallbackQueryHandler` in order to
+        filter callback queries relying on the content of the provided menu
+        identifier.
+
+        A callback query is valid if its content follows the following pattern:
+            ``[CALLBACK_QUERY_ID] [MENU_ID] [ELEMENT_ID, optional]``
+
+        If the query that is being handled matches ``MENU_ID``, database is
+        queried with the content of ``CALLBACK_QUERY_ID``. If a valid match
+        is found, its content is converted from JSON and then parameters are
+        collected and stored in ``callback.parameters``.
+
+        If ``ELEMENT_ID``is provided, ``element_id`` is set to be equal to it
+        in ``callback.parameters``. If ``same_menu`` in ``callback.parameters``
+        is ``False``, a new key named ``[MENU_ID]_id`` is set to be equal to
+        ``ELEMENT_ID`` in ``callback.parameters``.
+
+        The filter returns ``True`` if the query is valid and matches
+        ``menu_id``. Otherwise, it returns ``False``.
+
+        Args:
+            menu_id (str): The unique identifier of the menu that has to be
+                matched.
+
+        Returns:
+            Filter: The function that gets called whenever a callback query is
+            being handled.
+        """
+
+        def func(_, callback: CallbackQuery):
             parameters = callback.data.split()
 
             if parameters[1] != menu_id:
@@ -86,6 +136,32 @@ def func(flt, callback: CallbackQuery):
     def process_keyboard(
         self, keyboard: List[List[Button]], callback_query_id: str
     ) -> List[List[InlineKeyboardButton]]:
+        """Given a list of a list of buttons which represents an inline keyboard and a
+        unique identifier for the callback, generate a Pyrogram-compatible
+        inline keyboard. It also creates a dictionary ``content``, whose keys
+        represent the identifiers of the menu collected in the keyboard and
+        values their own parameters. Finally, it converts ``content`` to JSON
+        and stores it inside the database using the provided query identifier
+        as key.
+
+        The returned inline keyboard does not store any parameters. Instead,
+        its buttons stores the data needed to get the parameters from the
+        database, in accordance with the following pattern:
+            ``[CALLBACK_QUERY_ID] [MENU_ID] [ELEMENT_ID, optional]``
+
+        See `ParameterizedBaseHandler.filter` for more information.
+
+        Args:
+            keyboard (List[List[Button]]): The inline keyboard you want to
+                process.
+            callback_query_id (str): The unique identifier of the callback
+                for which the keyboard is generated.
+
+        Returns:
+            List[List[InlineKeyboardButton]]: The generated keyboard in a
+            Pyrogram-compatible type.
+        """
+
         content = {}
 
         for row in keyboard:
@@ -120,6 +196,23 @@ def process_keyboard(
         ]
 
     def setup(self, client: Client):
+        """Make all the defined menus reachable by the client by adding handlers that
+        catch all their identifiers to it. It adds support to parameterization
+        by applying ``ParameterizedBaseHandler.filter` to all the handled
+        callback queries. It also calls `pass_handler_and_clean`, which lets
+        the callback functions get this handler as argument and deletes
+        handled callback queries from the database relying on the passed
+        identifiers.
+
+        Args:
+            client (Client): The client which is being set up.
+
+        Warning:
+            The functions the handlers make use of are not set up in the
+            same way objects added using Pyrogram handlers are. Pyrubrum
+            implements the following pattern:
+                ``callback(handler, client, context, parameters)``
+        """
         for menu in self.get_menus():
             client.add_handler(
                 CallbackQueryHandler(
@@ -130,8 +223,32 @@ def setup(self, client: Client):
 
 
 def pass_handler_and_clean(
-    func: Callable[[Client, Any], None], handler: ParameterizedBaseHandler
-) -> Callable[[Client, Any], None]:
+    func: Callback, handler: ParameterizedBaseHandler
+) -> PyrogramHandlerCallback:
+    """Generate a function which, whenever it is called, subsequently calls
+    `callback`, passing the handler from which this object was generated, and
+    then deletes the key which is associated to the handled query from the
+    database. It requires a subclass of `ParameterizedBaseHandler`to be
+    provided in order to work.
+
+    Args:
+        callback (Callback): The callback function which
+            automatically gets called by the generated function.
+        handler (ParameterizedBaseHandler): The handler object which made
+            use of this function in order to provide this one as a callback
+            to a Pyrogram handler.
+
+    Returns:
+        PyrogramHandlerCallback: The function which is being added to
+            a Pyrogram handler.
+
+    Warning:
+        The functions the handlers make use of are not set up in the
+        same way objects added using Pyrogram handlers are. Pyrubrum
+        implements the following pattern:
+            ``callback(handler, client, context, parameters)``
+    """
+
     def on_callback(client: Client, context):
         if isinstance(context, CallbackQuery):
             func(handler, client, context, context.parameters)