Adding Oracle markdown doc and docstrings and fixing spelling

Author: adrianoaru-nhs

docs/utility-guides/Oracle.md

@@ -0,0 +1,68 @@
+# Utility Guide: Oracle
+
+The Oracle Utility can be used to run SQL queries or stored procedures on the Oracle database.
+
+## Table of Contents
+
+- [Utility Guide: Oracle](#utility-guide-oracle)
+  - [Table of Contents](#table-of-contents)
+  - [Using the Oracle Utility](#using-the-oracle-utility)
+  - [Required arguments](#required-arguments)
+  - [Example usage](#example-usage)
+  - [Oracle Specific Functions](#oracle-specific-functions)
+  - [Example Usage](#example-usage-1)
+
+## Using the Oracle Utility
+
+To use the Oracle Utility, import the 'OracleDB' class into your test file and then call the DateTimeUtils
+methods from within your tests, as required.
+
+## Required arguments
+
+The functions in this class require different arguments.<br>
+Look at the docstrings for each function to see what arguments are required.<br>
+The docstrings also specify when arguments are optional, and what the default values are when no argument is provided.
+
+## Example usage
+
+    from utils.oracle.oracle import OracleDB
+
+    def test_oracle_query() -> None:
+
+        query = """select column_a,
+        column_b,
+        column_c
+        from example_table
+        where condition_1 = :condition1
+        and condition_2 = :condition2"""
+
+        params = {
+        "condition1": 101,
+        "condition2": 202,
+        }
+
+        result_df = OracleDB().execute_query(query, params)
+
+    def run_stored_procedure() -> None:
+
+        OracleDB().execute_stored_procedure("bcss_timed_events")
+
+## Oracle Specific Functions
+
+This contains SQL queries that can be used to run tests.<br>
+These are all stored in one location to make it easier to edit the query at a later date and to make it accessible to multiple tests.
+
+Common values are placed in the `SqlQueryValues` class to avoid repeating the same values in the queries.
+
+## Example Usage
+
+    from oracle.oracle import OracleDB
+
+    def example_query() -> pd.DataFrame:
+
+        example_df = OracleDB().execute_query(
+            f"""subject_nhs_number
+        from ep_subject_episode_t
+        where se.latest_event_status_id in ({SqlQueryValues.S10_EVENT_STATUS}, {SqlQueryValues.S19_EVENT_STATUS})""")
+
+        return example_df

tests/smokescreen/bcss_smokescreen_tests.properties

@@ -20,7 +20,7 @@
     c3_fit_kit_normal_result=75
     c3_fit_kit_abnormal_result=150
     c3_fit_kit_analyser_code=UU2_tdH3
-    c3_total_fit_kits_to_retieve=9
+    c3_total_fit_kits_to_retrieve=9
     c3_fit_kit_authorised_user=AUTO1
 
 # ----------------------------------

utils/oracle/oracle.py

@@ -16,6 +16,9 @@ def __init__(self):
     def connect_to_db(self) -> oracledb.Connection:
         """
         This function is used to connect to the Oracle DB. All the credentials are retrieved from a .env file
+
+        Returns:
+            conn (oracledb.Connection): The Oracle DB connection object
         """
         try:
             logging.info("Attempting DB connection...")
@@ -29,17 +32,26 @@ def connect_to_db(self) -> oracledb.Connection:
                 f"Failed to to extract subject ID with error: {queryExecutionError}"
             )
 
-    def disconnect_from_db(self, conn) -> None:
+    def disconnect_from_db(self, conn: oracledb.Connection) -> None:
+        """
+        Disconnects from the DB
+
+        Args:
+            conn (oracledb.Connection): The Oracle DB connection object
+        """
         conn.close()
         logging.info("Connection Closed")
 
     def exec_bcss_timed_events(
-        self, nhs_number_df
+        self, nhs_number_df: pd.DataFrame
     ) -> None:  # Executes bcss_timed_events when given NHS numbers
         """
-        this function is used to execute bcss_timed_events against NHS Numbers.
+        This function is used to execute bcss_timed_events against NHS Numbers.
         It expects the nhs_numbers to be in a dataframe, and runs a for loop to get the subject_screening_id for each nhs number
         Once a subject_screening_id is retrieved, it will then run the command: exec bcss_timed_events [<subject_id>,'Y']
+
+        Args:
+            nhs_number_df (pd.DataFrame): A dataframe containing all of the NHS numbers as separate rows
         """
         conn = self.connect_to_db()
         try:
@@ -66,9 +78,15 @@ def exec_bcss_timed_events(
             if conn is not None:
                 self.disconnect_from_db(conn)
 
-    def get_subject_id_from_nhs_number(self, nhs_number) -> str:
+    def get_subject_id_from_nhs_number(self, nhs_number: str) -> str:
         """
         This function is used to obtain the subject_screening_id of a subject when given an nhs number
+
+        Args:
+            nhs_number (str): The NHS number of the subject
+
+        Returns:
+            subject_id (str): The subject id for the provided nhs number
         """
         conn = self.connect_to_db()
         logging.info(f"Attempting to get subject_id from nhs number: {nhs_number}")
@@ -86,6 +104,9 @@ def populate_ui_approved_users_table(
     ) -> None:  # To add users to the UI_APPROVED_USERS table
         """
         This function is used to add a user to the UI_APPROVED_USERS table
+
+        Args:
+            user (str): The user you want to add to the table
         """
         conn = self.connect_to_db()
         try:
@@ -131,11 +152,22 @@ def execute_query(
         """
         This is used to execute any sql queries.
         A query is provided and then the result is returned as a pandas dataframe
+
+        Args:
+            query (str): The SQL query you wish to run
+            parameters (list | None): Optional - Any parameters you want to pass on in a list
+
+        Returns:
+            df (pd.DataFrame): A pandas dataframe of the result of the query
         """
         conn = self.connect_to_db()
         engine = create_engine("oracle+oracledb://", creator=lambda: conn)
         try:
-            df = pd.read_sql(query, engine) if parameters == None else pd.read_sql(query, engine, params = parameters)
+            df = (
+                pd.read_sql(query, engine)
+                if parameters == None
+                else pd.read_sql(query, engine, params=parameters)
+            )
         except Exception as executionError:
             logging.error(
                 f"Failed to execute query with execution error {executionError}"
@@ -151,6 +183,9 @@ def execute_stored_procedure(
         """
         This is to be used whenever we need to execute a stored procedure.
         It is provided with the stored procedure name and then executes it
+
+        Args:
+            procedure (str): The stored procedure you want to run
         """
         conn = self.connect_to_db()
         try:
@@ -168,11 +203,15 @@ def execute_stored_procedure(
                 self.disconnect_from_db(conn)
 
     def update_or_insert_data_to_table(
-        self, statement, params
+        self, statement: str, params: list
     ) -> None:  # To update or insert data into a table
         """
         This is used to update or insert data into a table.
         It is provided with the SQL statement along with the arguments
+
+        Args:
+            statement (str): The SQL query you wish to run
+            params (list | None): Any parameters you want to pass on in a list
         """
         conn = self.connect_to_db()
         try:

utils/oracle/oracle_specific_functions.py

@@ -19,10 +19,14 @@ def get_kit_id_from_db(
 ) -> pd.DataFrame:
     """
     This query is used to obtain test kits used in compartment 2
-    It searches for kits that have not been logged and meet the following criteria:
-    - tk.tk_type_id = 2 (Only FIT Kits)
-    - sdc.hub_id = 23159 (Hub ID that the compartments are running in)
-    - se.latest_event_status_id is 11198 or 11213 (Only kits at the status we want S10/S19 are retrieved)
+
+    Args:
+        tk_type_id (int): The id of the kit type
+        hub_id (int): The hub ID of the screening center
+        no_of_kits_to_retrieve (int): The amount of kits you want to retrieve
+
+    Returns:
+        kit_id_df (pd.DataFrame): A pandas DataFrame containing the result of the query
     """
     logging.info("Retrieving useable test kit ids")
     kit_id_df = OracleDB().execute_query(
@@ -43,10 +47,16 @@ def get_kit_id_from_db(
     return kit_id_df
 
 
-def get_nhs_no_from_batch_id(batch_id) -> pd.DataFrame:
+def get_nhs_no_from_batch_id(batch_id: str) -> pd.DataFrame:
     """
     This query returns a dataframe of NHS Numbers of the subjects in a certain batch
     We provide the batch ID e.g. 8812 and then we have a list of NHS Numbers we can verify the statuses
+
+    Args:
+        batch_id (str): The batch ID you want to get the subjects from
+
+    Returns:
+        nhs_number_df (pd.DataFrame): A pandas DataFrame containing the result of the query
     """
     nhs_number_df = OracleDB().execute_query(
         f"""
@@ -66,9 +76,12 @@ def get_nhs_no_from_batch_id(batch_id) -> pd.DataFrame:
 def get_kit_id_logged_from_db(smokescreen_properties: dict) -> pd.DataFrame:
     """
     This query is used to obtain test data used in compartment 3
-    It searches for kits that have not been logged and meet the following criteria:
-    - tk.tk_type_id = 2 (Only FIT Kits)
-    - tk.logged_in_at = 23159 (Hub ID that the compartments are running in)
+
+    Args:
+        smokescreen_properties(): A dictionary containing all values needed to run the query
+
+    Returns:
+        return kit_id_df (pd.DataFrame): A pandas DataFrame containing the result of the query
     """
     kit_id_df = OracleDB().execute_query(
         f"""SELECT tk.kitid,tk.device_id,tk.screening_subject_id
@@ -83,7 +96,7 @@ def get_kit_id_logged_from_db(smokescreen_properties: dict) -> pd.DataFrame:
     AND tk.logged_in_at = {smokescreen_properties["c3_fit_kit_results_test_org_id"]}
     AND tk.reading_flag = 'N'
     AND tk.test_results IS NULL
-    fetch first {smokescreen_properties["c3_total_fit_kits_to_retieve"]} rows only
+    fetch first {smokescreen_properties["c3_total_fit_kits_to_retrieve"]} rows only
     """
     )
 
@@ -93,6 +106,12 @@ def get_kit_id_logged_from_db(smokescreen_properties: dict) -> pd.DataFrame:
 def get_service_management_by_device_id(device_id: str) -> pd.DataFrame:
     """
     This SQL is similar to the one used in pkg_test_kit_queue.p_get_fit_monitor_details, but adapted to allow us to pick out sub-sets of records
+
+    Args:
+        device_id (str): The device ID
+
+    Returns:
+        get_service_management_df (pd.DataFrame): A pandas DataFrame containing the result of the query
     """
 
     query = """SELECT kq.device_id, kq.test_kit_name, kq.test_kit_type, kq.test_kit_status,
@@ -136,6 +155,14 @@ def update_kit_service_management_entity(
     """
     This method is used to update the KIT_QUEUE table on the DB
     This is done so that we can then run two stored procedures to update the subjects and kits status to either normal or abnormal
+
+    Args:
+        device_id (str): The device ID
+        normal (bool): Whether the device should be marked as normal or abnormal
+        smokescreen_properties(): A dictionary containing all values needed to run the query
+
+    Returns:
+        subject_nhs_number (str): The NHS Number of the affected subject
     """
     get_service_management_df = get_service_management_by_device_id(device_id)
 
@@ -229,6 +256,12 @@ def get_subjects_for_appointments(subjects_to_retrieve: int) -> pd.DataFrame:
     This is used to get subjects for compartment 4
     It finds subjects with open episodes and the event status A8
     It also checks that the episode is less than 2 years old
+
+    Args:
+        subjects_to_retrieve (int): The number of subjects to retrieve
+
+    Returns:
+        subjects_df (pd.DataFrame): A pandas DataFrame containing the result of the query
     """
     subjects_df = OracleDB().execute_query(
         f"""
@@ -257,6 +290,12 @@ def get_subjects_with_booked_appointments(subjects_to_retrieve: int) -> pd.DataF
     This is used to get subjects for compartment 5
     It finds subjects with appointments book and letters sent
     and makes sure appointments are prior to todays date
+
+    Args:
+        subjects_to_retrieve (int): The number of subjects to retrieve
+
+    Returns:
+        subjects_df (pd.DataFrame): A pandas DataFrame containing the result of the query
     """
     subjects_df = OracleDB().execute_query(
         f"""