💡 documentation: change classes structure and add docstrings to funct…

…ions

pynani/utils/Buttons.py

@@ -1,52 +1,104 @@
-from typing import Optional, Union
-
-
-class Buttons:
-    def __make_button(self, title: str, url: Optional[str] = None, call_number: Optional[str] = None) -> dict:
-        if url is not None and call_number is not None:
-            raise ValueError("You can't have both url and call_number at the same time")
-
-        if url:
-            type_button = "web_url"
-            url_button = url
-            payload_button = ""
-        elif call_number:
-            type_button = "phone_number"
-            url_button = ""
-            payload_button = call_number
-        elif not url and not call_number:
-            type_button = "postback"
-            url_button = ""
-            payload_button = "DEVELOPER_DEFINED_PAYLOAD"
-
-        return {
-            "type": type_button,
-            "title": title,
-            "payload": payload_button, 
-            "url": url_button,
-        }
+from typing import Optional, Union, List, Dict
+from .logs import logger
+
+
+def __make_button( title: str, url: Optional[str] = None, call_number: Optional[str] = None) -> Dict:
+    """
+    Creates a button with the specified title and optional URL or call number.
+
+    Args:
+        title (str): The title of the button.
+        url (Optional[str], optional): The URL associated with the button. Defaults to None.
+        call_number (Optional[str], optional): The call number associated with the button. Defaults to None.
+
+    Returns:
+        Dict: A dictionary representing the button with its properties.
+    
+    Raises:
+        ValueError: If both URL and call number are provided.
+    
+    Example:
+        >>> __make_button("Hola", "https://www.google.com")
+        {'type': 'web_url', 'title': 'Hola', 'payload': '', 'url': 'https://www.google.com'}
+        >>> __make_button("Mundo", call_number="+525555555555")
+        {'type': 'phone_number', 'title': 'Mundo', 'payload': '+525555555555', 'url': ''}
+        >>> __make_button("Hello")
+        {'type': 'postback', 'title': 'Hello', 'payload': 'DEVELOPER_DEFINED_PAYLOAD', 'url': ''}
+    """
+
+    if url is not None and call_number is not None:
+        logger.error("You can't have both url and call_number at the same time")
+        raise ValueError("You can't have both url and call_number at the same time")
 
-    def basic_buttons(self, buttons: Union[str, list]) -> list:
-        if isinstance(buttons, str):
-            return [self.__make_button(buttons)]
-        else:
-            if len(buttons) > 3:
-                print("Buttons template should be less than 3")
-                buttons = buttons[:3]
-            return [self.__make_button(button) for button in buttons]
+    if url:
+        type_button = "web_url"
+        url_button = url
+        payload_button = ""
+    elif call_number:
+        type_button = "phone_number"
+        url_button = ""
+        payload_button = call_number
+    elif not url and not call_number:
+        type_button = "postback"
+        url_button = ""
+        payload_button = "DEVELOPER_DEFINED_PAYLOAD"
 
-    def leave_buttons(self, buttons: Union[dict, list]):
-        if isinstance(buttons, dict):
-            return [self.__make_button(**buttons)]
-        else:
-            if len(buttons) > 3:
-                print("Buttons template should be less than 3")
-                buttons = buttons[:3]
-            return [self.__make_button(**button) for button in buttons]
+    return {
+        "type": type_button,
+        "title": title,
+        "payload": payload_button, 
+        "url": url_button,
+    }
 
-
-# bb = Button()
-# # print(bb.basic_buttons(["Hola", "Mundo", "🔥"]))
-# print(bb.leave_buttons([{"title": "Hola", "url": "https://www.google.com"}, {"title": "Mundo", "call_number": "+525555555555"}]))
+def basic_buttons( buttons: Union[str, List[Union[str, int]]]) -> List:
+    """
+    Creates a list of basic buttons.
 
+    Args:
+        buttons (Union[str, List[Union[str, int]]]): The buttons to be created. It can be a string or a list of strings or integers.
+
+    Returns:
+        List: A list of dictionaries representing the basic buttons with their properties.
+
+    Example:
+        >>> basic_buttons(["Hello", "World", "🔥"])
+        [{'type': 'postback', 'title': 'Hello', 'payload': 'DEVELOPER_DEFINED_PAYLOAD', 'url': ''}, 
+        {'type': 'postback', 'title': 'World', 'payload': 'DEVELOPER_DEFINED_PAYLOAD', 'url': ''}, 
+        {'type': 'postback', 'title': '🔥', 'payload': 'DEVELOPER_DEFINED_PAYLOAD', 'url': ''}]
+        >>> basic_buttons("Hello")
+        [{'type': 'postback', 'title': 'Hello', 'payload': 'DEVELOPER_DEFINED_PAYLOAD', 'url': ''}]
+    """
+
+    if isinstance(buttons, str):
+        return [__make_button(buttons)]
+    else:
+        if len(buttons) > 3:
+            logger.warning("Buttons template should be less than 3")
+            buttons = buttons[:3]
+        return [__make_button(button) for button in buttons]
+
+def leave_buttons( buttons: Union[Dict, List[Dict]]) -> List:
+    """
+    Creates a list of leave buttons.
+
+    Args:
+        buttons (Union[Dict, List[Dict]]): The buttons to be created. It can be a dictionary or a list of dictionaries.
+
+    Returns:
+        List: A list of dictionaries representing the leave buttons with their properties.
+    
+    Example:
+        >>> leave_buttons([{"title": "Hello", "url": "https://www.google.com"}, {"title": "World", "call_number": "+525555555555"}])
+        [{'type': 'web_url', 'title': 'Hello', 'payload': '', 'url': 'https://www.google.com'}, 
+        {'type': 'phone_number', 'title': 'World', 'payload': '+525555555555', 'url': ''}]
+        >>> leave_buttons({"title": "Hello", "url": "https://www.google.com"})
+        [{'type': 'web_url', 'title': 'Hello', 'payload': '', 'url': 'https://www.google.com'}]
+    """
 
+    if isinstance(buttons, dict):
+        return [__make_button(**buttons)]
+    else:
+        if len(buttons) > 3:
+            logger.warning("Buttons template should be less than 3")
+            buttons = buttons[:3]
+        return [__make_button(**button) for button in buttons]

pynani/utils/__init__.py

@@ -0,0 +1 @@
+from .logs import logger

pynani/utils/logs.py

@@ -0,0 +1,25 @@
+"""This file is used to configure the logger for the project"""
+
+
+import logging
+from colorlog import ColoredFormatter
+
+
+logger = logging.getLogger('Pynani')
+logger.setLevel(logging.DEBUG)
+formatter = ColoredFormatter(
+    "%(log_color)s%(levelname)s: %(name)s  [%(asctime)s] -- %(message)s",
+    datefmt='%d/%m/%Y %H:%M:%S',
+    log_colors={
+        'DEBUG': 'cyan',
+        'INFO': 'green',
+        'WARNING': 'yellow',
+        'ERROR': 'red',
+        'CRITICAL': 'bold_red',
+    }
+)
+console_handler = logging.StreamHandler()
+console_handler.setLevel(logging.DEBUG)
+console_handler.setFormatter(formatter)
+
+logger.addHandler(console_handler)

pynani/utils/quick_reply.py

@@ -0,0 +1,90 @@
+from typing import Optional, Union, List, Dict
+from .logs import logger
+
+
+def __make_quick_button(text: Union[str, int], image_url: Optional[str] = None) -> Dict:
+    """
+    Creates a quick reply button with the specified text, optional image URL, and payload.
+
+    Args:
+        text (Union[str, int]): The text or integer to be displayed on the button.
+        image_url (Optional[str], optional): The URL of the image to be displayed on the button. Defaults to None.
+
+    Returns:
+        Dict: A dictionary representing the quick reply button with its properties.
+
+    Example:
+        >>> __make_quick_button("Hello")
+        {'content_type': 'text', 'title': 'Hello', 'payload': '<POSTBACK_PAYLOAD>', 'image_url': ''}
+        >>> __make_quick_button("World", "https://photos.com/world.jpg")
+        {'content_type': 'text', 'title': 'World', 'payload': '<POSTBACK_PAYLOAD>', 'image_url': 'https://photos.com/world.jpg'}
+    """
+
+    return {
+        "content_type": "text",
+        "title": text,
+        "payload": "<POSTBACK_PAYLOAD>", 
+        "image_url": image_url,
+    }
+
+def quick_buttons(buttons: List[Union[str, int]]) -> List[Dict]:
+    """
+    Prepares a list of quick reply buttons from a list of strings.
+
+    Args:
+        buttons (List[Union[str, int]]): A list of strings or integers representing the text for each quick reply button.
+
+    Returns:
+        List: A list of dictionaries representing the quick reply buttons with their properties.
+
+    Example:
+        >>> quick_buttons(["Hello", "World"])
+        [{'content_type': 'text', 'title': 'Hello', 'payload': '<POSTBACK_PAYLOAD>', 'image_url': ''}, 
+        {'content_type': 'text', 'title': 'World', 'payload': '<POSTBACK_PAYLOAD>', 'image_url': ''}]
+        >>> quick_buttons([1, 2, 3])
+        [{'content_type': 'text', 'title': '1', 'payload': '<POSTBACK_PAYLOAD>', 'image_url': ''}, 
+        {'content_type': 'text', 'title': '2', 'payload': '<POSTBACK_PAYLOAD>', 'image_url': ''}, 
+        {'content_type': 'text', 'title': '3', 'payload': '<POSTBACK_PAYLOAD>', 'image_url': ''}]
+    """
+
+    r_buttons = []
+    if len(buttons) > 13:
+        logger.warning("Quick replies should be less than 13")
+        buttons = buttons[:13]
+
+    for b in buttons:
+        r_buttons.append(__make_quick_button(b))
+
+    return r_buttons
+
+def quick_buttons_image(buttons: List) -> List[Dict]:
+    """
+    Prepares a list of quick reply buttons with images from a list of dictionaries.
+
+    Args:
+        buttons (List): A list of dictionaries representing the quick reply buttons with their properties.
+
+    Returns:
+        List: A list of dictionaries representing the quick reply buttons with their properties, including images.
+
+    Raises:
+        ValueError: If each button is not a dictionary.
+
+    Example:
+        >>> quick_buttons_image([{"text": "Hello", "image_url": "https://photos.com/hello.jpg"}, {"text": "World", "image_url": "https://photos.com/world.jpg"}])
+        [{'content_type': 'text', 'title': 'Hello', 'payload': '<POSTBACK_PAYLOAD>', 'image_url': 'https://photos.com/hello.jpg'}, 
+        {'content_type': 'text', 'title': 'World', 'payload': '<POSTBACK_PAYLOAD>', 'image_url': 'https://photos.com/world.jpg'}]
+    """
+
+    r_buttons = []
+    if len(buttons) > 13:
+        logger.warning("Quick replies should be less than 13")
+        buttons = buttons[:13]
+    for b in buttons:
+        if not isinstance(b, dict):
+            logger.error("Each button should be a dictionary")
+            raise ValueError("Each button should be a dictionary")
+        else:
+            r_buttons.append(__make_quick_button(**b))
+
+    return r_buttons