Feature/bcss 20438 fit kit logged docstrings and md (#57)

<!-- markdownlint-disable-next-line first-line-heading -->
## Description
Updated docstrings for fit kit logged functions and added a utility
guide

<!-- Describe your changes in detail. -->

## Context
Updated docstrings for fit kit logged functions and added a utility
guide for better usability of functions and to make it easier for new
testers to work with our framework.


<!-- Why is this change required? What problem does it solve? -->

## Type of changes

<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply. -->

- [x] Refactoring (non-breaking change)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would change existing
functionality)
- [ ] Bug fix (non-breaking change which fixes an issue)

## Checklist

<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->

- [x] I am familiar with the [contributing
guidelines](https://github.com/nhs-england-tools/playwright-python-blueprint/blob/main/CONTRIBUTING.md)
- [x] I have followed the code style of the project
- [ ] I have added tests to cover my changes (where appropriate)
- [x] I have updated the documentation accordingly
- [ ] This PR is a result of pair or mob programming

---

## Sensitive Information Declaration

To ensure the utmost confidentiality and protect your and others
privacy, we kindly ask you to NOT including [PII (Personal Identifiable
Information) / PID (Personal Identifiable
Data)](https://digital.nhs.uk/data-and-information/keeping-data-safe-and-benefitting-the-public)
or any other sensitive data in this PR (Pull Request) and the codebase
changes. We will remove any PR that do contain any sensitive
information. We really appreciate your cooperation in this matter.

- [x] I confirm that neither PII/PID nor sensitive data are included in
this PR and the codebase changes.

---------

Co-authored-by: adrianoaru-nhs <[email protected]>
Co-authored-by: Adriano Aru <[email protected]>

Author: Andyg79

docs/utility-guides/FitKitLogged.md

@@ -0,0 +1,71 @@
+# Utility Guide: Fit Kit Logged Utility
+
+The Fit Kit Logged Utility provides methods to retrieve test data (fit kit test results) used by the compartment 3 tests, and splits them into two dataframes (one 'normal', one 'abnormal').
+
+## Table of Contents
+
+- [Utility Guide: Fit Kit Logged Utility](#utility-guide-fit-kit-logged-utility)
+  - [Table of Contents](#table-of-contents)
+  - [Using the Fit Kit Logged Utility](#using-the-fit-kit-logged-utility)
+  - [Required Arguments](#required-arguments)
+  - [Fit Kit Logged Specific Functions](#fit-kit-logged-specific-functions)
+  - [Example Usage](#example-usage)
+
+## Using the Fit Kit Logged Utility
+
+To use the Fit Kit Logged Utility, import the `fit_kit_logged.py` module, from the `utils` directory, into your test file and call the `process_kit_data` method as required.
+
+## Required Arguments
+
+The methods in this utility require specific arguments. Below is a summary of the required arguments for key methods:
+
+- `process_kit_data`: Requires `smokescreen_properties`(dict)
+- `split_fit_kits`: Requires `kit_id_df`(pd.DataFrame), `smokescreen_properties`(dict)
+
+## Fit Kit Logged Specific Functions
+
+The `fit_kit_logged` Utility includes methods for retrieving FIT test kits from the DB and splitting them into 'Normal' and 'Abnormal' results. Below are their key functions:
+
+1. **`process_kit_data(smokescreen_properties: dict) -> list`**
+Retrieves the test data needed for compartment 3 and then splits it into two data frames, using the `split_fit_kits` method.
+
+- **Arguments**:
+  - `smokescreen_properties` (dict): A dictionary containing properties required to retrieve and process kit data.
+
+- **Returns**:
+  A list of tuples where each tuple contains a device ID (str) and a `boolean` flag (True for normal, False for abnormal).
+
+1. **`split_fit_kits(kit_id_df: pd.DataFrame, smokescreen_properties: dict) -> tuple`**
+This method splits the `dataframe` into two dataframes, one normal and one abnormal. It determines the number of normal and abnormal kits by using the `c3_eng_number_of_normal_fit_kits` parameter from `smokescreen_properties` for the number of normal, and then the rest are marked as abnormal.
+
+- **Arguments**:
+  - `kit_id_df` (pd.DataFrame): A `dataframe` containing fit kit IDs.
+  - `smokescreen_properties` (dict): A dictionary containing the number of normal and abnormal fit kits to split.
+
+- **Returns**:
+  A tuple containing two dataframes:
+  - `normal_fit_kit_df` (pd.DataFrame): `dataframe` containing normal fit kits.
+  - `abnormal_fit_kit_df` (pd.DataFrame): `dataframe` containing abnormal fit kits.
+
+## Example Usage
+
+```python
+from utils.fit_kit_logged import process_kit_data
+
+def test_example_usage(smokescreen_properties: dict) -> None:
+    # Find data, separate it into normal and abnormal, add results to the test records in the KIT_QUEUE table (i.e. mimic receiving results from the middleware) and get device IDs and their flags.
+    device_ids = process_kit_data(smokescreen_properties)
+    # Note: In this example, all of the code below this line is for context only and uses functions from other utilities.
+    # Retrieve NHS numbers for each device_id and determine normal/abnormal status
+    nhs_numbers = []
+    normal_flags = []
+
+    for device_id, is_normal in device_ids:
+        nhs_number = update_kit_service_management_entity(
+            device_id, is_normal, smokescreen_properties
+        )
+        nhs_numbers.append(nhs_number)
+        normal_flags.append(is_normal)  # Store the flag (True for normal, False for abnormal).
+
+test_example_usage()
+```

utils/fit_kit_logged.py

@@ -1,4 +1,3 @@
-from oracle.oracle import OracleDB
 from oracle.oracle_specific_functions import get_kit_id_logged_from_db
 import pandas as pd
 import logging
@@ -7,11 +6,17 @@
 
 def process_kit_data(smokescreen_properties: dict) -> list:
     """
-    This method retrieved the test data needed for compartment 3 and then splits it into two data frames:
+    This method retrieves the test data needed for compartment 3 and then, by using the split_fit_kits method, it splits it into two data frames:
     - 1 normal
     - 1 abnormal
+
     Once the dataframe is split in two it then creates two lists, one for normal and one for abnormal
     Each list will either have true or false appended depending on if it is normal or abnormal
+    Args:
+        smokescreen_properties (dict): A dictionary containing properties required to retrieve and process kit data.
+
+    Returns:
+        list: A list of tuples where each tuple contains a device ID (str) and a boolean flag (True for normal, False for abnormal).
     """
     # Get test data for compartment 3
     kit_id_df = get_kit_id_logged_from_db(smokescreen_properties)
@@ -48,9 +53,22 @@ def process_kit_data(smokescreen_properties: dict) -> list:
     return device_ids
 
 
-def split_fit_kits(kit_id_df: pd.DataFrame, smokescreen_properties: dict) -> pd.DataFrame:
+def split_fit_kits(
+    kit_id_df: pd.DataFrame, smokescreen_properties: dict
+) -> pd.DataFrame:
     """
     This method splits the dataframe into two, 1 normal and 1 abnormal
+    Args:
+        kit_id_df (pd.DataFrame): A dataframe containing fit kit IDs.
+        smokescreen_properties (dict): A dictionary containing the number of normal and
+            abnormal fit kits to split. It should include the keys:
+            - "c3_eng_number_of_normal_fit_kits" (str): Number of normal fit kits.
+            - "c3_eng_number_of_abnormal_fit_kits" (str): Number of abnormal fit kits.
+
+    Returns:
+        tuple: A tuple containing two dataframes:
+            - normal_fit_kit_df (pd.DataFrame): Dataframe containing normal fit kits.
+            - abnormal_fit_kit_df (pd.DataFrame): Dataframe containing abnormal fit kits.
     """
     number_of_normal = int(smokescreen_properties["c3_eng_number_of_normal_fit_kits"])
     number_of_abnormal = int(