Feature/bcss 21007 subject selection query builder fix (#108)

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

<!-- Describe your changes in detail. -->
Fixing some broken methods in the subject selection query builder util
and adding new ones.

## Context

<!-- Why is this change required? What problem does it solve? -->
Allows the subject selection query builder to function as intended and
cover all the use cases that the java version does.

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

classes/asa_grade_type.py

@@ -0,0 +1,89 @@
+from enum import Enum
+from typing import Optional, Dict
+
+
+class ASAGradeType(Enum):
+    """
+    Enum representing ASA grades for colonoscopy assessment scenarios,
+    with valid value IDs and descriptions.
+    """
+
+    IFIT = (17009, "I - Fit")
+    II_RELEVANT_DISEASE = (17010, "II - Relevant disease")
+    III_RESTRICTIVE_DISEASE = (17011, "III - Restrictive disease")
+    IV_LIFE_THREATENING_DISEASE = (17012, "IV - Life threatening disease")
+    V_MORIBUND = (17013, "V - Moribund")
+    NOT_APPLICABLE = (17014, "Not Applicable")
+    NOT_KNOWN = (17015, "Not Known")
+    NULL = (None, "")
+
+    def __init__(self, valid_value_id: Optional[int], description: str):
+        self._valid_value_id: Optional[int] = valid_value_id
+        self._description: str = description
+
+    @property
+    def valid_value_id(self) -> Optional[int]:
+        """Returns the valid value ID for the ASA grade."""
+        return self._valid_value_id
+
+    @property
+    def description(self) -> str:
+        """Returns the description for the ASA grade."""
+        return self._description
+
+    @classmethod
+    def _build_maps(cls) -> None:
+        """
+        Initializes internal lookup maps for ASAGradeType enum members.
+
+        It ensures these maps are built only once per class, using `hasattr` to prevent
+        redundant reinitialization.
+        """
+        if not hasattr(cls, "_descriptions"):
+            cls._descriptions: Dict[str, ASAGradeType] = {}
+            cls._lowercase_descriptions: Dict[str, ASAGradeType] = {}
+            cls._valid_value_ids: Dict[Optional[int], ASAGradeType] = {}
+            for item in cls:
+                cls._descriptions[item.description] = item
+                cls._lowercase_descriptions[item.description.lower()] = item
+                cls._valid_value_ids[item.valid_value_id] = item
+
+    @classmethod
+    def by_description(cls, description: str) -> Optional["ASAGradeType"]:
+        """
+        Returns the ASAGradeType matching the given description.
+        """
+        cls._build_maps()
+        return cls._descriptions.get(description)
+
+    @classmethod
+    def by_description_case_insensitive(
+        cls, description: str
+    ) -> Optional["ASAGradeType"]:
+        """
+        Returns the ASAGradeType matching the given description (case-insensitive).
+        """
+        cls._build_maps()
+        return cls._lowercase_descriptions.get(description.lower())
+
+    @classmethod
+    def by_valid_value_id(
+        cls, valid_value_id: Optional[int]
+    ) -> Optional["ASAGradeType"]:
+        """
+        Returns the ASAGradeType matching the given valid value ID.
+        """
+        cls._build_maps()
+        return cls._valid_value_ids.get(valid_value_id)
+
+    def get_valid_value_id(self) -> Optional[int]:
+        """
+        Returns the valid value ID for the ASA grade.
+        """
+        return self._valid_value_id
+
+    def get_description(self) -> str:
+        """
+        Returns the description for the ASA grade.
+        """
+        return self._description

classes/cancer_treatment_intent.py

@@ -0,0 +1,81 @@
+from enum import Enum
+from typing import Optional, Dict
+
+
+class CancerTreatmentIntent(Enum):
+    """
+    Enum representing types of cancer treatment intent with associated valid value IDs and descriptions.
+    Provides utility methods to retrieve enum instances by description or ID.
+    """
+
+    CURATIVE = (17370, "Curative")
+    PALLIATIVE = (17371, "Palliative")
+    UNCERTAIN = (17372, "Uncertain")
+    NOT_KNOWN = (17373, "Not Known")
+
+    def __init__(self, valid_value_id: int, description: str):
+        self._valid_value_id = valid_value_id
+        self._description = description
+
+    @property
+    def valid_value_id(self) -> int:
+        """Returns the valid value ID for the treatment given."""
+        return self._valid_value_id
+
+    @property
+    def description(self) -> str:
+        """Returns the description for the treatment given."""
+        return self._description
+
+    @classmethod
+    def _build_maps(cls) -> None:
+        """
+        Initializes internal lookup maps for CanterTreatmentIntent enum members.
+
+        It ensures these maps are built only once per class, using `hasattr` to prevent
+        redundant reinitialization.
+        """
+        if not hasattr(cls, "_descriptions"):
+            cls._descriptions: Dict[str, CancerTreatmentIntent] = {}
+            cls._lowercase_descriptions: Dict[str, CancerTreatmentIntent] = {}
+            cls._valid_value_ids: Dict[int, CancerTreatmentIntent] = {}
+            for item in cls:
+                cls._descriptions[item.description] = item
+                cls._lowercase_descriptions[item.description.lower()] = item
+                cls._valid_value_ids[item.valid_value_id] = item
+
+    @classmethod
+    def by_description(cls, description: str) -> Optional["CancerTreatmentIntent"]:
+        """
+        Returns the CancerTreatmentIntent matching the given description.
+        """
+        cls._build_maps()
+        return cls._descriptions.get(description)
+
+    @classmethod
+    def by_description_case_insensitive(
+        cls, description: str
+    ) -> Optional["CancerTreatmentIntent"]:
+        """
+        Returns the CancerTreatmentIntent matching the given description (case-insensitive).
+        """
+        cls._build_maps()
+        return cls._lowercase_descriptions.get(description.lower())
+
+    @classmethod
+    def by_valid_value_id(
+        cls, valid_value_id: int
+    ) -> Optional["CancerTreatmentIntent"]:
+        """
+        Returns the CancerTreatmentIntent matching the given valid value ID.
+        """
+        cls._build_maps()
+        return cls._valid_value_ids.get(valid_value_id)
+
+    def get_id(self) -> int:
+        """Returns the valid value ID for the CancerTreatmentIntent given."""
+        return self._valid_value_id
+
+    def get_description(self) -> str:
+        """Returns the description for the CancerTreatmentIntent given."""
+        return self._description

classes/diagnosis_date_reason_type.py

@@ -0,0 +1,103 @@
+from enum import Enum
+from typing import Optional, Dict
+
+
+class DiagnosisDateReasonType(Enum):
+    """
+    Enum representing diagnosis date reasons with valid value IDs and descriptions.
+    """
+
+    TWO_DNAS_OF_COLONOSCOPY_ASSESSMENT_APPT = (
+        305521,
+        "2 DNAs of colonoscopy assessment appt",
+    )
+    INCORRECT_INFORMATION_PREVIOUSLY_ENTERED = (
+        305501,
+        "Incorrect information previously entered",
+    )
+    OTHER = (305500, "Other")
+    PATIENT_CHOICE = (305522, "Patient choice")
+    PATIENT_COULD_NOT_BE_CONTACTED = (305505, "Patient could not be contacted")
+    PATIENT_DECEASED = (305503, "Patient deceased")
+    PATIENT_DECLINED_ALL_APPOINTMENTS = (305520, "Patient declined all appointments")
+    PATIENT_EMIGRATED = (305504, "Patient emigrated")
+    REOPENED_OLD_EPISODE_DATE_UNKNOWN = (305502, "Reopened old episode, date unknown")
+    SSPI_UPDATE_PATIENT_DECEASED = (305525, "SSPI update - patient deceased")
+    SSPI_UPDATE_PATIENT_EMIGRATED = (305524, "SSPI update - patient emigrated")
+    SYSTEM_CLOSURE_AFTER_NO_INPUT_OF_DIAGNOSIS_DATE = (
+        305519,
+        "System closure after no input of diagnosis date",
+    )
+    NULL = (None, "NULL")
+    NOT_NULL = (None, "NOT NULL")
+
+    def __init__(self, valid_value_id: Optional[int], description: str):
+        self._valid_value_id: Optional[int] = valid_value_id
+        self._description: str = description
+
+    @property
+    def valid_value_id(self) -> Optional[int]:
+        """Returns the valid value ID for the diagnosis date reason."""
+        return self._valid_value_id
+
+    @property
+    def description(self) -> str:
+        """Returns the description for the diagnosis date reason."""
+        return self._description
+
+    @classmethod
+    def _build_maps(cls) -> None:
+        """
+        Initializes internal lookup maps for DiagnosisDateReasonType enum members.
+
+        It ensures these maps are built only once per class, using `hasattr` to prevent
+        redundant reinitialization.
+        """
+        if not hasattr(cls, "_descriptions"):
+            cls._descriptions: Dict[str, DiagnosisDateReasonType] = {}
+            cls._lowercase_descriptions: Dict[str, DiagnosisDateReasonType] = {}
+            cls._valid_value_ids: Dict[Optional[int], DiagnosisDateReasonType] = {}
+            for item in cls:
+                cls._descriptions[item.description] = item
+                cls._lowercase_descriptions[item.description.lower()] = item
+                cls._valid_value_ids[item.valid_value_id] = item
+
+    @classmethod
+    def by_description(cls, description: str) -> Optional["DiagnosisDateReasonType"]:
+        """
+        Returns the DiagnosisDateReasonType matching the given description.
+        """
+        cls._build_maps()
+        return cls._descriptions.get(description)
+
+    @classmethod
+    def by_description_case_insensitive(
+        cls, description: str
+    ) -> Optional["DiagnosisDateReasonType"]:
+        """
+        Returns the DiagnosisDateReasonType matching the given description (case-insensitive).
+        """
+        cls._build_maps()
+        return cls._lowercase_descriptions.get(description.lower())
+
+    @classmethod
+    def by_valid_value_id(
+        cls, valid_value_id: Optional[int]
+    ) -> Optional["DiagnosisDateReasonType"]:
+        """
+        Returns the DiagnosisDateReasonType matching the given valid value ID.
+        """
+        cls._build_maps()
+        return cls._valid_value_ids.get(valid_value_id)
+
+    def get_valid_value_id(self) -> Optional[int]:
+        """
+        Returns the valid value ID for the diagnosis date reason.
+        """
+        return self._valid_value_id
+
+    def get_description(self) -> str:
+        """
+        Returns the description for the diagnosis date reason.
+        """
+        return self._description

classes/diagnostic_test_referral_type.py

@@ -0,0 +1,82 @@
+from enum import Enum
+from typing import Optional, Dict
+
+
+class DiagnosticTestReferralType(Enum):
+    """
+    Enum representing diagnostic test referral types with valid value IDs and descriptions.
+    """
+
+    ENDOSCOPIC = (20356, "Endoscopic")
+    RADIOLOGICAL = (20357, "Radiological")
+
+    def __init__(self, valid_value_id: int, description: str):
+        self._valid_value_id: int = valid_value_id
+        self._description: str = description
+
+    @property
+    def valid_value_id(self) -> int:
+        """Returns the valid value ID for the diagnostic test referral type."""
+        return self._valid_value_id
+
+    @property
+    def description(self) -> str:
+        """Returns the description for the diagnostic test referral type."""
+        return self._description
+
+    @classmethod
+    def _build_maps(cls) -> None:
+        """
+        Initializes internal lookup maps for DiagnosticTestReferralType enum members.
+
+        It ensures these maps are built only once per class, using `hasattr` to prevent
+        redundant reinitialization.
+        """
+        if not hasattr(cls, "_descriptions"):
+            cls._descriptions: Dict[str, DiagnosticTestReferralType] = {}
+            cls._lowercase_descriptions: Dict[str, DiagnosticTestReferralType] = {}
+            cls._valid_value_ids: Dict[int, DiagnosticTestReferralType] = {}
+            for item in cls:
+                cls._descriptions[item.description] = item
+                cls._lowercase_descriptions[item.description.lower()] = item
+                cls._valid_value_ids[item.valid_value_id] = item
+
+    @classmethod
+    def by_description(cls, description: str) -> Optional["DiagnosticTestReferralType"]:
+        """
+        Returns the DiagnosticTestReferralType matching the given description.
+        """
+        cls._build_maps()
+        return cls._descriptions.get(description)
+
+    @classmethod
+    def by_description_case_insensitive(
+        cls, description: str
+    ) -> Optional["DiagnosticTestReferralType"]:
+        """
+        Returns the DiagnosticTestReferralType matching the given description (case-insensitive).
+        """
+        cls._build_maps()
+        return cls._lowercase_descriptions.get(description.lower())
+
+    @classmethod
+    def by_valid_value_id(
+        cls, valid_value_id: int
+    ) -> Optional["DiagnosticTestReferralType"]:
+        """
+        Returns the DiagnosticTestReferralType matching the given valid value ID.
+        """
+        cls._build_maps()
+        return cls._valid_value_ids.get(valid_value_id)
+
+    def get_id(self) -> int:
+        """
+        Returns the valid value ID for the diagnostic test referral type.
+        """
+        return self._valid_value_id
+
+    def get_description(self) -> str:
+        """
+        Returns the description for the diagnostic test referral type.
+        """
+        return self._description