Feature/bcss 20437 fit kit gen util markdown and docstring

docs/utility-guides/FitKitGeneration.md

@@ -0,0 +1,68 @@
+# Utility Guide: Fit Kit Generation
+
+The Fit Kit Generation Utility provides methods to generate and manage FIT test kits for testing purposes.
+
+## Table of Contents
+
+- [Utility Guide: Fit Kit Generation](#utility-guide-fit-kit-generation)
+  - [Table of Contents](#table-of-contents)
+  - [Using the Fit Kit Generation Utility](#using-the-fit-kit-generation-utility)
+  - [Required Arguments](#required-arguments)
+  - [Fit Kit Generation Specific Functions](#fit-kit-generation-specific-functions)
+  - [Example Usage](#example-usage)
+
+## Using the Fit Kit Generation Utility
+
+To use the Fit Kit Generation Utility, import the `fit_kit_generation` module, from the `utils` directory, into your test file and call its methods from within your tests, as required. To generate the fit kit IDs, the only method required is `create_fit_id_df`. This will return a `dataframe` with all the transformations already taking place.
+
+## Required Arguments
+
+The methods in this utility require specific arguments. Below is a summary of the required arguments for key methods:
+
+- `generate_kit`: Requires `batch_id` (int) and `kit_type` (str).
+
+## Fit Kit Generation Specific Functions
+
+The Fit Kit Generation Utility includes methods for generating, validating, and managing FIT test kits. These methods are designed to streamline the process of creating test kits for various scenarios. Below are some key functions:
+
+1. **`create_fit_id_df(tk_type_id: int, hub_id: int, no_of_kits: int) -> DataFrame`**
+   Creates a DataFrame containing FIT kit IDs based on the provided parameters.
+   - **Arguments**:
+     - `tk_type_id` (int): The type ID of the test kit.
+     - `hub_id` (int): The hub ID associated with the kits.
+     - `no_of_kits` (int): The number of kits to retrieve.
+   - **Returns**: A pandas DataFrame with the FIT kit IDs.
+
+2. **`calculate_check_digit(kit_id: str) -> str`**
+   Calculates and appends a check digit to the given kit ID.
+   - **Arguments**:
+     - `kit_id` (str): The kit ID to process.
+   - **Returns**: The kit ID with the appended check digit.
+
+3. **`convert_kit_id_to_fit_device_id(kit_id: str) -> str`**
+   Converts a kit ID into a FIT Device ID.
+   - **Arguments**:
+     - `kit_id` (str): The kit ID to convert.
+   - **Returns**: The corresponding FIT Device ID.
+
+## Example Usage
+
+```python
+from utils.fit_kit_generation import create_fit_id_df, calculate_check_digit, convert_kit_id_to_fit_device_id
+
+def example_usage() -> None:
+    # Example inputs
+    tk_type_id = 1
+    hub_id = 101
+    no_of_kits_to_retrieve = 2
+
+    # Calling the fit_kit_df method will do the following:
+      # Step 1: Retrieve and process FIT kit data
+      # Step 2: Calculate a check digit for a single kit ID
+      # Step 3: Convert a kit ID to a FIT Device ID
+
+    fit_kit_df = create_fit_id_df(tk_type_id, hub_id, no_of_kits_to_retrieve)
+    print("Processed FIT Kit DataFrame:")
+    print(fit_kit_df)
+
+example_usage()

utils/fit_kit_generation.py

@@ -8,9 +8,25 @@ def create_fit_id_df(
     tk_type_id: int, hub_id: int, no_of_kits_to_retrieve: int
 ) -> pd.DataFrame:
     """
-    The first step here is to get the relevant test data for compartment 2
-    Then it calculates the check digit for each kit id retrieved
-    Finally it adds the final part on the end (expiry date + random characters)
+    This function retrieves test kit data from the database for the specified compartment (using the 'get_kit_id_from_db' function from 'oracle_specific_functions.py').
+    It then calculates a check digit for each retrieved kit ID and appends it to the kit ID.
+    Finally, it generates a FIT Device ID by appending an expiry date and a fixed suffix to the kit ID.
+
+    For example:
+        Given the following inputs:
+            tk_type_id = 1, hub_id = 101, no_of_kits_to_retrieve = 2
+        The function retrieves two kit IDs from the database, e.g., ["ABC123", "DEF456"].
+        It calculates the check digit for each kit ID, resulting in ["ABC123-K", "DEF456-M"].
+        Then, it generates the FIT Device IDs, e.g., ["ABC123-K122512345/KD00001", "DEF456-M122512345/KD00001"].
+
+    Args:
+        tk_type_id (int): The type ID of the test kit.
+        hub_id (int): The ID of the hub from which to retrieve the kits.
+        no_of_kits_to_retrieve (int): The number of kits to retrieve from the database.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing the processed kit IDs, including the calculated check digit
+        and the final formatted FIT Device ID.
     """
     df = get_kit_id_from_db(tk_type_id, hub_id, no_of_kits_to_retrieve)
     df["fit_device_id"] = df["kitid"].apply(calculate_check_digit)
@@ -20,11 +36,23 @@ def create_fit_id_df(
 
 def calculate_check_digit(kit_id: str) -> str:
     """
-    This function used used to calculate the check digit of a kit ID
-    It calculates the check digit by getting the sum of the location of each character in the kit id
-    Then it divides the sum by 43 and gets the remainder from this
-    It then searches the string "char_string" to find the index of the remainder
-    The character found is then the check digit
+    Calculates the check digit for a given kit ID.
+
+    The check digit is determined by summing the positions of each character in the kit ID
+    within a predefined character set. The remainder of the sum divided by 43 is used to
+    find the corresponding character in the character set, which becomes the check digit.
+
+    For example:
+        Given the kit ID "ABC123", the positions of the characters in the predefined
+        character set are summed. If the total is 123, the remainder when divided by 43
+        is 37. The character at position 37 in the character set is "K". The resulting
+        kit ID with the check digit appended would be "ABC123-K".
+
+    Args:
+        kit_id (str): The kit ID to calculate the check digit for.
+
+    Returns:
+        str: The kit ID with the calculated check digit appended.
     """
     logging.info(f"Calculating check digit for kit id: {kit_id}")
     total = 0
@@ -37,10 +65,17 @@ def calculate_check_digit(kit_id: str) -> str:
 
 def convert_kit_id_to_fit_device_id(kit_id: str) -> str:
     """
-    This is used to add the expiry date to the end of the Kit ID
-    This by setting the month to december
-    And the year is set to 1 year in the future.
-    E.g. if the current date is 06/24 the expiry date will be set to 12/25
+    Converts a Kit ID into a FIT Device ID by appending an expiry date and a fixed suffix.
+
+    The expiry date is calculated by setting the month to December and the year to one year
+    in the future based on the current date. For example, if the current date is June 2024,
+    the expiry date will be set to December 2025.
+
+    Args:
+        kit_id (str): The Kit ID to be converted.
+
+    Returns:
+        str: The generated FIT Device ID in the format "{kit_id}12{next_year}12345/KD00001".
     """
     logging.info(f"Generating FIT Device ID from: {kit_id}")
     today = datetime.now()