eli-579 removing comments and adding info to docstring, where appropriate

Author: eddalmond1

src/eligibility_signposting_api/services/processors/derived_values/add_days_handler.py

@@ -27,7 +27,6 @@ class AddDaysHandler(DerivedValueHandler):
 
     function_name: str = "ADD_DAYS"
 
-    # Mapping of derived attribute names to their source attributes
     DERIVED_ATTRIBUTE_SOURCES: ClassVar[dict[str, str]] = {
         "NEXT_DOSE_DUE": "LAST_SUCCESSFUL_DATE",
     }
@@ -62,7 +61,6 @@ def get_source_attribute(self, target_attribute: str, function_args: str | None
             The source attribute name (e.g., 'LAST_SUCCESSFUL_DATE')
         """
         if function_args and "," in function_args:
-            # Extract source from args if present (second argument)
             parts = [p.strip() for p in function_args.split(",")]
             if len(parts) > 1 and parts[1]:
                 return parts[1].upper()
@@ -98,6 +96,9 @@ def calculate(self, context: DerivedValueContext) -> str:
     def _find_source_date(self, context: DerivedValueContext) -> str | None:
         """Find the source date value from person data.
 
+        For PERSON-level attributes, looks for ATTRIBUTE_TYPE == "PERSON".
+        For TARGET-level attributes, looks for ATTRIBUTE_TYPE == context.attribute_name (e.g., "COVID").
+
         Args:
             context: The derived value context
 
@@ -108,8 +109,6 @@ def _find_source_date(self, context: DerivedValueContext) -> str | None:
         if not source_attr:
             return None
 
-        # For PERSON-level attributes, look for ATTRIBUTE_TYPE == "PERSON"
-        # For TARGET-level attributes, look for ATTRIBUTE_TYPE == context.attribute_name (e.g., "COVID")
         attribute_type_to_match = "PERSON" if context.attribute_level == "PERSON" else context.attribute_name
 
         for attribute in context.person_data:
@@ -132,7 +131,6 @@ def _get_days_to_add(self, context: DerivedValueContext) -> int:
         Returns:
             Number of days to add
         """
-        # Priority 1: Token argument (if non-empty)
         if context.function_args:
             args = context.function_args.split(",")[0].strip()
             if args:
@@ -142,11 +140,9 @@ def _get_days_to_add(self, context: DerivedValueContext) -> int:
                     message = f"Invalid days argument '{args}' for ADD_DAYS function. Expected an integer."
                     raise ValueError(message) from e
 
-        # Priority 2: Vaccine-specific configuration
         if context.attribute_name in self.vaccine_type_days:
             return self.vaccine_type_days[context.attribute_name]
 
-        # Priority 3: Default
         return self.default_days
 
     def _add_days_to_date(self, date_str: str, days: int) -> datetime:

src/eligibility_signposting_api/services/processors/token_processor.py

@@ -90,18 +90,15 @@ def get_token_replacement(token: str, person_data: list[dict], present_attribute
         if TokenProcessor.should_replace_with_empty(parsed_token, present_attributes):
             return ""
 
-        # Check if this is a derived value (has a function like ADD_DAYS)
         if parsed_token.function_name:
             return TokenProcessor.get_derived_value(parsed_token, person_data, present_attributes, token)
 
-        # For non-derived tokens, validate that target attributes are allowed
         TokenProcessor.validate_target_attribute(parsed_token, token)
 
         found_attribute, key_to_replace = TokenProcessor.find_matching_attribute(parsed_token, person_data)
 
         if not found_attribute or not key_to_replace:
             TokenProcessor.handle_token_not_found(parsed_token, token)
-            # handle_token_not_found always raises, but the type checker needs help
             msg = "Unreachable"
             raise RuntimeError(msg)  # pragma: no cover
 
@@ -116,6 +113,11 @@ def get_derived_value(
     ) -> str:
         """Calculate a derived value using the registered handler.
 
+        For TARGET level tokens, validates that the condition is allowed before processing.
+        If the vaccine type is not in person data, returns an empty string.
+        For derived values, any target attribute name is allowed (e.g., NEXT_BOOKING_AVAILABLE)
+        since it's just a placeholder that may be surfaced in the future.
+
         Args:
             parsed_token: The parsed token containing function information
             person_data: List of person attribute dictionaries
@@ -139,17 +141,12 @@ def get_derived_value(
             message = f"Unknown function '{function_name}' in token '{token}'."
             raise ValueError(message)
 
-        # For TARGET level tokens, validate the condition is allowed
         if parsed_token.attribute_level == TARGET_ATTRIBUTE_LEVEL:
             is_allowed_condition = parsed_token.attribute_name in ALLOWED_CONDITIONS.__args__
 
-            # If condition is not allowed, raise error
             if not is_allowed_condition:
                 TokenProcessor.handle_token_not_found(parsed_token, token)
 
-            # If vaccine type is not in person data, return empty string
-            # For derived values, any target attribute name is allowed (e.g., NEXT_BOOKING_AVAILABLE)
-            # since it's just a placeholder that may be surfaced in the future
             if parsed_token.attribute_name not in present_attributes:
                 return ""
 
@@ -175,7 +172,6 @@ def get_derived_value(
                 context=context,
             )
         except ValueError as e:
-            # Re-raise with more context
             message = f"Error calculating derived value for token '{token}': {e}"
             raise ValueError(message) from e