Feature/bcss 20679 selenium to playwright subject selection query builder (#97)

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

<!-- Describe your changes in detail. -->
Adding a new util to be able to generate SQL queries to be used as part
of the selenium to playwright migration.

## Context

<!-- Why is this change required? What problem does it solve? -->
Instead of writing out a new SQL query for each bit of test data needed
a generic utility can be used at achieve the same effect.

## Type of changes

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

- [ ] 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
- [x] I have added tests to cover my changes (where appropriate)
- [x] I have updated the documentation accordingly
- [x] 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: AndyG <[email protected]>
Co-authored-by: vidhya-chandra1 <[email protected]>

Author: 3 people

classes/address_contact_type.py

@@ -0,0 +1,64 @@
+from enum import Enum
+from typing import Optional
+
+
+class AddressContactType(Enum):
+    """
+    Enum representing the type of address contact for a subject.
+
+    Attributes:
+        WORK: Represents a work address contact type.
+        HOME: Represents a home address contact type.
+    """
+
+    WORK = (13056, "WORK")
+    HOME = (13057, "HOME")
+
+    def __init__(self, valid_value_id: int, allowed_value: str):
+        """
+        Initialize an AddressContactType enum member.
+
+        Args:
+            valid_value_id (int): The unique identifier for the address contact type.
+            allowed_value (str): The string representation of the address contact type.
+        """
+        self._valid_value_id = valid_value_id
+        self._allowed_value = allowed_value
+
+    @property
+    def valid_value_id(self) -> int:
+        """
+        Returns the unique identifier for the address contact type.
+
+        Returns:
+            int: The valid value ID.
+        """
+        return self._valid_value_id
+
+    @property
+    def allowed_value(self) -> str:
+        """
+        Returns the string representation of the address contact type.
+
+        Returns:
+            str: The allowed value.
+        """
+        return self._allowed_value
+
+    @classmethod
+    def by_valid_value_id(
+        cls, address_contact_type_id: int
+    ) -> Optional["AddressContactType"]:
+        """
+        Returns the AddressContactType enum member matching the given valid value ID.
+
+        Args:
+            address_contact_type_id (int): The valid value ID to search for.
+
+        Returns:
+            Optional[AddressContactType]: The matching enum member, or None if not found.
+        """
+        return next(
+            (item for item in cls if item.valid_value_id == address_contact_type_id),
+            None,
+        )

classes/address_type.py

@@ -0,0 +1,61 @@
+from enum import Enum
+from typing import Optional
+
+
+class AddressType(Enum):
+    """
+    Enum representing the type of address for a subject.
+
+    Attributes:
+        MAIN_REGISTERED_ADDRESS: Represents the main registered address (code "H").
+        TEMPORARY_ADDRESS: Represents a temporary address (code "T").
+    """
+
+    MAIN_REGISTERED_ADDRESS = (13042, "H")
+    TEMPORARY_ADDRESS = (13043, "T")
+
+    def __init__(self, valid_value_id: int, allowed_value: str):
+        """
+        Initialize an AddressType enum member.
+
+        Args:
+            valid_value_id (int): The unique identifier for the address type.
+            allowed_value (str): The string representation of the address type.
+        """
+        self._valid_value_id = valid_value_id
+        self._allowed_value = allowed_value
+
+    @property
+    def valid_value_id(self) -> int:
+        """
+        Returns the unique identifier for the address type.
+
+        Returns:
+            int: The valid value ID.
+        """
+        return self._valid_value_id
+
+    @property
+    def allowed_value(self) -> str:
+        """
+        Returns the string representation of the address type.
+
+        Returns:
+            str: The allowed value.
+        """
+        return self._allowed_value
+
+    @classmethod
+    def by_valid_value_id(cls, address_type_id: int) -> Optional["AddressType"]:
+        """
+        Returns the AddressType enum member matching the given valid value ID.
+
+        Args:
+            address_type_id (int): The valid value ID to search for.
+
+        Returns:
+            Optional[AddressType]: The matching enum member, or None if not found.
+        """
+        return next(
+            (item for item in cls if item.valid_value_id == address_type_id), None
+        )

classes/appointment_status_type.py

@@ -0,0 +1,39 @@
+class AppointmentStatusType:
+    """
+    Utility class for mapping descriptive appointment statuses to internal IDs.
+
+    This class provides a mapping between human-readable appointment status descriptions
+    (such as "booked", "attended", "cancelled", "dna") and their corresponding internal
+    integer IDs used in the system.
+
+    Methods:
+        get_id(description: str) -> int:
+            Returns the internal ID for a given appointment status description.
+            Raises ValueError if the description is not recognized.
+    """
+
+    _mapping = {
+        "booked": 2001,
+        "attended": 2002,
+        "cancelled": 2003,
+        "dna": 2004,  # Did Not Attend
+    }
+
+    @classmethod
+    def get_id(cls, description: str) -> int:
+        """
+        Returns the internal ID for a given appointment status description.
+
+        Args:
+            description (str): The appointment status description (e.g., "booked").
+
+        Returns:
+            int: The internal ID corresponding to the description.
+
+        Raises:
+            ValueError: If the description is not recognized.
+        """
+        key = description.strip().lower()
+        if key not in cls._mapping:
+            raise ValueError(f"Unknown appointment status: {description}")
+        return cls._mapping[key]

classes/appointments_slot_type.py

@@ -0,0 +1,38 @@
+class AppointmentSlotType:
+    """
+    Utility class for mapping symbolic appointment slot types to their internal IDs.
+
+    This class provides a mapping between human-readable appointment slot type descriptions
+    (such as "clinic", "phone", "video") and their corresponding internal integer IDs used in the system.
+
+    Methods:
+        get_id(description: str) -> int:
+            Returns the internal ID for a given appointment slot type description.
+            Raises ValueError if the description is not recognized.
+    """
+
+    _mapping = {
+        "clinic": 1001,
+        "phone": 1002,
+        "video": 1003,
+        # Add more mappings here as needed
+    }
+
+    @classmethod
+    def get_id(cls, description: str) -> int:
+        """
+        Returns the internal ID for a given appointment slot type description.
+
+        Args:
+            description (str): The appointment slot type description (e.g., "clinic").
+
+        Returns:
+            int: The internal ID corresponding to the description.
+
+        Raises:
+            ValueError: If the description is not recognized.
+        """
+        key = description.strip().lower()
+        if key not in cls._mapping:
+            raise ValueError(f"Unknown appointment slot type: {description}")
+        return cls._mapping[key]

classes/bowel_scope_dd_reason_for_change_type.py

@@ -0,0 +1,126 @@
+from enum import Enum
+from typing import Optional, Dict
+
+
+class BowelScopeDDReasonForChangeType(Enum):
+    """
+    Enum representing reasons for change to Bowel Scope Due Date.
+
+    Attributes:
+        Ceased: Ceased
+        DateOfBirthAmendment: Date of birth amendment
+        EligibleToBeInvitedForFsScreening: Eligible to be invited for FS Screening
+        FsScreeningEpisodeOpened: FS Screening episode opened
+        MultipleDateOfBirthChanges: Multiple Date of Birth Changes
+        NoLongerEligibleToBeInvitedForFsScreening: No longer eligible to be invited for FS Screening
+        ReopenedFsEpisode: Reopened FS Episode
+        SeekingFurtherData: Seeking further data
+    """
+
+    Ceased = (200669, "Ceased")
+    DateOfBirthAmendment = (205266, "Date of birth amendment")
+    EligibleToBeInvitedForFsScreening = (
+        200685,
+        "Eligible to be invited for FS Screening",
+    )
+    FsScreeningEpisodeOpened = (205002, "FS Screening episode opened")
+    MultipleDateOfBirthChanges = (202426, "Multiple Date of Birth Changes")
+    NoLongerEligibleToBeInvitedForFsScreening = (
+        200668,
+        "No longer eligible to be invited for FS Screening",
+    )
+    ReopenedFsEpisode = (205012, "Reopened FS Episode")
+    SeekingFurtherData = (200670, "Seeking further data")
+
+    def __init__(self, valid_value_id: int, description: str):
+        """
+        Initialize a BowelScopeDDReasonForChangeType enum member.
+
+        Args:
+            valid_value_id (int): The unique identifier for the reason.
+            description (str): The string description of the reason.
+        """
+        self._valid_value_id: int = valid_value_id
+        self._description: str = description
+
+    @property
+    def valid_value_id(self) -> int:
+        """
+        Returns the unique identifier for the reason.
+
+        Returns:
+            int: The valid value ID.
+        """
+        return self._valid_value_id
+
+    @property
+    def description(self) -> str:
+        """
+        Returns the string description of the reason.
+
+        Returns:
+            str: The description.
+        """
+        return self._description
+
+    @classmethod
+    def _descriptions(cls) -> Dict[str, "BowelScopeDDReasonForChangeType"]:
+        """
+        Returns a mapping from description to enum member.
+
+        Returns:
+            Dict[str, BowelScopeDDReasonForChangeType]: Mapping from description to enum member.
+        """
+        return {item.description: item for item in cls}
+
+    @classmethod
+    def _lowercase_descriptions(cls) -> Dict[str, "BowelScopeDDReasonForChangeType"]:
+        """
+        Returns a mapping from lowercase description to enum member.
+
+        Returns:
+            Dict[str, BowelScopeDDReasonForChangeType]: Mapping from lowercase description to enum member.
+        """
+        return {item.description.lower(): item for item in cls}
+
+    @classmethod
+    def _valid_value_ids(cls) -> Dict[int, "BowelScopeDDReasonForChangeType"]:
+        """
+        Returns a mapping from valid value ID to enum member.
+
+        Returns:
+            Dict[int, BowelScopeDDReasonForChangeType]: Mapping from valid value ID to enum member.
+        """
+        return {item.valid_value_id: item for item in cls}
+
+    @classmethod
+    def by_description(
+        cls, description: Optional[str]
+    ) -> Optional["BowelScopeDDReasonForChangeType"]:
+        """
+        Returns the enum member matching the given description (case-insensitive).
+
+        Args:
+            description (Optional[str]): The description to search for.
+
+        Returns:
+            Optional[BowelScopeDDReasonForChangeType]: The matching enum member, or None if not found.
+        """
+        if description is None:
+            return None
+        return cls._lowercase_descriptions().get(description.lower())
+
+    @classmethod
+    def by_valid_value_id(
+        cls, valid_value_id: int
+    ) -> Optional["BowelScopeDDReasonForChangeType"]:
+        """
+        Returns the enum member matching the given valid value ID.
+
+        Args:
+            valid_value_id (int): The valid value ID to search for.
+
+        Returns:
+            Optional[BowelScopeDDReasonForChangeType]: The matching enum member, or None if not found.
+        """
+        return cls._valid_value_ids().get(valid_value_id)

classes/ceased_confirmation_details.py

@@ -0,0 +1,40 @@
+from enum import Enum
+from typing import Optional
+
+
+class CeasedConfirmationDetails(Enum):
+    """
+    Enum representing ceased confirmation details for a subject.
+
+    Members:
+        NULL: Represents a null ceased confirmation detail.
+        NOT_NULL: Represents a non-null ceased confirmation detail.
+    """
+
+    NULL = "null"
+    NOT_NULL = "not null"
+
+    @classmethod
+    def by_description(cls, description: str) -> Optional["CeasedConfirmationDetails"]:
+        """
+        Returns the enum member matching the given description.
+
+        Args:
+            description (str): The description to search for.
+
+        Returns:
+            Optional[CeasedConfirmationDetails]: The matching enum member, or None if not found.
+        """
+        for item in cls:
+            if item.value == description:
+                return item
+        return None
+
+    def get_description(self) -> str:
+        """
+        Returns the string description of the ceased confirmation detail.
+
+        Returns:
+            str: The description value.
+        """
+        return self.value