Documentation Update

README.md

@@ -5,20 +5,17 @@ _This Telegram bot allows users to conveniently find the cheapest flights and re
 ## Table of Contents
 
 - [About](#about)
+- [Features](#features)
 - [Getting Started](#getting-started)
-- [Prerequisites](#prerequisites)
 - [Installation](#installation)
-- [Usage](#usage)
-- [Contributing](#contributing)
 - [License](#license)
 
-## About
 
-We all want the cheapest possible flight but getting cheap flights is no easy task.
+## About
 
-This Telegram Bot uses Kiwi flight api to search flights and return the current cheapest flight for your desired routes and dates.
+We all love finding cheap flights, but it can often feel like a challenge. That’s where this Telegram Bot comes in!
 
-You can also save the flight result for the bot to track the flight price and the bot will notify you if the flight price has dropped.
+Powered by the Kiwi flight API, this bot makes it easy to search for the best deals on flights for your chosen routes and dates. Once you find a flight, you can even save it for price tracking. The bot will notify you if the price drops, so you’ll never miss out on a great deal!
 
 ## Features
 
@@ -27,12 +24,17 @@ You can also save the flight result for the bot to track the flight price and th
 - Flight Tracking.
 - KIWI API Support.
 - Inline And Keyboard Markup support.
+- Admin Panel.
+- Price Alerts.
 
 ### Bot Commands
 
 - `/start` - Initializes Bot welcome response.
 - `/flight_alerts` - Show all saved flight alerts.
+- `/menu` - Navigate to Main Menu.
 - `/reset` - Reset the flight search.
+- `/help` - Show Help.
+- `/admin` - Navigate to Admin Dashboard.
 
 ## Getting Started
 
@@ -44,17 +46,16 @@ You can also save the flight result for the bot to track the flight price and th
 
    | Env Variable      | Description                                              | Defaults               |
    | ----------------- | -------------------------------------------------------- | ---------------------- |
-   | `BOT_USERNAME`    | Your Telegram Bot Username                               | None                   |
    | `BOT_TOKEN`       | Your Telegram Bot Token                                  | None                   |
-   | `KIWI_API_KEY`    | Your KIWI API key                                        | None                   |
+   | `KIWI_API_KEY_STD`| Your KIWI API key for Oneway and Return flight search    | None                   |
+   | `KIWI_API_KEY_MULTICITY `| Your KIWI API key for Multicity flight search      | None                   |
    | `DATABASE_PATH`   | Your database file path                                  | `database\database.db` |
-   | `ADMINISTRATOR`   | Holds a list of telegram chat id's for admin rights      | []                     |
+   | `ADMINISTRATOR`   | Holds a list of telegram chat id's for admin rights      | [Integer]                     |
 
 
 ### Database
 
-This bot only supports a SQL database file. If you have an existing database file from previous use than edit your file path in your .env file.
-The default path is database\database.db which will be created automatically on the first call on the DB instance.
+This bot is compatible only with a SQL database file. If you have an existing database from prior use, make sure to update the file path in your .env file. The default path is database/database.db, which will be automatically created upon the first call to the database instance.
 
 ## Installation
 

bot_config.py

@@ -21,6 +21,11 @@
 
 
 class TelegramBot:
+    """
+    This class is a Telegram Bot. It contains the entire logic required to run a Telegram Bot.
+    It includes the Telegram Bot token, command handlers, callback query handlers, message handlers, error handlers, and job queue.
+    """
+
     def __init__(self, token: str) -> None:
         # TELEGRAM BOT FATHER CREDENTIALS
         self.token = token
@@ -95,10 +100,17 @@ def __init__(self, token: str) -> None:
 
     def load_global_settings(self):
 
+        """
+        This method loads the global settings from the database.
+        The global settings that are loaded are the flight search job interval.
+
+        Returns:
+            dict: A dictionary containing the global settings.
+        """
         db = DB()
         settings = {}
 
         settings['FS_JOB_INTV'] = db.cursor.execute('SELECT fs_job_interval FROM global_settings').fetchone()[0]
 
         db.close()
-        return settings
+        return settings

handlers/admin.py

@@ -20,6 +20,14 @@
 @admin_only
 async def admin_dashboard(update: Update, context: ContextTypes.DEFAULT_TYPE):
 
+    """
+    This function is a Telegram Bot Command Handler.
+    It is invoked when the user types /admin_dashboard in a Telegram chat.
+    The function will return a message with various statistics about the bot to the user.
+    The message includes the total number of users, the total number of flight alerts, the first run interval for the flight tracker job, the run intervals for the flight tracker job, and the flight alert limit.
+    The message also includes a button to set the flight alert limit and a button to set the run intervals for the flight tracker job.
+    """
+
     chat_id = update.effective_chat.id
 
     db = DB()
@@ -52,6 +60,15 @@ async def admin_dashboard(update: Update, context: ContextTypes.DEFAULT_TYPE):
 @send_action(action=ChatAction.TYPING)
 async def admin_convo(update: Update, context: ContextTypes.DEFAULT_TYPE):
 
+    """
+    This function is a Telegram Bot Message Handler.
+    It is invoked when the user sends a message during an admin session.
+    The function will check what the user is trying to set, either the flight tracker job interval or the flight alert limit.
+    The function will then validate the input and update the relevant value in the database.
+    The function will then send a message to the user indicating if the update was successful or not.
+    The function will also clear the chat_data to indicate that the admin session has expired.
+    """
+
     chat_id = update.effective_chat.id
     TEXT = update.message.text.strip()
     db = DB()

handlers/button.py

@@ -19,7 +19,11 @@
 
 @check_save_alert_limit
 async def button(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    """This function is a CALLBACKQUERY HANDLER. This function will handler any callback queries from any inline keyboard"""
+    """
+    This is a callback query handler that handles all inline keyboard button presses.
+    It will either delete the inline keyboard, send a response, or call another function based on the callback query data.
+    """
+
     callback = update.callback_query
     await callback.answer()
     chat_id = update.effective_chat.id

handlers/conversation.py

@@ -14,9 +14,22 @@
 
 
 @send_action(action=ChatAction.TYPING)
-async def converstaion(update: Update, context: ContextTypes.DEFAULT_TYPE, **kwargs):
-    """This function is a MESSAGE HANDLER. This function will optionaly take a keyword argument to initate a chat from the bot"""
+async def converstaion(update: Update, context: ContextTypes.DEFAULT_TYPE, **kwargs): 
+    """
+    Conversation handler. This function is responsible for handling user conversations.
+    It checks if user has clicked on flight type option and carries out the necessary
+    steps to complete the search. It also checks if user has entered a valid date and
+    provides an error message if the date is invalid. If the user has selected a flight
+    type but has not entered the required information, it will prompt the user to enter
+    the required information. If the user has not selected a flight type, it will prompt
+    the user to select a flight type.
 
+    :param update: The update object that contains the user's message
+    :type update: Update
+    :param context: The context object that contains the user's data
+    :type context: ContextTypes.DEFAULT_TYPE
+    """
+
     chat_id = update.effective_chat.id
     text = update.message.text.strip()
 

handlers/del_flight_alert.py

@@ -11,8 +11,15 @@
 
 @verify_user_on_del_alert
 async def del_flight_alert(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    """This function will delete the a flight data alert from the database.
-    It uses the context.args to get the flight_data id from the command send to the user."""
+    """
+    This function is a Telegram Bot Message Handler.
+    It is invoked when the user types a message that starts with '/TAP_DELETE_ID_'.
+    The function will delete the flight alert with the id specified in the message.
+    If the flight alert does not exist, it will send a message to the user with a red flag emoji and a message stating that the flight alert does not exist.
+    If the flight alert exists, it will delete the flight alert and send a message to the user with a green checkmark emoji and a message stating that the flight alert has been deleted.
+    The function will also close the database connection.
+    """
+
     flight_alert_id = int(update.message.text.split('ID_')[1].strip())
     db = DB()
 

handlers/error.py

@@ -11,7 +11,21 @@
 
 
 async def errors(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    """Error handler that handles bot errors and prints out errors to console """
+    """
+    Error handler for the telegram bot.
+
+    This function is called when an exception is raised in any of the 
+    command handlers or message handlers. It logs the exception and 
+    sends a message to the administrators specified in the config.
+
+    Args:
+        update (Update): The update object.
+        context (ContextTypes.DEFAULT_TYPE): The context object.
+
+    Returns:
+        None
+    """
+
     logger.exception(context.error)
     curr_datetime = datetime.datetime.now()
     error = context.error

handlers/flight_alerts.py

@@ -11,8 +11,15 @@
 
 
 async def flight_alerts(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    """This function returns all the saved flight alerts that are been tracked in the database.
-    It will provide a link to delete each a flight alert."""
+    """
+    This function is a Telegram Bot Command Handler.
+    It is invoked when the user types /flight_alerts in a Telegram chat.
+    The function will return a message with all the flight alerts created by the user in the chat.
+    The message will include the route, dates, adults and price of each flight alert.
+    The message will also include a delete button for each flight alert.
+    If the user has no flight alerts, the function will return a message with a button to create a new flight alert.
+    """
+
     chat_id = update.effective_chat.id
     db = DB()
 

handlers/flight_search_reset.py

@@ -9,6 +9,13 @@
 
 
 async def flight_search_reset(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    """
+    This function is a Telegram Bot Command Handler.
+    It is invoked when the user types /reset_flight_search in a Telegram chat.
+    The function will clear all the user data associated with the user and send a message
+    with a button to start a new flight search.
+    """
+
     chat_id = update.effective_chat.id
     context.user_data.clear()
     menu = single_button(text='🔎 New Flight Search',

handlers/help.py

@@ -10,7 +10,13 @@
 
 
 async def help(update: Update, context: ContextTypes.DEFAULT_TYPE):
-
+    """
+    This function is a Telegram Bot Command Handler.
+    It is invoked when the user types /help in a Telegram chat.
+    The function will return a message with the help text.
+    The message will also include a button to go back to the main menu.
+    """
+
     FILE_PATH = os.path.join('BotResponses', 'help.txt')
 
     with open(FILE_PATH, encoding='utf-8') as file:

handlers/main_menu.py

@@ -10,7 +10,13 @@
 from utils.keyboards import main_menu
 
 
-async def handler_main_menu(update: Update, context: ContextTypes.DEFAULT_TYPE):
+async def handler_main_menu(update: Update, context: ContextTypes.DEFAULT_TYPE): 
+    """
+    This is a Telegram Bot Command Handler.
+    It is invoked when the user types /menu in a Telegram chat.
+    The function will return a message with a random response from BotResponses/main_menu.txt.
+    The message will also include the Main Menu.
+    """
 
     FILE_PATH = os.path.join('BotResponses', 'main_menu.txt')
 

handlers/start.py

@@ -10,7 +10,13 @@
 
 
 async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    """This function is a COMMAND HANDLER. This function will only be called with the /start command"""
+    """
+    This function is a Telegram Bot Command Handler.
+    It is invoked when the user types /start in a Telegram chat.
+    The function will return a message with a greeting and a list of commands the bot can do.
+    The message will also include a button that will redirect the user to the main menu.
+    """
+
     first_name = update.message.chat.first_name
     last_name = update.message.chat.last_name
     FILE_PATH = os.path.join('BotResponses', 'start_response.txt')

handlers/unknown.py

@@ -10,5 +10,10 @@
 
 
 async def unknown_commands(update: Update, context: ContextTypes.DEFAULT_TYPE):
-
+    """
+    This is a Telegram Bot Message Handler.
+    It is invoked when the user sends a command that the bot does not understand.
+    The function will return a message with a sorry message and a button to go back to the main menu.
+    """
+
     await context.bot.send_message(chat_id=update.effective_chat.id, text='🤖 Sorry, i do not understand this command.', reply_markup=main_menu_redirect, parse_mode=ParseMode.HTML)