Add docstring and tests for eventsourcing db

.github/workflows/python-package.yml

@@ -36,4 +36,8 @@ jobs:
         flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
     - name: Test with pytest
       run: |
-        python -m pytest
+        python -m pytest --cov=biomero --cov-report=xml
+    - name: Coveralls GitHub Action
+      uses: coverallsapp/github-action@v2.3.0
+
+

biomero/database.py

@@ -1,4 +1,18 @@
-from eventsourcing.utils import get_topic
+# -*- coding: utf-8 -*-
+# Copyright 2024 Torec Luik
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from eventsourcing.utils import get_topic, clear_topic_cache
 import logging
 from sqlalchemy import create_engine, text, Column, Integer, String, URL, DateTime, Float
 from sqlalchemy.orm import sessionmaker, declarative_base, scoped_session
@@ -14,6 +28,14 @@
 
 
 class JobView(Base):
+    """
+    SQLAlchemy model for the 'biomero_job_view' table.
+
+    Attributes:
+        slurm_job_id (Integer): The unique identifier for the Slurm job.
+        user (Integer): The ID of the user who submitted the job.
+        group (Integer): The group ID associated with the job.
+    """
     __tablename__ = 'biomero_job_view'
 
     slurm_job_id = Column(Integer, primary_key=True)
@@ -22,6 +44,14 @@ class JobView(Base):
 
 
 class JobProgressView(Base):
+    """
+    SQLAlchemy model for the 'biomero_job_progress_view' table.
+
+    Attributes:
+        slurm_job_id (Integer): The unique identifier for the Slurm job.
+        status (String): The current status of the Slurm job.
+        progress (String, optional): The progress status of the Slurm job.
+    """
     __tablename__ = 'biomero_job_progress_view'
 
     slurm_job_id = Column(Integer, primary_key=True)
@@ -30,6 +60,20 @@ class JobProgressView(Base):
 
 
 class TaskExecution(Base):
+    """
+    SQLAlchemy model for the 'biomero_task_execution' table.
+
+    Attributes:
+        task_id (PGUUID): The unique identifier for the task.
+        task_name (String): The name of the task.
+        task_version (String): The version of the task.
+        user_id (Integer, optional): The ID of the user who initiated the task.
+        group_id (Integer, optional): The group ID associated with the task.
+        status (String): The current status of the task.
+        start_time (DateTime): The time when the task started.
+        end_time (DateTime, optional): The time when the task ended.
+        error_type (String, optional): Type of error encountered during execution, if any.
+    """
     __tablename__ = 'biomero_task_execution'
 
     task_id = Column(PGUUID(as_uuid=True), primary_key=True)
@@ -44,12 +88,33 @@ class TaskExecution(Base):
 
 
 class EngineManager:
+    """
+    Manages the SQLAlchemy engine and session lifecycle.
+
+    Class Attributes:
+        _engine: The SQLAlchemy engine used to connect to the database.
+        _scoped_session_topic: The topic of the scoped session.
+        _session: The scoped session used for database operations.
+    """
     _engine = None
     _scoped_session_topic = None
     _session = None
 
     @classmethod
-    def create_scoped_session(cls, sqlalchemy_url=None):
+    def create_scoped_session(cls, sqlalchemy_url: str = None):
+        """
+        Creates and returns a scoped session for interacting with the database.
+
+        If the engine doesn't already exist, it initializes the SQLAlchemy engine 
+        and sets up the scoped session.
+
+        Args:
+            sqlalchemy_url (str, optional): The SQLAlchemy database URL. If not provided, 
+                the method will retrieve the value from the 'SQLALCHEMY_URL' environment variable.
+
+        Returns:
+            str: The topic of the scoped session adapter class.
+        """
         if cls._engine is None:      
             # Note, we only allow sqlalchemy eventsourcing module
             if not sqlalchemy_url:
@@ -75,17 +140,33 @@ def __getattribute__(self, item: str) -> None:
 
     @classmethod
     def get_session(cls):
+        """
+        Retrieves the current scoped session.
+
+        Returns:
+            Session: The SQLAlchemy session for interacting with the database.
+        """
         return cls._session()
 
     @classmethod
     def commit(cls):
+        """
+        Commits the current transaction in the scoped session.
+        """
         cls._session.commit()
 
     @classmethod
     def close_engine(cls):
+        """
+        Closes the database engine and cleans up the session.
+
+        This method disposes of the SQLAlchemy engine, removes the session, 
+        and resets all associated class attributes to `None`.
+        """
         if cls._engine is not None:
             cls._session.remove()
             cls._engine.dispose()
             cls._engine = None
             cls._session = None  
             cls._scoped_session_topic = None
+            clear_topic_cache()