Improvements to submission querying.

src/submissions/backend/db/models/__init__.py

@@ -2,8 +2,10 @@
 Contains all models for sqlalchemy
 '''
 import sys
-from sqlalchemy.orm import DeclarativeMeta, declarative_base, Query
+from sqlalchemy.orm import DeclarativeMeta, declarative_base, Query, Session
 from sqlalchemy.ext.declarative import declared_attr
+from typing import Any, List
+from pathlib import Path
 # Load testing environment
 if 'pytest' in sys.modules:
     from pathlib import Path
@@ -11,28 +13,32 @@ if 'pytest' in sys.modules:
 
 Base: DeclarativeMeta = declarative_base()
 
+
 class BaseClass(Base):
     """
     Abstract class to pass ctx values to all SQLAlchemy objects.
-
-    Args:
-        Base (DeclarativeMeta): Declarative base for metadata.
     """
-    __abstract__ = True
+    __abstract__ = True  #: Will not be added to DB
     
-    __table_args__ = {'extend_existing': True} 
+    __table_args__ = {'extend_existing': True}   #: Will only add new columns
 
     @declared_attr
-    def __tablename__(cls):
+    def __tablename__(cls) -> str:
         """
-        Set tablename to lowercase class name
+        Sets table name to lower case class name.
+
+        Returns:
+            str: lower case class name
         """        
         return f"_{cls.__name__.lower()}"
 
     @declared_attr
-    def __database_session__(cls):
+    def __database_session__(cls) -> Session:
         """
-        Pull db session from ctx
+        Pull db session from ctx to be used in operations
+
+        Returns:
+            Session: DB session from ctx settings.
         """        
         if not 'pytest' in sys.modules:
             from tools import ctx
@@ -41,9 +47,12 @@ class BaseClass(Base):
         return ctx.database_session
 
     @declared_attr
-    def __directory_path__(cls):
+    def __directory_path__(cls) -> Path:
         """
-        Pull submission directory from ctx
+        Pull directory path from ctx to be used in operations.
+
+        Returns:
+            Path: Location of the Submissions directory in Settings object
         """        
         if not 'pytest' in sys.modules:
             from tools import ctx
@@ -52,27 +61,31 @@ class BaseClass(Base):
         return ctx.directory_path
     
     @declared_attr
-    def __backup_path__(cls):
+    def __backup_path__(cls) -> Path:
         """
-        Pull backup directory from ctx
+        Pull backup directory path from ctx to be used in operations.
+
+        Returns:
+            Path: Location of the Submissions backup directory in Settings object
         """        
         if not 'pytest' in sys.modules:
             from tools import ctx
         else:
             from test_settings import ctx
         return ctx.backup_path
-    
-    def query_return(query:Query, limit:int=0):
+
+    @classmethod
+    def execute_query(cls, query: Query, limit: int = 0) -> Any | List[Any]:
         """
         Execute sqlalchemy query.
 
         Args:
-            query (Query): Query object
-            limit (int, optional): Maximum number of results to return (0 = all). Defaults to 0.
+            query (Query): input query object
+            limit (int): Maximum number of results. (0 = all)
 
         Returns:
-            _type_: Query result.
-        """    
+            Any | List[Any]: Single result if limit = 1 or List if other.
+        """        
         with query.session.no_autoflush:
             match limit:
                 case 0:
@@ -81,11 +94,11 @@ class BaseClass(Base):
                     return query.first()
                 case _:
                     return query.limit(limit).all()
-    
+
     def save(self):
         """
         Add the object to the database and commit
-        """        
+        """
         # logger.debug(f"Saving object: {pformat(self.__dict__)}")
         try:
             self.__database_session__.add(self)
@@ -94,6 +107,7 @@ class BaseClass(Base):
             logger.critical(f"Problem saving object: {e}")
             self.__database_session__.rollback()
 
+
 from .controls import *
 # import order must go: orgs, kit, subs due to circular import issues
 from .organizations import *