Reviewed comments and type hints

src/datatypes.py

@@ -1,10 +1,22 @@
+"""
+This file contains all the code to load the business/private datatypes from the database and interact with them.
+i.e. the product categories, products, reviews etc.... including utility methods to find them, render them etc...
+It is all implemented as a very simple read-only Object-Relational mapping type layer to grant access to read and
+use the data in the database.  DB updates are all done by offline processes and the data setup.
+"""
+
+from __future__ import annotations  # For referencing own class
+
 import sqlite3
-from typing import List
+from typing import List, Dict
 
 from src.common import *
 
 
 class DataLoader:
+    """
+    Class which controls the loading of all the data in the system from the database
+    """
     active_db = "02_baseline_products_dataset"
     db_dir = os.path.join(data_dir, 'sqlite')
     db_file = os.path.join(db_dir, f"{active_db}.db")
@@ -12,6 +24,9 @@ class DataLoader:
 
     @classmethod
     def set_db_name(cls, name: str):
+        """
+        Programatically switch the database in use.
+        """
         if name != cls.active_db:
             new_file = os.path.join(data_dir, 'sqlite', f"{name}.db")
             cls.db_file = os.path.join(DataLoader.db_dir, f"{name}.db")
@@ -20,14 +35,26 @@ class DataLoader:
 
     @staticmethod
     def current_db() -> str:
+        """
+        Get the name of the current database in use
+        """
         return DataLoader.active_db[:-3]
 
     @staticmethod
     def available_dbs() -> List[str]:
+        """
+        Get the names of all the available databases in the sqlite folder
+        """
         return [f[:-3] for f in os.listdir(DataLoader.db_dir) if ('products' in f) and f.endswith('.db')]
 
     @staticmethod
     def load_data(reload=False):
+        """
+        Load (or reload) all the data classes across the system from the database. Fills out all the
+        class variables holding the list of all of each type, and then completes also the cross-references
+        between objects so they are aware of each other (e.g. putting reviews into products and linking the reviews
+        to their products)
+        """
         if DataLoader.loaded and not reload:
             return
 
@@ -71,16 +98,26 @@ class DataLoader:
 
 
 class Category:
-    all = {}
+    """
+    A category of products (e.g. "Dishwashers"). Holds also a list of Features relevant to this
+    category and a list of Products in this category
+    """
+    all: Dict[str, Category] = {}  # All categories by ID
 
     @staticmethod
-    def all_sorted():
+    def all_sorted() -> List[Category]:
+        """
+        Gets a list of all the catgories, sorted by name
+        """
         all_cats = list(Category.all.values())
         all_cats.sort(key=lambda x: x.name)
         return all_cats
 
     @staticmethod
-    def by_name(name: str):
+    def by_name(name: str) -> Category:
+        """
+        Look up a single category by name
+        """
         all_cats = list(Category.all.values())
         for c in all_cats:
             if c.name == name:
@@ -93,28 +130,37 @@ class Category:
         self.products = []
 
     @property
-    def feature_count(self):
+    def feature_count(self) -> int:
         return len(self.features)
 
     @property
-    def product_count(self):
+    def product_count(self) -> int:
         return len(self.products)
 
     @property
-    def singular_name(self):
+    def singular_name(self) -> str:
+        """
+        Get the name of this category, stripping the trailing s if there is one
+        """
         if self.name[-1] == "s":
             return self.name[:-1]  # Clip the s
         return self.name
 
     @property
     def lower_singular_name(self):
+        """
+        Get the name of this ctaegory in lower case, removing any trailing s
+        """
         if self.name[-1] == "s":
             return self.name[:-1].lower()  # Clip the s
         return self.name.lower()
 
 
 class Feature:
-    all = {}
+    """
+    A feature available to Products in a given Category (e.g. "Quiet operation")
+    """
+    all: Dict[str, Feature] = {}  # All features by ID
 
     def __init__(self, id, name, category):
         self.id = id
@@ -123,15 +169,19 @@ class Feature:
         self.products = []
 
     @property
-    def product_count(self):
+    def product_count(self) -> int:
         return len(self.products)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return self.name
 
 
 class Product:
-    all = {}
+    """
+    A product specification with its price, description, features, and a list of associated
+    customer reviews.
+    """
+    all: Dict[str, Product] = {}  # All products by ID
 
     def __init__(self, id, name, description, price, category):
         self.id = id
@@ -143,30 +193,36 @@ class Product:
         self.reviews = []
 
     @property
-    def feature_count(self):
+    def feature_count(self) -> int:
         return len(self.features)
 
     @property
-    def review_count(self):
+    def review_count(self) -> int:
         return len(self.reviews)
 
     @property
-    def average_rating(self, decimals=2):
+    def average_rating(self, decimals=2) -> float:
         if self.review_count == 0:
             return 0.0
         return float(round(sum([r.rating for r in self.reviews]) / self.review_count, decimals))
 
     @staticmethod
-    def for_ids(ids: List[str]):
+    def for_ids(ids: List[str]) -> List[Product]:
+        """
+        Get a set of products based on a set of IDs
+        """
         return[Product.all[i] for i in ids]
 
     @staticmethod
-    def all_as_list():
+    def all_as_list() -> List[Product]:
         return list(Product.all.values())
 
 
 class Review:
-    all = {}
+    """
+    A single customer review with its star rating and the review text
+    """
+    all: Dict[str, Review] = {}
 
     def __init__(self, id, rating, review_text, product):
         self.id = id