Adding part of scenario 11.

Added new classes relating to the person repository
Adding new utils to be able to fetch a person matching a set of criteria
updating investigation dataset utils and apps to reflect new fields

Author: adrianoaru-nhs

classes/date/date_description_utils.py

@@ -0,0 +1,202 @@
+from datetime import datetime, timedelta, date
+from typing import Optional
+import logging
+from classes.date.date_description import DateDescription
+
+
+class DateDescriptionUtils:
+    """
+    Utility class for interpreting and converting date descriptions to Python date objects or formatted strings.
+    """
+
+    DATE_FORMAT_YYYY_MM_DD = "%Y-%m-%d"
+    DATE_FORMAT_DD_MM_YYYY = "%d/%m/%Y"
+
+    @staticmethod
+    def interpret_date(date_field_name: str, date_value: str) -> str:
+        """
+        Interprets a date description and returns a formatted date string (dd/MM/yyyy).
+        If the date cannot be interpreted, returns the original value.
+        """
+        logging.debug(f"interpret_date: {date_field_name}, {date_value}")
+        try:
+            return DateDescriptionUtils.convert_description_to_string_date(
+                date_field_name, date_value, DateDescriptionUtils.DATE_FORMAT_DD_MM_YYYY
+            )
+        except Exception as e:
+            logging.error(f"Could not interpret date: {e}")
+            return date_value
+
+    @staticmethod
+    def convert_description_to_sql_date(
+        which_date: str, date_description: str
+    ) -> Optional[str]:
+        """
+        Converts a date description to an Oracle TO_DATE SQL string.
+        Returns None if the date cannot be interpreted.
+        """
+        logging.debug(
+            f"convert_description_to_sql_date: {which_date}, {date_description}"
+        )
+        return_date_string = None
+        return_date = None
+
+        date_description_words = date_description.split(" ")
+
+        # First handle actual dates
+        if DateDescriptionUtils.is_valid_date(
+            date_description, DateDescriptionUtils.DATE_FORMAT_DD_MM_YYYY
+        ):
+            return_date_string = DateDescriptionUtils.oracle_to_date_function(
+                date_description, "dd/mm/yyyy"
+            )
+        elif DateDescriptionUtils.is_valid_date(
+            date_description, DateDescriptionUtils.DATE_FORMAT_YYYY_MM_DD
+        ):
+            return_date_string = DateDescriptionUtils.oracle_to_date_function(
+                date_description, "yyyy-mm-dd"
+            )
+        elif date_description.endswith(" ago") and len(date_description_words) == 3:
+            return_date = DateDescriptionUtils.convert_description_to_local_date(
+                which_date, date_description
+            )
+        else:
+            # If the date description is in the enum, use the suggested suitable date, plus allow for NULL and NOT NULL
+            enum_val = DateDescription.by_description_case_insensitive(date_description)
+            if enum_val is not None:
+                if enum_val.name == "NULL":
+                    return_date_string = "NULL"
+                elif enum_val.name == "NOT_NULL":
+                    return_date_string = "NOT NULL"
+                else:
+                    return_date = enum_val.suitable_date
+
+        if return_date is not None and return_date_string is None:
+            return_date_string = DateDescriptionUtils.oracle_to_date_function(
+                return_date.strftime(DateDescriptionUtils.DATE_FORMAT_DD_MM_YYYY),
+                "dd/mm/yyyy",
+            )
+
+        return return_date_string
+
+    @staticmethod
+    def convert_description_to_local_date(
+        which_date: str, date_description: str
+    ) -> date:
+        """
+        Converts a date description to a Python date object.
+        Raises ValueError if the description cannot be interpreted.
+        """
+        logging.debug(
+            f"convert_description_to_local_date: {which_date}, {date_description}"
+        )
+        date_description_words = date_description.split(" ")
+
+        # Handle actual dates
+        if DateDescriptionUtils.is_valid_date(
+            date_description, DateDescriptionUtils.DATE_FORMAT_DD_MM_YYYY
+        ):
+            return datetime.strptime(
+                date_description, DateDescriptionUtils.DATE_FORMAT_DD_MM_YYYY
+            ).date()
+        if DateDescriptionUtils.is_valid_date(
+            date_description, DateDescriptionUtils.DATE_FORMAT_YYYY_MM_DD
+        ):
+            return datetime.strptime(
+                date_description, DateDescriptionUtils.DATE_FORMAT_YYYY_MM_DD
+            ).date()
+
+        # Handle relative dates ("ago" or "ahead")
+        if DateDescriptionUtils._is_relative_date(
+            date_description, date_description_words, "ago"
+        ):
+            return DateDescriptionUtils._calculate_relative_date(
+                date_description_words, is_ago=True
+            )
+        if DateDescriptionUtils._is_relative_date(
+            date_description, date_description_words, "ahead"
+        ):
+            return DateDescriptionUtils._calculate_relative_date(
+                date_description_words, is_ago=False
+            )
+
+        # Handle enum-based descriptions
+        enum_val = DateDescription.by_description_case_insensitive(date_description)
+        if enum_val is not None:
+            if enum_val.name in ["NULL", "NOT_NULL"]:
+                raise ValueError(f"Cannot convert '{date_description}' to a date.")
+            if enum_val.suitable_date is not None:
+                return enum_val.suitable_date
+
+        raise ValueError(f"Cannot interpret date description '{date_description}'.")
+
+    @staticmethod
+    def _is_relative_date(date_description, words, suffix):
+        return date_description.endswith(f" {suffix}") and len(words) == 3
+
+    @staticmethod
+    def _calculate_relative_date(words, is_ago):
+        if not words[0].isdigit():
+            raise ValueError(f"Invalid period number in '{' '.join(words)}'")
+        number_of_periods = int(words[0])
+        period_type = words[1]
+        today = date.today()
+        delta_days = DateDescriptionUtils._get_delta_days(
+            number_of_periods, period_type
+        )
+        if is_ago:
+            return today - timedelta(days=delta_days)
+        else:
+            return today + timedelta(days=delta_days)
+
+    @staticmethod
+    def _get_delta_days(number_of_periods, period_type):
+        if period_type in ["year", "years"]:
+            return number_of_periods * 365
+        if period_type in ["month", "months"]:
+            return number_of_periods * 30
+        if period_type in ["week", "weeks"]:
+            return number_of_periods * 7
+        if period_type in ["day", "days"]:
+            return number_of_periods
+        raise ValueError(f"Unknown period type '{period_type}'")
+
+    @staticmethod
+    def convert_description_to_string_date(
+        which_date: str, date_description: str, date_format: str
+    ) -> str:
+        """
+        Converts a date description to a formatted date string.
+        Raises ValueError if the description cannot be interpreted.
+        """
+        logging.debug(
+            f"convert_description_to_string_date: {which_date}, {date_description}, {date_format}"
+        )
+        local_date = DateDescriptionUtils.convert_description_to_local_date(
+            which_date, date_description
+        )
+        return local_date.strftime(date_format)
+
+    @staticmethod
+    def is_valid_date(date_str: str, date_format: str) -> bool:
+        """
+        Checks if the given string is a valid date in the specified format.
+        """
+        try:
+            datetime.strptime(date_str, date_format)
+            return True
+        except ValueError:
+            return False
+
+    @staticmethod
+    def oracle_to_date_function(date_str: str, oracle_format: str) -> str:
+        """
+        Constructs an Oracle TO_DATE function to convert a string to a date.
+        This method formats the date string according to the specified format.
+        Args:
+            date_str (str): The date string to be converted.
+            oracle_format (str): The format in which the date string is provided.
+        Returns:
+            str: The SQL expression for the Oracle TO_DATE function.
+        """
+        return f" TO_DATE( '{date_str}', '{oracle_format}') "

classes/person/person.py

@@ -1,107 +1,49 @@
-import logging
+from dataclasses import dataclass, field
 from typing import Optional
-from classes.subject.gender_type import GenderType
 
 
+@dataclass
 class Person:
     """
-    Represents a person with name, title, gender, and other attributes.
+    Represents a person with identifying and role-related attributes.
+
+    Attributes:
+        person_id (Optional[int]): Unique identifier for the person (PRS ID).
+        surname (Optional[str]): The surname of the person.
+        forenames (Optional[str]): The forenames of the person.
+        registration_code (Optional[str]): The registration code of the person.
+        role_id (Optional[int]): Role identifier (PIO ID). Used to hold one
+            selected role for the person.
     """
 
-    def __init__(self) -> None:
-        self.surname: str = ""
-        self.forename: str = ""
-        self.title: str = ""
-        self.other_forenames: str = ""
-        self.previous_surname: str = ""
-        self.gender: Optional[GenderType] = GenderType.NOT_KNOWN
+    person_id: Optional[int] = field(default=None)
+    surname: Optional[str] = field(default=None)
+    forenames: Optional[str] = field(default=None)
+    registration_code: Optional[str] = field(default=None)
+    role_id: Optional[int] = field(default=None)
 
-    def get_full_name(self) -> str:
+    @property
+    def full_name(self) -> str:
         """
-        Returns the full name of the person, including title, forename, and surname.
-        """
-        return f"{self.title} {self.forename} {self.surname}"
-
-    def __str__(self) -> str:
-        """
-        Returns a string representation of the person, including gender.
-        """
-        return f"{self.title} {self.forename} {self.surname} (gender={self.gender})"
-
-    def get_surname(self) -> str:
-        """
-        Returns the surname of the person.
-        """
-        return self.surname
-
-    def set_surname(self, surname: str) -> None:
-        """
-        Sets the surname of the person.
-        """
-        logging.debug("set surname")
-        self.surname = surname
-
-    def get_forename(self) -> str:
-        """
-        Returns the forename of the person.
-        """
-        return self.forename
-
-    def set_forename(self, forename: str) -> None:
-        """
-        Sets the forename of the person.
-        """
-        logging.debug("set forename")
-        self.forename = forename
-
-    def get_title(self) -> str:
-        """
-        Returns the title of the person.
-        """
-        return self.title
-
-    def set_title(self, title: str) -> None:
-        """
-        Sets the title of the person.
-        """
-        logging.debug("set title")
-        self.title = title
-
-    def get_other_forenames(self) -> str:
-        """
-        Returns other forenames of the person.
-        """
-        return self.other_forenames
-
-    def set_other_forenames(self, other_forenames: str) -> None:
-        """
-        Sets other forenames of the person.
-        """
-        logging.debug("set other_forenames")
-        self.other_forenames = other_forenames
+        Get the full name of the person.
 
-    def get_previous_surname(self) -> str:
-        """
-        Returns the previous surname of the person.
+        Returns:
+            str: The concatenation of forenames and surname, or an empty string if missing.
         """
-        return self.previous_surname
+        parts = [self.forenames or "", self.surname or ""]
+        return " ".join(p for p in parts if p).strip()
 
-    def set_previous_surname(self, previous_surname: str) -> None:
-        """
-        Sets the previous surname of the person.
-        """
-        logging.debug("set previous_surname")
-        self.previous_surname = previous_surname
-
-    def get_gender(self) -> Optional[GenderType]:
-        """
-        Returns the gender of the person.
+    def __str__(self) -> str:
         """
-        return self.gender
+        Get a string representation of the person object.
 
-    def set_gender(self, gender: GenderType) -> None:
-        """
-        Sets the gender of the person.
+        Returns:
+            str: String with field values, similar to the Java `toString` implementation.
         """
-        logging.debug("set gender")
-        self.gender = gender
+        return (
+            f"User [personId={self.person_id}, "
+            f"surname={self.surname}, "
+            f"forenames={self.forenames}, "
+            f"registrationCode={self.registration_code}, "
+            f"roleId={self.role_id}]"
+        )