completed documentations

Author: ca20110820

projects/Expense-Tracker/README.md

@@ -1,9 +1,116 @@
-# Expense Tracker App
+# Expense Tracker Application
+
+The Expense Tracker Application is a GUI application built using Python and
+Customtkinter/Tkinter for
+managing expenses. It allows users to add, update, and delete expense items, generate reports in Excel and PDF formats,
+and visualize expense data by category.
+
+---
+
+## Features
+
+- Add, update, and delete expense items.
+- Generate reports in Excel and PDF formats.
+- Visualize expense data by category.
+- User-friendly graphical interface.
+
+---
+
+## Installation
+
+1. Clone the [python-beginner-projects](https://github.com/Mrinank-Bhowmick/python-beginner-projects) repository to your
+   local machine:
+
+   ```
+   git clone https://github.com/Mrinank-Bhowmick/python-beginner-projects.git
+   ```
+
+2. Navigate to the project directory:
+
+   ```
+   cd python-beginner-projects/projects/Expense-Tracker
+   ```
+
+3. Install the required dependencies:
+
+   ```
+   pip install -r requirements.txt
+   ```
+
+---
+
+## Usage
+
+1. Run the application:
+
+   ```
+   python app.py
+   ```
+
+2. The Expense Tracker GUI will open, allowing you to interact with the application.
+
+3. Add, update, or delete expense items using the provided form and buttons.
+
+4. Generate reports by navigating to the "Report" tab and clicking on the respective buttons for Excel or PDF reports.
+
+5. Visualize expense data by navigating to the "Summary By Category" tab.
+
+You can also run the sample using:
+
+```
+python sample.py
+```
+
+which would use dummy data to test the app.
+
+---
+
+## Screenshots
+
+### Adding Item
+
+![Adding Item](media/adding-item.gif)
+
+### Updating Item
+
+![Updating Item](media/updating-items.gif)
+
+### Deleting Items
+
+![Deleting Items](media/deleting-items.gif)
+
+### Viewing Summary Statistics
+
+![Summary Statistics](media/summary-stats.gif)
+
+### Generating Reports
+
+![Generating Reports](media/generating-reports.gif)
+
+### Excel Report
+
+![Excel Report 1](media/report-excel-1.JPG)
+![Excel Report 2](media/report-excel-2.JPG)
+
+### PDF Report
+
+![PDF Report](media/report-pdf.JPG)
+
+
+---
 
 ## Tasks
-- [X] Expense Categorization: This feature allows users to classify their expenses into categories like food, transportation, and entertainment, and provides a summary based on these categories.
+
+- [X] Expense Categorization: This feature allows users to classify their expenses into categories like food,
+  transportation, and entertainment, and provides a summary based on these categories.
 - [X] Date Range Filtering: This feature enables users to filter and view their expenses within a specific date range.
-- [ ] Expense Analysis: This feature offers statistical insights such as the average expense, highest expense, lowest expense, etc.
-- [X] Data Saving and Loading: This feature lets users save their expense data to a file (like CSV or JSON) and load it back when needed.
-- [ ] Data Export to PDF/Excel: This feature enables users to export their expense data to common formats like PDF or Excel for easy sharing or printing.
-- [ ] Currency Converter: For users dealing with multiple currencies, this feature provides an option to convert expenses to a preferred currency.
+- [X] Expense Analysis: This feature offers statistical insights such as the average expense, highest expense, lowest
+  expense, etc.
+- [X] Data Saving and Loading: This feature lets users save their expense data to a file (like CSV or JSON) and load it
+  back when needed.
+- [X] Data Export to PDF/Excel: This feature enables users to export their expense data to common formats like PDF or
+  Excel for easy sharing or printing.
+- [ ] Currency Converter: For users dealing with multiple currencies, this feature provides an option to convert
+  expenses to a preferred currency.
+
+

projects/Expense-Tracker/app.py

@@ -10,6 +10,13 @@
 
 
 class App(ctk.CTk):
+    """
+    Represents the main application for managing expenses.
+
+    This class provides a GUI application for adding, updating, and deleting expense items,
+    generating reports, and visualizing data.
+    """
+
     def __init__(self, db_path, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
@@ -170,19 +177,27 @@ def __init__(self, db_path, *args, **kwargs):
         self.protocol("WM_DELETE_WINDOW", self.on_window_close)
 
     def update_pivot_tables(self):
+        """Updates the pivot tables."""
+
         self.pivot_table.update_pivot_table()
 
     def generate_excel_report(self):
+        """Generates an Excel report."""
+
         excel_path = str(Path(__file__).resolve().parent / 'report.xlsx')
         report = ExcelReport(excel_path, self._items_db)
         report.generate_report()
 
     def generate_pdf_report(self):
+        """Generates a PDF report."""
+
         pdf_path = str(Path(__file__).resolve().parent / 'report.pdf')
         report = PdfReport(pdf_path, self._items_db)
         report.generate_report()
 
     def on_window_close(self):
+        """Callback for window close event."""
+
         # Reference: https://stackoverflow.com/questions/111155/how-do-i-handle-the-window-close-event-in-tkinter
         print('Window Closing ...')
         self.destroy()
@@ -199,6 +214,8 @@ def _get_form_values(self):
         }
 
     def clear_form(self):
+        """Clears the form."""
+
         self.entry_name.delete(0, last_index=len(self.entry_name.get()))
         self.entry_amount.delete(0, last_index=len(self.entry_amount.get()))
         self.entry_description.delete(0, last_index=len(self.entry_description.get()))
@@ -207,6 +224,8 @@ def clear_form(self):
         self.entry_subcategory.delete(0, last_index=len(self.entry_subcategory.get()))
 
     def fill_form(self, name, amount, description, date, category='None', subcategory='None'):
+        """Fills the form with provided values."""
+
         self.clear_form()
         self.entry_name.insert(0, name)
         self.entry_amount.insert(0, amount)
@@ -216,6 +235,8 @@ def fill_form(self, name, amount, description, date, category='None', subcategor
         self.entry_subcategory.insert(0, subcategory)
 
     def on_btn_add_clicked(self):
+        """Callback for add button click event."""
+
         new_item = self._create_item_from_form()
 
         if new_item is not None:
@@ -226,6 +247,8 @@ def on_btn_add_clicked(self):
         self.clear_form()
 
     def on_btn_update_clicked(self):
+        """Callback for update button click event."""
+
         # Get the (one) selected item
         selected_item = self.items_table.focus()
         item_dct = self.items_table.item(selected_item)
@@ -260,6 +283,8 @@ def on_btn_update_clicked(self):
         self.clear_form()
 
     def on_btn_delete_clicked(self):
+        """Callback for delete button click event."""
+
         yes_or_no = messagebox.askyesno("Delete Item", "Do you want to continue?")
 
         if not yes_or_no:
@@ -279,7 +304,13 @@ def on_btn_delete_clicked(self):
         self.items_table.deletes_item(item_objs)
 
     def _create_item(self, inp_item):
-        # inp_item: List[str|int|float]
+        """
+        Creates an item from input.
+
+        Args:
+            inp_item (List[str|int|float]): List representing an item.
+        """
+
         try:
             item_id = inp_item[0]
             item_name = inp_item[1]
@@ -314,6 +345,8 @@ def _create_item(self, inp_item):
             return None
 
     def _create_item_from_form(self) -> Item | None:
+        """Creates an item from the form."""
+
         try:
             if self.entry_category.get().strip() in ['None', '']:
                 category = None
@@ -338,6 +371,8 @@ def _create_item_from_form(self) -> Item | None:
             return None
 
     def on_row_selected(self, e):
+        """Callback for row selection event."""
+
         # Reference: https://stackoverflow.com/questions/30614279/tkinter-treeview-get-selected-item-values
 
         # Reference: For Multiple Selected Rows