chore: update docstrings

hydrogram · alissonlauffer · Jan 16, 2024 · Nov 8, 2023 · Dec 2, 2023 · Dec 2, 2023
commit ae0ef6f47d227c117bd43fa4f178d4370e92d441
diff --git a/hydrogram/handlers/callback_query_handler.py b/hydrogram/handlers/callback_query_handler.py
@@ -18,7 +18,7 @@
 #  along with Hydrogram.  If not, see <http://www.gnu.org/licenses/>.
 
 from asyncio import iscoroutinefunction
-from typing import Callable
+from typing import Callable, Optional
 
 import hydrogram
 from hydrogram.types import CallbackQuery, Identifier, Listener, ListenerTypes
@@ -55,12 +55,16 @@ def __init__(self, callback: Callable, filters=None):
         self.original_callback = callback
         super().__init__(self.resolve_future_or_callback, filters)
 
-    def compose_data_identifier(self, query: CallbackQuery):
+    def compose_data_identifier(self, query: CallbackQuery) -> Identifier:
         """
         Composes an Identifier object from a CallbackQuery object.
 
-        :param query: The CallbackQuery object to compose of.
-        :return: An Identifier object.
+        Parameters:
+            query (:obj:`~hydrogram.types.CallbackQuery`):
+                The CallbackQuery object to compose of.
+
+        Returns:
+            :obj:`~hydrogram.types.Identifier`: An Identifier object.
         """
         from_user = query.from_user
         from_user_id = from_user.id if from_user else None
@@ -84,15 +88,20 @@ def compose_data_identifier(self, query: CallbackQuery):
 
     async def check_if_has_matching_listener(
         self, client: "hydrogram.Client", query: CallbackQuery
-    ) -> tuple[bool, Listener]:
+    ) -> tuple[bool, Optional[Listener]]:
         """
         Checks if the CallbackQuery object has a matching listener.
 
-        :param client: The Client object to check with.
-        :param query: The CallbackQuery object to check with.
-        :return: A tuple of a boolean and a Listener object. The boolean indicates whether
-        the found listener has filters and its filters matches with the CallbackQuery object.
-        The Listener object is the matching listener.
+        Parameters:
+            client (:obj:`~hydrogram.Client`):
+                The Client object to check with.
+
+            query (:obj:`~hydrogram.types.CallbackQuery`):
+                The CallbackQuery object to check with.
+
+        Returns:
+            A tuple of whether the CallbackQuery object has a matching listener and its filters does match with the
+            CallbackQuery and the matching listener;
         """
         data = self.compose_data_identifier(query)
 
@@ -114,14 +123,19 @@ async def check_if_has_matching_listener(
 
         return listener_does_match, listener
 
-    async def check(self, client: "hydrogram.Client", query: CallbackQuery):
+    async def check(self, client: "hydrogram.Client", query: CallbackQuery) -> bool:
         """
         Checks if the CallbackQuery object has a matching listener or handler.
 
-        :param client: The Client object to check with.
-        :param query: The CallbackQuery object to check with.
-        :return: A boolean indicating whether the CallbackQuery object has a matching listener or the handler
-        filter matches.
+        Parameters:
+            client (:obj:`~hydrogram.Client`):
+                The Client object to check with.
+
+            query (:obj:`~hydrogram.types.CallbackQuery`):
+                The CallbackQuery object to check with.
+
+        Returns:
+            ``bool``: A boolean indicating whether the CallbackQuery object has a matching listener or the handler filter matches.
         """
         listener_does_match, listener = await self.check_if_has_matching_listener(client, query)
 
@@ -167,14 +181,22 @@ async def check(self, client: "hydrogram.Client", query: CallbackQuery):
 
     async def resolve_future_or_callback(
         self, client: "hydrogram.Client", query: CallbackQuery, *args
-    ):
+    ) -> None:
         """
         Resolves the future or calls the callback of the listener. Will call the original handler if no listener.
 
-        :param client: The Client object to resolve or call with.
-        :param query: The CallbackQuery object to resolve or call with.
-        :param args: The arguments to call the callback with.
-        :return: None
+        Parameters:
+            client (:obj:`~hydrogram.Client`):
+                The Client object to resolve or call with.
+
+            query (:obj:`~hydrogram.types.CallbackQuery`):
+                The CallbackQuery object to resolve or call with.
+
+            args:
+                The arguments to call the callback with.
+
+        Returns:
+            ``None``
         """
         listener_does_match, listener = await self.check_if_has_matching_listener(client, query)
 

diff --git a/hydrogram/handlers/message_handler.py b/hydrogram/handlers/message_handler.py
@@ -18,10 +18,10 @@
 #  along with Hydrogram.  If not, see <http://www.gnu.org/licenses/>.
 
 from inspect import iscoroutinefunction
-from typing import Callable
+from typing import Callable, Optional
 
 import hydrogram
-from hydrogram.types import Identifier, ListenerTypes, Message
+from hydrogram.types import Identifier, Listener, ListenerTypes, Message
 
 from .handler import Handler
 
@@ -54,14 +54,22 @@ def __init__(self, callback: Callable, filters=None):
         self.original_callback = callback
         super().__init__(self.resolve_future_or_callback, filters)
 
-    async def check_if_has_matching_listener(self, client: "hydrogram.Client", message: Message):
+    async def check_if_has_matching_listener(
+        self, client: "hydrogram.Client", message: Message
+    ) -> tuple[bool, Optional[Listener]]:
         """
         Checks if the message has a matching listener.
 
-        :param client: The Client object to check with.
-        :param message: The Message object to check with.
-        :return: A tuple of whether the message has a matching listener and its filters does match with the Message
-        and the matching listener;
+        Parameters:
+            client (:obj:`~hydrogram.Client`):
+                The Client object to check with.
+
+            message (:obj:`~hydrogram.types.Message`):
+                The Message object to check with.
+
+        Returns:
+            ``tuple``: A tuple of two elements, the first one is whether the message has a matching listener or not,
+            the second one is the matching listener if exists.
         """
         from_user = message.from_user
         from_user_id = from_user.id if from_user else None
@@ -93,13 +101,19 @@ async def check_if_has_matching_listener(self, client: "hydrogram.Client", messa
 
         return listener_does_match, listener
 
-    async def check(self, client: "hydrogram.Client", message: Message):
+    async def check(self, client: "hydrogram.Client", message: Message) -> bool:
         """
         Checks if the message has a matching listener or handler and its filters does match with the Message.
 
-        :param client: Client object to check with.
-        :param message: Message object to check with.
-        :return: Whether the message has a matching listener or handler and its filters does match with the Message.
+        Parameters:
+            client (:obj:`~hydrogram.Client`):
+                The Client object to check with.
+
+            message (:obj:`~hydrogram.types.Message`):
+                The Message object to check with.
+
+        Returns:
+            ``bool``: Whether the message has a matching listener or handler and its filters does match with the Message.
         """
         listener_does_match = (await self.check_if_has_matching_listener(client, message))[0]
 
@@ -123,10 +137,15 @@ async def resolve_future_or_callback(
         """
         Resolves the future or calls the callback of the listener if the message has a matching listener.
 
-        :param client: Client object to resolve or call with.
-        :param message: Message object to resolve or call with.
-        :param args: Arguments to call the callback with.
-        :return: None
+        Parameters:
+            client (:obj:`~hydrogram.Client`):
+                The Client object to resolve or call with.
+
+            message (:obj:`~hydrogram.types.Message`):
+                The Message object to resolve or call with.
+
+            args (``tuple``):
+                Arguments to call the callback with.
         """
         listener_does_match, listener = await self.check_if_has_matching_listener(client, message)
 

diff --git a/hydrogram/helpers/helpers.py b/hydrogram/helpers/helpers.py
@@ -17,6 +17,8 @@
 #  You should have received a copy of the GNU Lesser General Public License
 #  along with Hydrogram.  If not, see <http://www.gnu.org/licenses/>.
 
+from typing import Optional, Union
+
 from hydrogram.types import (
     ForceReply,
     InlineKeyboardButton,
@@ -26,11 +28,16 @@
 )
 
 
-def ikb(rows=None):
+def ikb(rows: Optional[list[list[Union[str, tuple[str, str]]]]] = None) -> InlineKeyboardMarkup:
     """
     Create an InlineKeyboardMarkup from a list of lists of buttons.
-    :param rows: List of lists of buttons. Defaults to empty list.
-    :return: InlineKeyboardMarkup
+
+    Parameters:
+        rows (List[List[Union[str, Tuple[str, str]]]]):
+            List of lists of buttons. Defaults to empty list.
+
+    Returns:
+        :obj:`~hydrogram.types.InlineKeyboardMarkup`: An InlineKeyboardMarkup object.
     """
     if rows is None:
         rows = []
@@ -48,26 +55,38 @@ def ikb(rows=None):
     # return {'inline_keyboard': lines}
 
 
-def btn(text, value, type="callback_data"):
+def btn(text: str, value: str, type="callback_data") -> InlineKeyboardButton:
     """
     Create an InlineKeyboardButton.
 
-    :param text: Text of the button.
-    :param value: Value of the button.
-    :param type: Type of the button. Defaults to "callback_data".
-    :return: InlineKeyboardButton
+    Parameters:
+        text (str):
+            Text of the button.
+
+        value (str):
+            Value of the button.
+
+        type (str):
+            Type of the button. Defaults to "callback_data".
+
+    Returns:
+        :obj:`~hydrogram.types.InlineKeyboardButton`: An InlineKeyboardButton object.
     """
     return InlineKeyboardButton(text, **{type: value})
     # return {'text': text, type: value}
 
 
-# The inverse of above
-def bki(keyboard):
+# The inverse of ikb()
+def bki(keyboard: InlineKeyboardButton) -> list[list[Union[str, tuple[str, str]]]]:
     """
     Create a list of lists of buttons from an InlineKeyboardMarkup.
 
-    :param keyboard: InlineKeyboardMarkup
-    :return: List of lists of buttons
+    Parameters:
+        keyboard (:obj:`~hydrogram.types.InlineKeyboardMarkup`):
+            An InlineKeyboardMarkup object.
+
+    Returns:
+        List of lists of buttons.
     """
     lines = []
     for row in keyboard.inline_keyboard:
@@ -80,12 +99,16 @@ def bki(keyboard):
     # return ikb() format
 
 
-def ntb(button):
+def ntb(button: InlineKeyboardButton) -> list:
     """
     Create a button list from an InlineKeyboardButton.
 
-    :param button: InlineKeyboardButton
-    :return: Button as a list to be used in btn()
+    Parameters:
+        button (:obj:`~hydrogram.types.InlineKeyboardButton`):
+            An InlineKeyboardButton object.
+
+    Returns:
+        ``list``: A button list.
     """
     for btn_type in [
         "callback_data",
@@ -104,13 +127,19 @@ def ntb(button):
     # return {'text': text, type: value}
 
 
-def kb(rows=None, **kwargs):
+def kb(rows=None, **kwargs) -> ReplyKeyboardMarkup:
     """
     Create a ReplyKeyboardMarkup from a list of lists of buttons.
 
-    :param rows: List of lists of buttons. Defaults to empty list.
-    :param kwargs: Other arguments to pass to ReplyKeyboardMarkup.
-    :return: ReplyKeyboardMarkup
+    Parameters:
+        rows (List[List[str]]):
+            List of lists of buttons. Defaults to an empty list.
+
+        kwargs:
+            Other arguments to pass to ReplyKeyboardMarkup.
+
+    Returns:
+        :obj:`~hydrogram.types.ReplyKeyboardMarkup`: A ReplyKeyboardMarkup object.
     """
     if rows is None:
         rows = []
@@ -136,22 +165,32 @@ def kb(rows=None, **kwargs):
 """
 
 
-def force_reply(selective=True):
+def force_reply(selective=True) -> ForceReply:
     """
     Create a ForceReply.
 
-    :param selective: Whether the reply should be selective. Defaults to True.
-    :return: ForceReply
+    Parameters:
+        selective (bool):
+            Whether the reply should be selective. Defaults to True.
+
+    Returns:
+        :obj:`~hydrogram.types.ForceReply`: A ForceReply object.
     """
     return ForceReply(selective=selective)
 
 
-def array_chunk(input_array, size):
+def array_chunk(input_array, size) -> list[list]:
     """
     Split an array into chunks.
 
-    :param input_array: The array to split.
-    :param size: The size of each chunk.
-    :return: List of chunks.
+    Parameters:
+        input_array (list):
+            The array to split.
+
+        size (int):
+            The size of each chunk.
+
+    Returns:
+        list: A list of chunks.
     """
     return [input_array[i : i + size] for i in range(0, len(input_array), size)]