diff --git a/README.md b/README.md index ef32c0768..40fd8cbad 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,11 @@
  • Check out the video!
  • What is new in this version?
  • Installation
    • +
  • How To Run
    • +
  • Configuring Email Credentials for SMTP: Sending Emails from Your Account
  • Testing
  • Code Coverage
    • +
  • Use Cases
  • Automated Analysis Tools
  • License
  • Code Documentation
    • @@ -68,7 +71,7 @@ DollarSplitBot: Where simplicity meets financial harmony at your fingertips. ## Check out the video! -To demonstrate our application's functionality and showcase its working examples, we have produced a YouTube video for the DollarSplitBot project. In this video, we showcase that the system operates as intended. You can view the video by clicking on the following link: [YouTube Link](https://youtu.be/aCjcT1CHAzU) +To demonstrate our application's functionality and showcase its working examples, we have produced a YouTube video for the DollarSplitBot project. In this video, we showcase that the system operates as intended. You can view the video by clicking on the following link: [YouTube Link](https://www.youtube.com/watch?v=JT06PTMHz7Y) ## What is new in this version? diff --git a/code/history.py b/code/history.py index df99dcad9..e32158a5c 100644 --- a/code/history.py +++ b/code/history.py @@ -14,32 +14,6 @@ def run(message, bot): displays the user's historical data. """ - # try: - # helper.read_json() - # chat_id = message.chat.id - # user_history = helper.getUserHistory(chat_id) - - # if user_history is None: - # raise Exception("Sorry! No spending records found!") - - # if len(user_history) == 0: - # bot.send_message(chat_id, "Sorry! No spending records found!") - # else: - # # Create a CSV representation of the data - # csv_data = "DATE, CATEGORY, AMOUNT\n" - - # for line in user_history: - # rec = line.split(",") # Assuming data is comma-separated - # if len(rec) == 3: - # csv_data += f"{rec[0]}, {rec[1]}, {rec[2]}\n" - - # # Send the CSV data as a text message - # bot.send_message(chat_id, csv_data) - - # except Exception as e: - # logging.exception(str(e)) - # bot.reply_to(message, "Oops! " + str(e)) - try: helper.read_json() chat_id = message.chat.id diff --git a/code/pdf.py b/code/pdf.py index faf67500f..da4ff5d98 100644 --- a/code/pdf.py +++ b/code/pdf.py @@ -2,23 +2,10 @@ import logging from matplotlib import pyplot as plt from telebot import types - -#Issue 15 - Added tabulate and fpdf libraries from tabulate import tabulate from fpdf import FPDF -#Issue 23 - Added Tabula library -#import tabula - -#from reportlab.lib import colors -#from reportlab.lib.pagesizes import letter -#from reportlab.platypus import SimpleDocTemplate, Table, TableStyle - -#Issue - 33 - # === Documentation of pdf.py === - - def run(message, bot): """ run(message, bot): This is the main function used to implement the pdf save feature. @@ -31,8 +18,6 @@ def run(message, bot): #print('User-history--> ',user_history) print('User_list', user_list) - #Issue 23 - add two pdf types - start - markup = types.ReplyKeyboardMarkup(one_time_keyboard=True) #markup.row_width = 2 markup.add("PDF for Total Expenses - Category wise", "PDF showing who owes whom how much") @@ -41,7 +26,6 @@ def run(message, bot): user_history = helper.getUserHistory(chat_id) bot.register_next_step_handler(msg, pdfGeneration, bot,user_list, user_history) - #Issue 23 - add two pdf types - end except Exception as e: logging.exception(str(e)) @@ -108,10 +92,6 @@ def pdfGeneration(message, bot, user_list, user_history): pdf.output("expense_report.pdf") bot.send_document(chat_id, open("expense_report.pdf", "rb")) print("PDF generated successfully.") - #issue 15 - modified the format of pdf document - start - - - #Issue 3 - added the else condition - start else: message = "Looks like you have not entered any data yet. Please enter some data and then try creating a pdf." bot.send_message(chat_id, message) @@ -127,8 +107,6 @@ def pdfGeneration(message, bot, user_list, user_history): display_text += commands[c] + "\n" bot.send_message(chat_id, "Please select a menu option from below:") bot.send_message(chat_id, display_text) - #Issue 3 - added the else condition - end - #Issue 23 - added code for generating pdf showing who owes whom how much elif choice == 'PDF showing who owes whom how much': message = "Alright. I just created a pdf of your expense history!" bot.send_message(chat_id, message) @@ -155,8 +133,6 @@ def pdfGeneration(message, bot, user_list, user_history): pdf.set_font("helvetica", size=12) for user, details in user_list.items(): - #print('User! ', user) - #print('details! ', details) for i, user_name in enumerate(details["users"]): #amounts = '' pdf.cell(50, 10, user_name, border=1, align="C", fill=True) diff --git a/code/send_mail.py b/code/send_mail.py index 94d6980e0..873fe6f9c 100644 --- a/code/send_mail.py +++ b/code/send_mail.py @@ -14,6 +14,13 @@ def run(message, bot): bot.register_next_step_handler(message1, add_emails, bot) def add_emails(message, bot): + """ + add_emails(message, bot): + Takes 2 arguments - message (a message received from the user) and bot (the chatbot instance). + This function extracts the email from the user's message and associates it with the user's chat ID in the user_emails dictionary. + It can also perform email validation. If the email is invalid, it sends a message to the user to enter a valid email. + Finally, the user is notified that their email has been recorded and is asked if they want to send an email to the provided address. + """ chat_id = message.chat.id email = message.text # Assuming you want to store the email address in the user_emails dictionary @@ -30,11 +37,24 @@ def add_emails(message, bot): # Example of a basic email validation function (you can expand this) def is_valid_email(email): + """ + is_valid_email(email): + Takes one argument - email (the email address to be validated). + This function checks if the provided email address is in a valid format using a regular expression pattern. + If the email is in a valid format, it returns True; otherwise, it returns False. + """ import re email_pattern = r'^\S+@\S+\.\S+$' return re.match(email_pattern, email) is not None def send_email(choice, bot): + """ + send_email(choice, bot): + Takes two arguments - choice (user's choice of sending an email) and bot (the chatbot instance). + If the user's choice is 'Y' or 'y', this function sets up a Gmail SMTP connection, composes and sends emails to all users stored in the user_emails dictionary. + It uses a Gmail account for sending emails, and the email content is based on data obtained from the 'helper.read_json()' function. + After sending the emails, it closes the SMTP connection. + """ if str(choice.text) == "Y" or str(choice.text) == "y": # Set up the Gmail API smtp_server = 'smtp.gmail.com' @@ -68,6 +88,13 @@ def send_email(choice, bot): def format_text_data(user_list): + """ + format_text_data(user_list): + Takes one argument - user_list (a dictionary containing details about owed and owing amounts among users). + This function formats the provided user_list data into a text representation with detailed information on who owes and is owed money. + The formatted text data is enclosed in triple backticks for use in Markdown or code block formatting. + The resulting text data is returned as a string. + """ text_data = "```\n" for user, details in user_list.items(): diff --git a/docs/code.md b/docs/code.md index 096a6524c..01ef3c272 100644 --- a/docs/code.md +++ b/docs/code.md @@ -2,34 +2,21 @@ code.py is the main file from where calls to the corresponding .py files for all features are sent. It contains a number of endpoints which redirect to function calls in the corresponding files. # Location of Code for this Feature -The code that implements this feature can be found [here](https://github.com/sak007/MyDollarBot-BOTGo/blob/main/code/code.py) +The code that implements this feature can be found [here](https://github.com/shonilbhide/dollar_bot/blob/Rubrics/code/code.py) + # Code Description ## Functions -1. main() -The entire bot's execution begins here. It ensure the **bot** variable begins polling and actively listening for requests from telegram. - -2. listener(user_requests): -Takes 1 argument **user_requests** and logs all user interaction with the bot including all bot commands run and any other issue logs. - -3. start_and_menu_command(m): -Prints out the the main menu displaying the features that the bot offers and the corresponding commands to be run from the Telegram UI to use these features. Commands used to run this: commands=['start', 'menu'] - -4. command_add(message) -Takes 1 argument **message** which contains the message from the user along with the chat ID of the user chat. It then calls add.py to run to execute the add functionality. Commands used to run this: commands=['add'] +- run(message, bot): This function serves as the entry point for the budget feature. It displays a menu in the chatbot, prompting the user to select an operation related to their budget. The available options are determined by the helper.getBudgetOptions() function. Once the user makes a selection, the control is passed to the post_operation_selection(message, bot) function for further processing. -5. command_history(message): -Takes 1 argument **message** which contains the message from the user along with the chat ID of the user chat. It then calls history.py to run to execute the add functionality. Commands used to run this: commands=['history'] +- post_operation_selection(message, bot): This function processes the user's selection of a budget operation. It checks if the selected operation is valid and, if not, informs the user that the operation is invalid. If the user is new and doesn't have a budget record, it initializes one. Depending on the selected operation (e.g., add, update, view, delete), it calls the respective sub-module functions to perform the desired operation and then stores the updated budget data using helper.write_json(user_list). -6. command_edit(message): -Takes 1 argument **message** which contains the message from the user along with the chat ID of the user chat. It then calls edit.py to run to execute the add functionality. Commands used to run this: commands=['edit'] +- budget_update.run(message, bot): This function is called when the user selects the "add" or "update" operation. It handles the process of adding or updating budget expenses. The exact details of these operations are likely implemented in the budget_update module. -7. command_display(message): -Takes 1 argument **message** which contains the message from the user along with the chat ID of the user chat. It then calls display.py to run to execute the add functionality. Commands used to run this: commands=['display'] +- budget_view.run(message, bot): This function is called when the user selects the "view" operation. It is responsible for displaying the user's budget information, such as expenses and balances. The specific implementation of the viewing process is likely found in the budget_view module. -8. command_delete(message): -Takes 1 argument **message** which contains the message from the user along with the chat ID of the user chat. It then calls delete.py to run to execute the add functionality. Commands used to run this: commands=['display'] +- budget_delete.run(message, bot): This function is called when the user selects the "delete" operation. It is responsible for managing the process of deleting specific budget expenses. The details of how the deletion process works are likely defined in the budget_delete module. # How to run this feature? -This file contains information on the main code.py file from where all features are run. Instructions to run this are the same as instructions to run the project and can be found in README.md. \ No newline at end of file +This file contains information on the main code.py file from where all features are run. Instructions to run this are the same as instructions to run the project and can be found in README.md. diff --git a/docs/graphing.md b/docs/graphing.md index 36ae40d9b..efbd38542 100644 --- a/docs/graphing.md +++ b/docs/graphing.md @@ -4,16 +4,16 @@ This feature enables the user to see their expense in a graphical format to enab Currently, the /display command will provide the expenses as a message to the users via the bot. To better the UX, we decided to add the option to show the expenses in a Bar Graph. # Location of Code for this Feature -The code that implements this feature can be found [here](https://github.com/sak007/MyDollarBot-BOTGo/blob/main/code/graphing.py) +The code that implements this feature can be found [here](https://github.com/shonilbhide/dollar_bot/blob/Rubrics/code/graphing.py) # Code Description ## Functions -1. visualize(total_text): -This is the main function used to implement the graphing part of display feature. This file is called from display.py, and takes the user expense as a string and creates a dictionary which in turn is fed as input matplotlib to create the graph +- viewBudget(data): This function creates a pie chart to visualize different budget categories. It takes a dictionary of budget data as input and generates a graph that represents the budget distribution across various categories. To provide a visual representation of how the budget is allocated in different spending categories. -2. addlabels(x, y): -This function is used to add the labels to the graph. It takes the expense values and adds the values inside the bar graph for each expense type +- addlabels(x, y): This function is used to add labels to the bar graph. It takes two lists, 'x' (category names) and 'y' (expenditure values), and adds the corresponding values inside the bars of a bar graph. To make the bar graph more informative by labeling each bar with its expenditure value. + +- visualize(total_text, monthly_budget): This is the main function that generates a bar graph to compare actual expenditure with the budget for different categories. It takes two inputs: 'total_text,' which contains information about actual expenses, and 'monthly_budget,' which is a dictionary specifying the budget for each category. To create a visual comparison between the user's actual expenditures and their budgeted amounts for different spending categories. # How to run this feature? After you've added sufficient input data, use the /display command and you can see the output in a pictorial representation. diff --git a/docs/helper.md b/docs/helper.md index 54b993b7f..e7dca7d26 100644 --- a/docs/helper.md +++ b/docs/helper.md @@ -2,42 +2,32 @@ The helper file contains a set of functions that are commonly used for repeated tasks in the various features of MyDollarBot. Since these come up often, we have put them all up here in a separate file for reusability. # Location of Code for this Feature -The code that implements this feature can be found [here](https://github.com/sak007/MyDollarBot-BOTGo/blob/main/code/helper.py) +The code that implements this feature can be found [here](https://github.com/shonilbhide/dollar_bot/blob/main/code/helper.py) # Code Description ## Functions -1. read_json(): -Function to load .json expense record data +- spend_categories: This is a list of predefined spending categories, such as "Food," "Groceries," "Utilities," etc. These categories are used to categorize expenses. -2. write_json(user_list): -Stores data into the datastore of the bot. +- choices: A list containing three options: "Date," "Category," and "Cost." These options might be used to select how the user wants to view or filter their expense data. -3. validate_entered_amount(amount_entered): -Takes 1 argument, **amount_entered**. It validates this amount's format to see if it has been correctly entered by the user. +- spend_display_option: This list contains two options: "Day" and "Month." These options could be used to specify whether the user wants to view expenses on a daily or monthly basis. -4. getUserHistory(chat_id): -Takes 1 argument **chat_id** and uses this to get the relevant user's historical data. +- spend_estimate_option: Another list with two options: "Next day" and "Next month." These might be used to estimate future expenses based on past spending data. -5. getSpendCategories(): -This functions returns the spend categories used in the bot. These are defined the same file. +- update_options: A dictionary with two key-value pairs, "continue" and "exit." These options could be used to continue or exit a particular process within the program. -6. getSpendDisplayOptions(): -This functions returns the spend display options used in the bot. These are defined the same file. +- budget_options: A dictionary with options related to budget management, such as "add," "update," "view," and "delete." -7. getCommands(): -This functions returns the command options used in the bot. These are defined the same file. +- budget_types: A dictionary that defines different types of budgets, such as "Overall Budget" and "Category-Wise Budget." -8. def getDateFormat(): -This functions returns the date format used in the bot. +- data_format: A dictionary that seems to be an initial data structure for storing user data, expenses, and budgets. It has placeholders for various data, including user information, expenses, and budget details. -9. def getTimeFormat(): -This functions returns the time format used in the bot. +- commands: A dictionary that provides descriptions of various commands or actions that the user can perform within the program. These descriptions include commands like "add," "display," "edit," etc. -10. def getMonthFormat(): -This functions returns the month format used in the bot. +Functions: The code defines several functions, including read_json, write_json, validate_entered_amount, and others. These functions likely handle reading and writing data, validating user input, and managing user records and budgets # How to run this feature? Once the project is running(please follow the instructions given in the main README.md for this), please type /add into the telegram bot. -This file is not a feature and cannot be run per se. Its functions are used all over by the other files as it provides helper functions for various functionalities and features. \ No newline at end of file +This file is not a feature and cannot be run per se. Its functions are used all over by the other files as it provides helper functions for various functionalities and features. diff --git a/docs/history.md b/docs/history.md index 739d94824..88c0e2721 100644 --- a/docs/history.md +++ b/docs/history.md @@ -2,22 +2,22 @@ This feature enables the user to view all of their stored records i.e it gives a historical view of all the expenses stored in MyDollarBot. # Location of Code for this Feature -The code that implements this feature can be found [here](https://github.com/sak007/MyDollarBot-BOTGo/blob/main/code/history.py) +The code that implements this feature can be found [here](https://github.com/shonilbhide/dollar_bot/blob/main/code/history.py) # Code Description ## Functions -1. run(message, bot): -This is the main function used to implement the delete feature. It takes 2 arguments for processing - **message** which is the message from the user, and **bot** which is the telegram bot object from the main code.py function. It calls helper.py to get the user's historical data and based on whether there is data available, it either prints an error message or displays the user's historical data. +- run(message, bot): This is the primary function that handles the display of historical spending data for a user. +How it works: It takes two inputs, message (a message from the user) and bot (a communication tool for the bot). The function first tries to read the user's historical data, and if it finds any data, it formats it into a tabular view. Then it sends this data back to the user. If no data is found, it informs the user that there are no records. To provide the user with their spending history. + +- helper.read_json(): This function reads data from a JSON file. To retrieve the user's historical data. + +- helper.getUserHistory(chat_id): This function retrieves a specific user's spending history. To obtain the user's historical spending records based on their chat ID. + +- bot.send_message(chat_id, tabular_data, parse_mode="Markdown"): This sends the formatted spending data back to the user in a message, allowing the user to view their historical data in a neat table format. To present the historical data to the user in a visually appealing way. + +- Exception Handling: The code is prepared to handle exceptions. If any errors occur during the process, it logs the error and informs the user about the issue. To ensure that the user receives feedback in case something goes wrong, and to keep a record of errors for debugging. # How to run this feature? Once the project is running(please follow the instructions given in the main README.md for this), please type /add into the telegram bot. -AGM, [13-10-2023 05:48 PM] -/history - -agmalpur, [13-10-2023 05:48 PM] -| DATE | CATEGORY | AMOUNT | -+-------------------+-------------------+-------------+ -| 13-Oct-2023 16:55 | Transport | 8.0 | -+-------------------+-------------------+-------------+ diff --git a/docs/notifier.md b/docs/notifier.md new file mode 100644 index 000000000..f7bf35f96 --- /dev/null +++ b/docs/notifier.md @@ -0,0 +1,14 @@ +# About DollarSplitBot's notifier.py file +notifier.py is used to send notifications to a Telegram chat. This can be helpful for various purposes, like receiving updates or alerts from a program or service. +# Location of Code for this Feature +The code that implements this feature can be found [here](https://github.com/shonilbhide/dollar_bot/blob/main/code/notifier.py) + +# Code Description +## Functions +- _get_chat_id method: This is a private method within the TelegramNotifier class. It attempts to fetch the chat ID by making an API request to Telegram. The chat ID is essential to send messages to a specific chat or group. If it fails to fetch the chat ID, it sets the chat ID to None and prints an error message. + +- send method: This method is used to send a message to the chat or group associated with the TelegramNotifier object. It takes a msg (message) as an argument, which is the text to be sent. +Before sending the message, it checks if the chat ID is available. If not, it attempts to retrieve it. It constructs a payload containing the chat ID and the message and sends it to the Telegram API. If the message is sent successfully, it prints a success message. If there's an error, it prints an error message. + +# How to run this feature? +This file contains information on the main code.py file from where all features are run. Instructions to run this are the same as instructions to run the project and can be found in README.md. diff --git a/docs/notify.md b/docs/notify.md new file mode 100644 index 000000000..12b61986f --- /dev/null +++ b/docs/notify.md @@ -0,0 +1,19 @@ +# About DollarSplitBot's code.py file +notify.py is is for a program that helps users manage their budgets and sends notifications when they exceed their budget for a specific category. + +# Location of Code for this Feature +The code that implements this feature can be found [here](https://github.com/shonilbhide/dollar_bot/blob/main/code/notify.py) + +# Code Description +## Functions +- notify(chat_id, cat, amount): This function sends a notification on Telegram when the user exceeds their budget for a specific category. It takes three arguments: +chat_id: The user's Telegram chat ID, which helps the program send the notification to the correct user. +cat: The category for which the budget is exceeded (e.g., "Groceries" or "Transportation"). +amount: The amount by which the budget is exceeded. +This function reads some configuration data from a file (specifically, an "api_token"), which is required to send the Telegram notification. Then, it formats a message to inform the user that they've exceeded their budget for a particular category and sends it to the user on Telegram. + +# How to run this feature? +Once the project is running(please follow the instructions given in the main README.md for this), please type /budget into the telegram bot. + + + diff --git a/docs/pdf.md b/docs/pdf.md new file mode 100644 index 000000000..a0bbe41f9 --- /dev/null +++ b/docs/pdf.md @@ -0,0 +1,17 @@ +# About DollarSplitBot's /pdf Feature +The provided code appears to be part of a Python script designed to create PDF documents based on user input in a chat application, possibly a Telegram bot. + +The user can choose a category and add the amount for the budget to be stored in the expense tracker. + +# Location of Code for this Feature +The code that implements this feature can be found [here](https://github.com/shonilbhide/dollar_bot/blob/main/code/pdf.py) + +# Code Description +## Functions + +- run(message, bot): This is the main function for implementing the PDF save feature. It reads some data, displays a menu asking the user what kind of PDF they want to generate, and registers a handler for the user's response. + +- pdfGeneration(message, bot, user_list, user_history): This function generates PDF documents based on user preferences. Depending on the user's choice, it can generate two types of PDF documents: one showing total expenses categorized, and the other showing who owes whom how much. It uses the matplotlib, tabulate, and fpdf libraries to create these PDFs. + +# How to run this feature? +Once the project is running(please follow the instructions given in the main README.md for this), please type /pdf into the telegram bot.