Skip to content

Commit 106c205

Browse files
adrianoaru-nhsadrianoaru-nhs
authored
Feature/bcss 20626 fit kit markdown updates (#91)
<!-- markdownlint-disable-next-line first-line-heading --> ## Description <!-- Describe your changes in detail. --> Combining two markdown documents as their respective util files were combined into one ## Context <!-- Why is this change required? What problem does it solve? --> Makes the guide easier to understand what utility file it is referring to. ## 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) - [ ] 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.
1 parent cc54a4c commit 106c205

File tree

4 files changed

+156
-141
lines changed

4 files changed

+156
-141
lines changed

‎docs/utility-guides/FitKit.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Utility Guide: Fit Kit Utility
2+
3+
This guide covers both the Fit Kit Generation and Fit Kit Logged utilities, which together provide methods to generate, manage, and process FIT test kits for testing purposes.
4+
5+
## Table of Contents
6+
7+
- [Utility Guide: Fit Kit Utility](#utility-guide-fit-kit-utility)
8+
- [Table of Contents](#table-of-contents)
9+
- [Fit Kit Generation Utility](#fit-kit-generation-utility)
10+
- [Overview](#overview)
11+
- [How to Use](#how-to-use)
12+
- [Required Arguments](#required-arguments)
13+
- [Key Methods](#key-methods)
14+
- [Example Usage](#example-usage)
15+
- [Fit Kit Logged Utility](#fit-kit-logged-utility)
16+
- [Overview](#overview-1)
17+
- [How to Use](#how-to-use-1)
18+
- [Required Arguments](#required-arguments-1)
19+
- [Key Methods](#key-methods-1)
20+
- [Example Usage](#example-usage-1)
21+
- [1st Example - Basic](#1st-example---basic)
22+
- [2nd Example - Compartment 3](#2nd-example---compartment-3)
23+
24+
---
25+
26+
## Fit Kit Generation Utility
27+
28+
### Overview
29+
30+
The Fit Kit Generation Utility (`FitKitGeneration` class) provides methods to generate and manage FIT test kits for testing purposes. It retrieves kit IDs from the database, calculates check digits, and formats them as FIT Device IDs ready for use in tests.
31+
32+
### How to Use
33+
34+
Import the `FitKitGeneration` class from `utils/fit_kit.py` and use its methods to generate and process FIT kit IDs.
35+
36+
```python
37+
from utils.fit_kit import FitKitGeneration
38+
```
39+
40+
### Required Arguments
41+
42+
- `create_fit_id_df`: Requires `tk_type_id` (int), `hub_id` (int), and `no_of_kits_to_retrieve` (int).
43+
44+
### Key Methods
45+
46+
1. **`create_fit_id_df(tk_type_id: int, hub_id: int, no_of_kits_to_retrieve: int) -> pd.DataFrame`**
47+
- Retrieves kit IDs from the database, calculates check digits, and generates FIT Device IDs.
48+
- **Returns:** A pandas DataFrame with the processed FIT Device IDs.
49+
50+
2. **`calculate_check_digit(kit_id: str) -> str`**
51+
- Calculates and appends a check digit to the given kit ID.
52+
53+
3. **`convert_kit_id_to_fit_device_id(kit_id: str) -> str`**
54+
- Converts a kit ID into a FIT Device ID by appending an expiry date and a fixed suffix.
55+
56+
> **Tip:**
57+
> To obtain a pandas DataFrame containing a list of FIT Kits to use, you only need to call the `create_fit_id_df` method. This method internally calls the other two methods to generate the correct check digits and expiration tags.
58+
59+
### Example Usage
60+
61+
```python
62+
from utils.fit_kit import FitKitGeneration
63+
64+
def example_usage() -> None:
65+
tk_type_id = 2
66+
hub_id = 101
67+
no_of_kits_to_retrieve = 2
68+
69+
fit_kit_gen = FitKitGeneration()
70+
fit_kit_df = fit_kit_gen.create_fit_id_df(tk_type_id, hub_id, no_of_kits_to_retrieve)
71+
print("Processed FIT Kit DataFrame:")
72+
print(fit_kit_df)
73+
```
74+
75+
---
76+
77+
## Fit Kit Logged Utility
78+
79+
### Overview
80+
81+
The Fit Kit Logged Utility (`FitKitLogged` class) provides methods to retrieve test data (fit kit test results) used by the compartment 3 tests, and splits them into two dataframes: one for 'normal' results and one for 'abnormal' results.
82+
83+
### How to Use
84+
85+
Import the `FitKitLogged` class from `utils/fit_kit.py` and use its methods to process and split FIT kit data.
86+
87+
```python
88+
from utils.fit_kit import FitKitLogged
89+
```
90+
91+
### Required Arguments
92+
93+
- `process_kit_data`: Requires `smokescreen_properties` (dict)
94+
- `split_fit_kits`: Requires `kit_id_df` (pd.DataFrame), `smokescreen_properties` (dict)
95+
96+
### Key Methods
97+
98+
1. **`process_kit_data(smokescreen_properties: dict) -> list`**
99+
- Retrieves test data for compartment 3 and splits it into normal and abnormal kits using `split_fit_kits`.
100+
- **Returns:** A list of tuples, each containing a device ID (str) and a `boolean` flag (`True` for normal, `False` for abnormal).
101+
102+
2. **`split_fit_kits(kit_id_df: pd.DataFrame, smokescreen_properties: dict) -> tuple[pd.DataFrame, pd.DataFrame]`**
103+
- Splits the DataFrame into two: one for normal kits and one for abnormal kits, based on the numbers specified in `smokescreen_properties`.
104+
- **Returns:** A tuple containing two DataFrames: `(normal_fit_kit_df, abnormal_fit_kit_df)`.
105+
106+
> **How it works:**
107+
>
108+
> - The number of normal and abnormal kits is determined by the `c3_eng_number_of_normal_fit_kits` and `c3_eng_number_of_abnormal_fit_kits` keys in the `smokescreen_properties` dictionary.
109+
> - The utility retrieves the required number of kits, splits them, and returns device IDs with their normal/abnormal status.
110+
111+
### Example Usage
112+
113+
#### 1st Example - Basic
114+
115+
This example is showing how the utility can be used to get a pandas `dataframe` containing a list of normal / abnormal kits.
116+
117+
```python
118+
from utils.fit_kit import FitKitLogged
119+
120+
def test_example_usage(smokescreen_properties: dict) -> None:
121+
fit_kit_logged = FitKitLogged()
122+
# Retrieve and split FIT kit data
123+
device_ids = fit_kit_logged.process_kit_data(smokescreen_properties)
124+
# Example: process device IDs and their normal/abnormal status
125+
for device_id, is_normal in device_ids:
126+
print(f"Device ID: {device_id}, Normal: {is_normal}")
127+
```
128+
129+
#### 2nd Example - Compartment 3
130+
131+
This example is showing how we are using this utility in compartment 3.
132+
133+
```python
134+
from utils.fit_kit import FitKitLogged
135+
from utils.oracle.oracle_specific_functions import update_kit_service_management_entity
136+
137+
def test_compartment_3(page: Page, smokescreen_properties: dict):
138+
device_ids = FitKitLogged().process_kit_data(smokescreen_properties)
139+
nhs_numbers = []
140+
normal_flags = []
141+
142+
for device_id, is_normal in device_ids:
143+
nhs_number = update_kit_service_management_entity(
144+
device_id, is_normal, smokescreen_properties
145+
)
146+
nhs_numbers.append(nhs_number)
147+
normal_flags.append(is_normal)
148+
```
149+
150+
---
151+
152+
For more details on each method's implementation, refer to the source code in `utils/fit_kit.py`.

‎docs/utility-guides/FitKitGeneration.md‎

Lines changed: 0 additions & 68 deletions
This file was deleted.

‎docs/utility-guides/FitKitLogged.md‎

Lines changed: 0 additions & 71 deletions
This file was deleted.

‎utils/fit_kit.py‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
1-
from oracle.oracle_specific_functions import get_kit_id_logged_from_db
2-
from utils.oracle.oracle_specific_functions import get_kit_id_from_db
1+
from utils.oracle.oracle_specific_functions import (
2+
get_kit_id_from_db,
3+
get_kit_id_logged_from_db,
4+
)
35
from pages.base_page import BasePage
46
from datetime import datetime
57
import logging

0 commit comments

Comments
 (0)