Feature/bcss 21168 repo improvements (#134)

<!-- markdownlint-disable-next-line first-line-heading -->
## Description

<!-- Describe your changes in detail. -->
This PR has the following changes:
Moving he functions in oracle_specific_dunctions.py into more concise
files in the oracle_specific_functions_folder
- This has been documented in Oracle.md wit ha table showcasing where
each function is

Organising the classes into more specific sub folders. 
- This is all tracked on confluence:
https://nhsd-confluence.digital.nhs.uk/spaces/BCS/pages/1176510399/BCSS+Playwright+Classes+Folder+Structure

Converting classes into Enum classes / python dataclasses where relevant

Standardizing the capitalization of the criteria values

## Context

<!-- Why is this change required? What problem does it solve? -->
This was done to make the repository easier to navigate and use. 

## 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.

Author: adrianoaru-nhs

.gitleaksignore

@@ -226,3 +226,4 @@ cae84544e2852202f5d0abb9ad18f9d83a0c6d80:subject_criteria_builder/criteria.json:
 60468a7d6f3ff3259616757be85d6f07e62d00b6:subject_criteria_builder/criteria.json:generic-api-key:4210
 145171b9e9d169acb136fc527708c997c9ad9f61:subject_criteria_builder/criteria.json:generic-api-key:4210
 2ccb5e91033934d4818c1efa2eb1696b5511ebc9:subject_criteria_builder/criteria.json:generic-api-key:4210
+145171b9e9d169acb136fc527708c997c9ad9f61:subject_criteria_builder/criteria.json:generic-api-key:4210

classes/address.py

@@ -0,0 +1,48 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Address:
+    """
+    Represents a postal address with up to five address lines and a postcode.
+    Provides methods to format the address as a string.
+    """
+
+    address_line1: str = ""
+    address_line2: str = ""
+    address_line3: str = ""
+    address_line4: str = ""
+    address_line5: str = ""
+    post_code: str = ""
+
+    def set_address_line(self, line_number: int, address_line: str) -> None:
+        """
+        Sets the specified address line (1-5) to the given value.
+
+        Args:
+            line_number (int): The address line number (1-5).
+            address_line (str): The value to set for the address line.
+
+        Raises:
+            ValueError: If line_number is not between 1 and 5.
+        """
+        if not 1 <= line_number <= 5:
+            raise ValueError(
+                f"Invalid line number {line_number}, must be between 1 and 5"
+            )
+
+        setattr(self, f"address_line{line_number}", address_line)
+
+    def __str__(self) -> str:
+        """
+        Returns the formatted address as a single string.
+        """
+        address_parts = [
+            self.address_line1,
+            self.address_line2,
+            self.address_line3,
+            self.address_line4,
+            self.address_line5,
+            self.post_code,
+        ]
+        return ", ".join([part for part in address_parts if part])

classes/address/address.py

@@ -0,0 +1,67 @@
+from enum import Enum
+from typing import Optional
+
+
+class AppointmentSlotType(Enum):
+    """
+    Enum representing appointment slot types, mapped to valid value IDs and descriptions.
+    Provides utility methods for lookup by description (case-sensitive and insensitive) and by valid value ID.
+    """
+
+    COLONOSCOPY_ASSESSMENT = (209028, "Colonoscopy Assessment")
+    BOWEL_SCOPE_AUTOMATIC = (200526, "FS Automatic")
+    BOWEL_SCOPE_MANUAL = (200527, "FS Manual")
+    POSITIVE_ASSESSMENT = (6016, "Positive Assessment")
+    POST_INVESTIGATION = (6017, "Post-Investigation")
+    SURVEILLANCE = (20061, "Surveillance")
+
+    def __init__(self, valid_value_id: int, description: str) -> None:
+        self._valid_value_id = valid_value_id
+        self._description = description
+
+    @property
+    def valid_value_id(self) -> int:
+        """
+        Returns the valid value ID for the appointment slot type.
+        """
+        return self._valid_value_id
+
+    @property
+    def description(self) -> str:
+        """
+        Returns the description for the appointment slot type.
+        """
+        return self._description
+
+    @classmethod
+    def by_description(cls, description: str) -> Optional["AppointmentSlotType"]:
+        """
+        Returns the enum member matching the given description (case-sensitive).
+        """
+        for member in cls:
+            if member.description == description:
+                return member
+        return None
+
+    @classmethod
+    def by_description_case_insensitive(
+        cls, description: str
+    ) -> Optional["AppointmentSlotType"]:
+        """
+        Returns the enum member matching the given description (case-insensitive).
+        """
+        desc_lower = description.lower()
+        for member in cls:
+            if member.description.lower() == desc_lower:
+                return member
+        return None
+
+    @classmethod
+    def by_valid_value_id(cls, valid_value_id: int) -> Optional["AppointmentSlotType"]:
+        """
+        Returns the enum member matching the given valid value ID.
+        """
+        for member in cls:
+            if member.valid_value_id == valid_value_id:
+                return member
+        return None

classes/address_contact_type.py classes/address/address_contact_type.pyclasses/address_contact_type.py renamed to classes/address/address_contact_type.py

@@ -0,0 +1,66 @@
+from enum import Enum
+from typing import Optional
+
+
+class AppointmentStatusType(Enum):
+    """
+    Enum representing appointment status types, mapped to valid value IDs and descriptions.
+    """
+
+    ATTENDED = (6121, "Attended")
+    BOOKED = (6120, "Booked")
+    CANCELLED = (6122, "Cancelled")
+    DID_NOT_ATTEND = (6123, "Did Not Attend")
+
+    def __init__(self, valid_value_id: int, description: str) -> None:
+        self._valid_value_id = valid_value_id
+        self._description = description
+
+    @property
+    def valid_value_id(self) -> int:
+        """
+        Returns the valid value ID for the appointment status type.
+        """
+        return self._valid_value_id
+
+    @property
+    def description(self) -> str:
+        """
+        Returns the description for the appointment status type.
+        """
+        return self._description
+
+    @classmethod
+    def by_description(cls, description: str) -> Optional["AppointmentStatusType"]:
+        """
+        Returns the enum member matching the given description (case-sensitive).
+        """
+        for member in cls:
+            if member.description == description:
+                return member
+        return None
+
+    @classmethod
+    def by_description_case_insensitive(
+        cls, description: str
+    ) -> Optional["AppointmentStatusType"]:
+        """
+        Returns the enum member matching the given description (case-insensitive).
+        """
+        desc_lower = description.lower()
+        for member in cls:
+            if member.description.lower() == desc_lower:
+                return member
+        return None
+
+    @classmethod
+    def by_valid_value_id(
+        cls, valid_value_id: int
+    ) -> Optional["AppointmentStatusType"]:
+        """
+        Returns the enum member matching the given valid value ID.
+        """
+        for member in cls:
+            if member.valid_value_id == valid_value_id:
+                return member
+        return None