wip - updated docstrings and added a new file - FitKitGeneration.md

Author: Andyg79

docs/utility-guides/FitKitGeneration.md

@@ -0,0 +1,68 @@
+# Utility Guide: FitKitGeneration
+
+The FitKitGeneration Utility provides methods to generate and manage FIT test kits for screening purposes.
+
+## Table of Contents
+
+- [Utility Guide: FitKitGeneration](#utility-guide-fitkitgeneration)
+  - [Table of Contents](#table-of-contents)
+  - [Using the FitKitGeneration Utility](#using-the-fitkitgeneration-utility)
+  - [Required Arguments](#required-arguments)
+  - [Example Usage](#example-usage)
+  - [FitKitGeneration Specific Functions](#fitkitgeneration-specific-functions)
+
+## Using the FitKitGeneration Utility
+
+To use the fit_kit_generation Utility, import the `fit_kit_generation` module into your test file and call it's methods from within your tests, as required
+
+## Required Arguments
+
+The methods in this utility require specific arguments. Refer to the docstrings in the `fit_kit_generation.py` file for details on required and optional arguments.
+
+## Example Usage
+
+from utils.fit_kit_generation import FitKitGenerator
+
+def test_generate_fit_kit() -> None:
+    fit_kit = FitKitGenerator().generate_kit(batch_id=12345, kit_type="Standard")
+    assert fit_kit is not None
+
+## FitKitGeneration Specific Functions
+
+The FitKitGeneration 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. **`generate_kit(batch_id: int, kit_type: str) -> dict`**  
+   Generates a FIT test kit with the specified batch ID and kit type.  
+   - **Arguments**:
+     - `batch_id` (int): The ID of the batch to which the kit belongs.
+     - `kit_type` (str): The type of kit to generate (e.g., "Standard", "Advanced").
+   - **Returns**: A dictionary containing the details of the generated kit.
+
+2. **`validate_kit(kit_id: int) -> bool`**  
+   Validates a FIT test kit by its ID.  
+   - **Arguments**:
+     - `kit_id` (int): The ID of the kit to validate.
+   - **Returns**: `True` if the kit is valid, `False` otherwise.
+
+3. **`manage_kits(action: str, kit_ids: list[int]) -> None`**  
+   Performs bulk actions on a list of FIT test kits.  
+   - **Arguments**:
+     - `action` (str): The action to perform (e.g., "activate", "deactivate").
+     - `kit_ids` (list[int]): A list of kit IDs to apply the action to.
+
+## Example Usage
+
+    from utils.fit_kit_generation import FitKitGenerator
+
+    def test_fit_kit_functions() -> None:
+        # Generate a new FIT kit
+        fit_kit = FitKitGenerator().generate_kit(batch_id=12345, kit_type="Standard")
+        assert fit_kit["kit_type"] == "Standard"
+
+        # Validate the generated kit
+        is_valid = FitKitGenerator().validate_kit(kit_id=fit_kit["kit_id"])
+        assert is_valid
+
+        # Manage multiple kits
+        FitKitGenerator().manage_kits(action="activate", kit_ids=[fit_kit["kit_id"]])
+        

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()